Function calling

Function calling (also known as tool calling) lets SubQ models interface with external systems and data outside their training data. Pass function tools defined by a JSON schema in the tools parameter; the model may return a tool call, and your application executes the function and sends the tool call output back so the model can finish the reply. The shape differs by endpoint: Responses uses a flattened tool object (type/name/parameters directly on it), while Chat Completions nests those fields under a function object.

How it works

Tools — functionality you give the model. A function tool is a JSON Schema definition the model can choose to call, for example get_stock_quote, account lookup, or issuing a refund.

Tool calls — requests from the model to use a tool. If the prompt needs live data, the model returns one or more calls, each with a function name and JSON-encoded arguments.

Tool call outputs — results your application sends back so the model can finish the reply.

The tool calling flow

Make a request to the model with tools it could call
Receive a tool call from the model
Execute code on the application side with input from the tool call
Make a second request to the model with the tool output
Receive a final response from the model (or more tool calls)

Field reference

	Responses API	Chat Completions
Tool shape	`type`, `name`, `description`, `parameters`, `strict` directly on the tool object	`type: "function"` plus a nested `function: { name, description, parameters, strict }`
Tool call	`function_call` output item — `call_id`, `name`, `arguments`	`tool_calls[]` on the assistant message — `id`, `function: { name, arguments }`
Sending the result	`function_call_output` input item — `call_id`, `output`	A message with `role: "tool"`, `tool_call_id`, `content`
Streaming	`response.function_call_arguments.delta`/`.done` events	`delta.tool_calls[]`, keyed by `index`
Continuing the loop	`previous_response_id` (or `conversation`)	Resend the full `messages[]`, including the assistant and tool messages

Both accept the same JSON Schema shape in parameters, and the same strict mode requirements.

Example

End-to-end flow for a get_stock_quote function: the first request declares the tool, the model returns a tool call, your code runs the function and sends the result back for a final answer.

curl --request POST \
  --url https://api.subq.ai/v1/responses \
  --header "Authorization: Bearer $SUBQ_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "model": "subq-preview",
  "input": "What's NVDA trading at right now?",
  "tools": [
    {
      "type": "function",
      "name": "get_stock_quote",
      "description": "Retrieves the latest quote for a stock ticker.",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Ticker symbol, e.g. NVDA or MSFT"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "USD",
              "EUR"
            ],
            "description": "Quote currency. Defaults to USD when null."
          },
          "include_extended_hours": {
            "type": "boolean",
            "description": "When true, include pre-market and after-hours price if available."
          }
        },
        "required": [
          "symbol",
          "currency",
          "include_extended_hours"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}
EOF

cURLTypeScriptPython

Accumulate any text preamble, execute every function_call in the turn, then continue with one function_call_output per call_id:

import OpenAI from "openai";

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

// Responses API function tools use a flattened shape. Unlike Chat
// Completions, name/description/parameters are not nested under `function`.
const tools = [
  {
    type: "function",
    name: "get_stock_quote",
    description:
      "Get the latest price for one stock ticker. Returns symbol, price, change_percent, and as_of.",
    parameters: {
      type: "object",
      properties: {
        symbol: {
          type: "string",
          description: "Ticker symbol, e.g. NVDA or MSFT.",
        },
      },
      required: ["symbol"],
      additionalProperties: false,
    },
    strict: true,
  },
];

const SAMPLE_QUOTES = {
  NVDA: { price: 210.96, change_percent: 4.03 },
  MSFT: { price: 402.18, change_percent: 1.12 },
};

// Replace this stub with a call to your market-data provider.
async function getStockQuote({ symbol }) {
  return { symbol, as_of: new Date().toISOString(), ...SAMPLE_QUOTES[symbol] };
}

const functionHandlers = {
  get_stock_quote: getStockQuote,
};

// A function_call turn may carry a text preamble as a `message` item before
// the call (see "Text preamble before tool calls"); it is never the final
// answer by itself, so always take the *last* message item.
function getLastAssistantText(response) {
  const messages = response.output.filter((item) => item.type === "message");

  return (
    messages
      .at(-1)
      ?.content?.filter((part) => part.type === "output_text")
      .map((part) => part.text)
      .join("") ?? ""
  );
}

let response = await client.responses.create({
  model: "subq-preview",
  input: "What are NVDA and MSFT trading at, and which moved more today?",
  tools,
});

// A response can contain more function calls after receiving function call
// outputs, so continue until the model returns a final response.
const maxFunctionRounds = 8;

for (let round = 0; round < maxFunctionRounds; round += 1) {
  const functionCalls = response.output.filter(
    (item) => item.type === "function_call",
  );

  if (functionCalls.length === 0) break;

  // A message before a function call is an optional preamble, not the final
  // answer. It can be shown to the user while the functions are running.
  const preamble = getLastAssistantText(response);
  if (preamble) {
    console.log(preamble);
  }

  // Execute every function_call in the turn — the model may call in parallel.
  const functionCallOutputs = await Promise.all(
    functionCalls.map(async (call) => {
      const handler = functionHandlers[call.name];
      if (!handler) {
        throw new Error(`No handler registered for function "${call.name}".`);
      }

      return {
        type: "function_call_output",
        call_id: call.call_id,
        output: JSON.stringify(await handler(JSON.parse(call.arguments))),
      };
    }),
  );

  response = await client.responses.create({
    model: "subq-preview",
    previous_response_id: response.id,
    input: functionCallOutputs,
    // Resend tools so the model can request another function call.
    tools,
  });
}

if (response.output.some((item) => item.type === "function_call")) {
  throw new Error(`Exceeded ${maxFunctionRounds} function-calling rounds.`);
}

console.log(getLastAssistantText(response));

TypeScriptPython

Set stream to true and include your function definitions in tools.

curl --request POST \
  --url https://api.subq.ai/v1/chat/completions \
  --header "Authorization: Bearer $SUBQ_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "model": "subq-preview",
  "messages": [
    {
      "role": "user",
      "content": "What's NVDA trading at right now?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_stock_quote",
        "description": "Retrieves the latest quote for a stock ticker.",
        "parameters": {
          "type": "object",
          "properties": {
            "symbol": {
              "type": "string",
              "description": "Ticker symbol, e.g. NVDA or MSFT"
            },
            "currency": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "USD",
                "EUR"
              ],
              "description": "Quote currency. Defaults to USD when null."
            },
            "include_extended_hours": {
              "type": "boolean",
              "description": "When true, include pre-market and after-hours price if available."
            }
          },
          "required": [
            "symbol",
            "currency",
            "include_extended_hours"
          ],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ],
  "stream": true
}
EOF

cURLTypeScriptPython

Accumulate streamed delta.tool_calls into one assistant message, execute each call, append role: "tool" results, then call the model again:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SUBQ_API_KEY,
  baseURL: "https://api.subq.ai/v1",
  maxRetries: 0,
});

// 1. Define callable tools for the model
const tools = [
  {
    type: "function",
    function: {
      name: "get_stock_quote",
      description: "Retrieves the latest quote for a stock ticker.",
      parameters: {
        type: "object",
        properties: {
          symbol: {
            type: "string",
            description: "Ticker symbol, e.g. NVDA or MSFT",
          },
          currency: {
            type: ["string", "null"],
            enum: ["USD", "EUR"],
            description: "Quote currency. Defaults to USD when null.",
          },
          include_extended_hours: {
            type: "boolean",
            description:
              "When true, include pre-market and after-hours price if available.",
          },
        },
        required: ["symbol", "currency", "include_extended_hours"],
        additionalProperties: false,
      },
      strict: true,
    },
  },
];

function getStockQuote({ symbol, currency, include_extended_hours }) {
  const quoteCurrency = currency ?? "USD";
  return JSON.stringify({
    symbol: symbol.toUpperCase(),
    price: 210.96,
    currency: quoteCurrency,
    change: 8.18,
    change_percent: 4.03,
    open: 202.0,
    high: 211.0,
    low: 201.92,
    previous_close: 202.78,
    market_cap: 5.11e12,
    pe_ratio: 32.31,
    market_open: false,
    extended_hours: include_extended_hours
      ? {
          price: 210.38,
          change: -0.58,
          change_percent: -0.27,
          session: "after_hours",
        }
      : null,
    as_of: "2026-07-10T21:22:00Z",
  });
}

/** Accumulate streamed chat.completion chunks into one assistant message. */
async function createCompletion(messages) {
  const stream = await client.chat.completions.create({
    model: "subq-preview",
    messages,
    tools,
    stream: true,
  });

  const message = {
    role: "assistant",
    content: null,
    tool_calls: [],
  };

  for await (const chunk of stream) {
    const delta = chunk.choices[0]?.delta;
    if (!delta) continue;

    if (typeof delta.content === "string") {
      message.content = (message.content ?? "") + delta.content;
    }

    for (const toolCall of delta.tool_calls ?? []) {
      const index = toolCall.index ?? 0;
      if (!message.tool_calls[index]) {
        message.tool_calls[index] = {
          id: toolCall.id,
          type: toolCall.type ?? "function",
          function: {
            name: toolCall.function?.name ?? "",
            arguments: toolCall.function?.arguments ?? "",
          },
        };
        continue;
      }

      if (toolCall.id) message.tool_calls[index].id = toolCall.id;
      if (toolCall.function?.name) {
        message.tool_calls[index].function.name += toolCall.function.name;
      }
      if (toolCall.function?.arguments) {
        message.tool_calls[index].function.arguments +=
          toolCall.function.arguments;
      }
    }
  }

  if (message.tool_calls.length === 0) {
    delete message.tool_calls;
  }

  return message;
}

const messages = [
  { role: "user", content: "What's NVDA trading at right now?" },
];

// 2. Prompt the model with tools available
let message = await createCompletion(messages);
messages.push(message);

if (!message.tool_calls?.length) {
  console.log(message.content);
  process.exit(0);
}

// 3. Execute each tool call on the application side
for (const toolCall of message.tool_calls) {
  if (toolCall.function.name !== "get_stock_quote") continue;

  const args = JSON.parse(toolCall.function.arguments);
  const result = getStockQuote(args);

  // 4. Provide tool call outputs back to the model
  messages.push({
    role: "tool",
    tool_call_id: toolCall.id,
    content: result,
  });
}

// 5. Receive a final response (or more tool calls)
message = await createCompletion(messages);
console.log(message.content);

TypeScriptPython

Example assistant tool call (after accumulating the stream):

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "get_stock_quote",
        "arguments": "{\"symbol\":\"NVDA\",\"currency\":\"USD\",\"include_extended_hours\":false}"
      }
    }
  ]
}

Example tool message you send back:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"symbol\":\"NVDA\",\"price\":210.96,\"currency\":\"USD\",\"change\":8.18,\"change_percent\":4.03,\"open\":202.0,\"high\":211.0,\"low\":201.92,\"previous_close\":202.78,\"market_cap\":5110000000000,\"pe_ratio\":32.31,\"market_open\":false,\"extended_hours\":null,\"as_of\":\"2026-07-10T21:22:00Z\"}"
}

A response can contain more calls after receiving outputs, so keep looping until the model returns a final message — cap the number of rounds to avoid runaway loops. Execute every call in a turn concurrently (the model may call in parallel).

Strict mode

Set strict to true so function arguments adhere to the schema. Recommended for production. Strict schemas require:

additionalProperties set to false on every object in parameters
Every key in properties listed in required

Mark a field optional by allowing null in its type (for example "type": ["string", "null"]) while still listing it in required.

Handling function calls

Assume zero, one, or many tool calls in a turn — see Dispatching multiple tool calls above.

Add the model's tool call(s) to your ongoing context (the assistant message on Chat Completions, or nothing extra to add on Responses — just continue via previous_response_id/conversation)
For each call, parse the arguments, run your code, and send back a result keyed by call_id (Responses) or tool_call_id (Chat Completions)
Call the model again with the result — the full messages[] on Chat Completions, or just the function_call_output items on Responses

The result is typically a string — JSON, plain text, or a short success/failure token for side-effect-only functions (for example "success").

Tool choice

By default the model decides when to call tools. On Chat Completions, control that with tool_choice:

Value	Behavior
`"auto"`	Default. Call zero, one, or multiple functions
`"required"`	Call one or more functions
`"none"`	Do not call tools (same as omitting `tools`)
`{"type":"function","function":{"name":"get_stock_quote"}}`	Force that specific function

{
  "tool_choice": {
    "type": "function",
    "function": { "name": "get_stock_quote" }
  }
}

Responses accepts the same "auto"/"required"/"none" string values (defaulting to "auto" once tools is set) but doesn't support forcing one specific function by name.

Best practices

Write clear names and descriptions. Say when to use the function, what each parameter means, and what the output represents. Use the system message or instructions for when not to call a tool.
Keep the tool list small. Fewer tools usually improve accuracy; prefer a focused set over a large catalog in one turn.
Offload known values in code. Do not ask the model to fill arguments you already know (for example an order_id from session state).
Enable strict mode and validate parsed arguments in your application before executing side effects.

Responses API — request fields and streaming events for the flattened shape.
Chat Completions API — request fields and response shape for the nested shape.
Structured outputs — schema-constrained JSON replies.
Models — which models support tool calls.
OpenAI Function calling — full OpenAI reference.

Function calling

On this page