Interfaze as Tools

copy markdown

You can wire any Interfaze capability directly as a tool inside your existing agent. Your main model decides when to call it, Interfaze runs the task, and the result comes back as clean structured JSON — no extra infrastructure required.

This works by combining run-task mode with your SDK's tool-calling primitives.

Available tasks

Task	What it does
`ocr`	Extract text and structured data from images or documents
`object_detection`	Detect and locate objects in images
`web_search`	Real-time web search with sources
`scraper`	Extract structured content from any web page
`speech_to_text`	Transcribe audio files
`translate`	Translate text between languages

The helper function

Every example below uses this helper. It calls Interfaze in run-task mode and returns the raw result your agent can reason over.

OpenAI SDK

Vercel AI SDK

LangChain SDK

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const interfaze = new OpenAI({
  apiKey: process.env.INTERFAZE_API_KEY,
  baseURL: "https://api.interfaze.ai/v1",
});

async function runInterfazeTask(task: string, prompt: string) {
  const res = await interfaze.chat.completions.create({
    model: "interfaze-beta",
    messages: [
      { role: "system", content: `<task>${task}</task>` },
      { role: "user", content: prompt },
    ],
    response_format: zodResponseFormat(z.any(), "empty_schema"),
  });
  return JSON.parse(res.choices[0].message.content!).result;
}

OCR — extract text from documents

Register OCR as a tool. Your agent calls it when it encounters a document or image URL and gets back clean structured text.

OpenAI SDK

Vercel AI SDK

LangChain SDK

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const interfaze = new OpenAI({
  apiKey: process.env.INTERFAZE_API_KEY,
  baseURL: "https://api.interfaze.ai/v1",
});
const model = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function runInterfazeTask(task: string, prompt: string) {
  const res = await interfaze.chat.completions.create({
    model: "interfaze-beta",
    messages: [
      { role: "system", content: `<task>${task}</task>` },
      { role: "user", content: prompt },
    ],
    response_format: zodResponseFormat(z.any(), "empty_schema"),
  });
  return JSON.parse(res.choices[0].message.content!).result;
}

const ocrTool = {
  type: "function" as const,
  function: {
    name: "ocr",
    description: "Extract text and structured data from images or documents.",
    parameters: {
      type: "object",
      properties: {
        url: { type: "string", description: "URL of the image or document." },
      },
      required: ["url"],
    },
  },
};

const messages: OpenAI.ChatCompletionMessageParam[] = [
  {
    role: "user",
    content: "Extract the title, authors, and abstract from: https://arxiv.org/pdf/2602.04101",
  },
];

const res = await model.chat.completions.create({
  model: "gpt-4o",
  messages,
  tools: [ocrTool],
  tool_choice: "auto",
});

messages.push(res.choices[0].message);

for (const call of res.choices[0].message.tool_calls ?? []) {
  const { url } = JSON.parse(call.function.arguments);
  const result = await runInterfazeTask("ocr", `Extract all text and data from: ${url}`);
  messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });
}

const final = await model.chat.completions.create({ model: "gpt-4o", messages });
console.log(final.choices[0].message.content);

Web search — live data at runtime

Give your agent access to real-time information. It can look up current events, check documentation, or verify facts before responding.

OpenAI SDK

Vercel AI SDK

LangChain SDK

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const interfaze = new OpenAI({
  apiKey: process.env.INTERFAZE_API_KEY,
  baseURL: "https://api.interfaze.ai/v1",
});
const model = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function runInterfazeTask(task: string, prompt: string) {
  const res = await interfaze.chat.completions.create({
    model: "interfaze-beta",
    messages: [
      { role: "system", content: `<task>${task}</task>` },
      { role: "user", content: prompt },
    ],
    response_format: zodResponseFormat(z.any(), "empty_schema"),
  });
  return JSON.parse(res.choices[0].message.content!).result;
}

const webSearchTool = {
  type: "function" as const,
  function: {
    name: "web_search",
    description: "Search the web for real-time information.",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string", description: "The search query." },
      },
      required: ["query"],
    },
  },
};

const messages: OpenAI.ChatCompletionMessageParam[] = [
  { role: "user", content: "What are the latest updates to the OpenAI API?" },
];

const res = await model.chat.completions.create({
  model: "gpt-4o",
  messages,
  tools: [webSearchTool],
  tool_choice: "auto",
});

messages.push(res.choices[0].message);

for (const call of res.choices[0].message.tool_calls ?? []) {
  const { query } = JSON.parse(call.function.arguments);
  const result = await runInterfazeTask("web_search", query);
  messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });
}

const final = await model.chat.completions.create({ model: "gpt-4o", messages });
console.log(final.choices[0].message.content);

Speech-to-text — transcribe audio files

Register speech-to-text as a tool. Pass any audio URL and your agent gets a full transcript to summarize, extract action items from, or reason over.

OpenAI SDK

Vercel AI SDK

LangChain SDK

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const interfaze = new OpenAI({
  apiKey: process.env.INTERFAZE_API_KEY,
  baseURL: "https://api.interfaze.ai/v1",
});
const model = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function runInterfazeTask(task: string, prompt: string) {
  const res = await interfaze.chat.completions.create({
    model: "interfaze-beta",
    messages: [
      { role: "system", content: `<task>${task}</task>` },
      { role: "user", content: prompt },
    ],
    response_format: zodResponseFormat(z.any(), "empty_schema"),
  });
  return JSON.parse(res.choices[0].message.content!).result;
}

const sttTool = {
  type: "function" as const,
  function: {
    name: "speech_to_text",
    description: "Transcribe an audio file to text.",
    parameters: {
      type: "object",
      properties: {
        audio_url: { type: "string", description: "URL of the audio file." },
      },
      required: ["audio_url"],
    },
  },
};

const messages: OpenAI.ChatCompletionMessageParam[] = [
  {
    role: "user",
    content: "Summarize this call and list any follow-up items: https://r2public.jigsawstack.com/interfaze/examples/stt_call.mp3",
  },
];

const res = await model.chat.completions.create({
  model: "gpt-4o",
  messages,
  tools: [sttTool],
  tool_choice: "auto",
});

messages.push(res.choices[0].message);

for (const call of res.choices[0].message.tool_calls ?? []) {
  const { audio_url } = JSON.parse(call.function.arguments);
  const result = await runInterfazeTask("speech_to_text", `Transcribe this audio: ${audio_url}`);
  messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });
}

const final = await model.chat.completions.create({ model: "gpt-4o", messages });
console.log(final.choices[0].message.content);

Combining multiple tools

You can register any combination of tasks as tools. The agent picks whichever it needs based on the request.

OpenAI SDK

Vercel AI SDK

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const interfaze = new OpenAI({
  apiKey: process.env.INTERFAZE_API_KEY,
  baseURL: "https://api.interfaze.ai/v1",
});
const model = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function runInterfazeTask(task: string, prompt: string) {
  const res = await interfaze.chat.completions.create({
    model: "interfaze-beta",
    messages: [
      { role: "system", content: `<task>${task}</task>` },
      { role: "user", content: prompt },
    ],
    response_format: zodResponseFormat(z.any(), "empty_schema"),
  });
  return JSON.parse(res.choices[0].message.content!).result;
}

const tools: OpenAI.ChatCompletionTool[] = [
  {
    type: "function",
    function: {
      name: "ocr",
      description: "Extract text and structured data from images or documents.",
      parameters: {
        type: "object",
        properties: { url: { type: "string" } },
        required: ["url"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "web_search",
      description: "Search the web for real-time information.",
      parameters: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "speech_to_text",
      description: "Transcribe an audio file to text.",
      parameters: {
        type: "object",
        properties: { audio_url: { type: "string" } },
        required: ["audio_url"],
      },
    },
  },
];

const taskMap: Record<string, (args: Record<string, string>) => Promise<unknown>> = {
  ocr: ({ url }) => runInterfazeTask("ocr", `Extract all text from: ${url}`),
  web_search: ({ query }) => runInterfazeTask("web_search", query),
  speech_to_text: ({ audio_url }) => runInterfazeTask("speech_to_text", `Transcribe: ${audio_url}`),
};

const messages: OpenAI.ChatCompletionMessageParam[] = [
  { role: "user", content: "Search for the latest news on AI agents and summarize the top results." },
];

let res = await model.chat.completions.create({ model: "gpt-4o", messages, tools, tool_choice: "auto" });
messages.push(res.choices[0].message);

while (res.choices[0].message.tool_calls?.length) {
  for (const call of res.choices[0].message.tool_calls) {
    const args = JSON.parse(call.function.arguments);
    const result = await taskMap[call.function.name](args);
    messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });
  }
  res = await model.chat.completions.create({ model: "gpt-4o", messages, tools, tool_choice: "auto" });
  messages.push(res.choices[0].message);
}

console.log(res.choices[0].message.content);