Tools and function calling

POST /v1/chat/completions accepts the standard OpenAI tools array. The model emits structured tool_calls in its response when it decides a tool is the right move; your code runs the tool and round-trips the result back as a role: "tool" message.

Tool schema

Each tool is a function declaration with a JSON-schema parameter object:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Return the current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string", "description": "City name, e.g. 'Berlin'." },
        "unit": { "type": "string", "enum": ["c", "f"], "default": "c" }
      },
      "required": ["city"]
    }
  }
}

The tool_choice field controls how the model picks a tool:

Value	Behavior
`"auto"` (default if `tools` is set)	Model decides per turn whether to call a tool.
`"none"`	Disable tool calls for this turn.
`"required"`	Force the model to call at least one tool. Returns `400 tool_choice_required_unsupported` if the model lacks the capability.
`{ "type": "function", "function": { "name": "..." } }`	Force a specific tool.

Single-turn example

curl -X POST https://api.aurous-labs.com/v1/chat/completions \
  -H "Authorization: Bearer $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aurous-grow-2.0-pro",
    "messages": [
      { "role": "user", "content": "What is the weather in Berlin?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Return the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string" },
              "unit": { "type": "string", "enum": ["c", "f"] }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto",
    "max_tokens": 512
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.aurous-labs.com/v1",
  apiKey: process.env.AUROUS_API_KEY!,
});

const tools = [
  {
    type: "function" as const,
    function: {
      name: "get_weather",
      description: "Return the current weather for a city.",
      parameters: {
        type: "object",
        properties: {
          city: { type: "string" },
          unit: { type: "string", enum: ["c", "f"] },
        },
        required: ["city"],
      },
    },
  },
];

const first = await client.chat.completions.create({
  model: "aurous-grow-2.0-pro",
  messages: [{ role: "user", content: "What is the weather in Berlin?" }],
  tools,
  tool_choice: "auto",
  max_tokens: 512,
});

const call = first.choices[0].message.tool_calls?.[0];
console.log(call?.function.name, call?.function.arguments);
// → "get_weather" '{"city":"Berlin","unit":"c"}'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.aurous-labs.com/v1",
    api_key="al_live_xxxxxxxxxxxxxxxx",
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Return the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "unit": {"type": "string", "enum": ["c", "f"]},
                },
                "required": ["city"],
            },
        },
    }
]

first = client.chat.completions.create(
    model="aurous-grow-2.0-pro",
    messages=[{"role": "user", "content": "What is the weather in Berlin?"}],
    tools=tools,
    tool_choice="auto",
    max_tokens=512,
)

call = first.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)
# → "get_weather" '{"city":"Berlin","unit":"c"}'

Round-tripping the tool result

After the model emits a tool call, run the tool locally, then re-call chat.completions.create with the original assistant message AND a new role: "tool" message carrying the result:

Node.js (OpenAI SDK)

// Step 1: model returned a tool_call.
const assistantMessage = first.choices[0].message;
const call = assistantMessage.tool_calls![0];
const args = JSON.parse(call.function.arguments);

// Step 2: run the tool (your code).
const weather = await fetchWeather(args.city, args.unit);
//   → { tempC: 14, condition: "cloudy" }

// Step 3: send the tool result back as a follow-up turn.
const followup = await client.chat.completions.create({
  model: "aurous-grow-2.0-pro",
  messages: [
    { role: "user", content: "What is the weather in Berlin?" },
    assistantMessage, // contains tool_calls
    {
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(weather),
    },
  ],
  max_tokens: 512,
});

console.log(followup.choices[0].message.content);
// → "It's 14°C and cloudy in Berlin right now."

The tool_call_id on the role: "tool" message must match the id field on the assistant’s tool_calls entry. The model may emit multiple tool calls in a single turn — round-trip them all in one follow-up.

Parallel tool calls

If the model emits two or more tool calls in a single turn (message.tool_calls.length > 1), run them in parallel and send all results back in the next request:

const calls = assistantMessage.tool_calls!;
const results = await Promise.all(
  calls.map(async (c) => ({
    role: "tool" as const,
    tool_call_id: c.id,
    content: JSON.stringify(await dispatchTool(c.function.name, c.function.arguments)),
  })),
);

const final = await client.chat.completions.create({
  model: "aurous-grow-2.0-pro",
  messages: [
    { role: "user", content: "Compare Berlin and Tokyo weather." },
    assistantMessage,
    ...results, // one tool message per call
  ],
});

Forcing a specific tool

Pin the tool the model must call by name:

{
  "tools": [...],
  "tool_choice": {
    "type": "function",
    "function": { "name": "get_weather" }
  }
}

Combined with response_format, this is the building block for “extract structured data from text” flows: define a tool whose parameters match the schema you want and force it.

Streaming and tools

When stream: true, tool-call arguments arrive as delta.tool_calls[*].function.arguments fragments that you must concatenate per id until you see finish_reason: "tool_calls". The OpenAI Node and Python SDKs both expose tool_calls accumulators on their streaming helpers — prefer those over hand-parsing deltas.

Errors

tool_choice_required_unsupported (400) — you passed tool_choice: "required" to a model whose aurous_metadata.capabilities doesn’t include tool_choice_required. List models via GET /v1/models to check capability flags before setting this.
response_format_too_large (400) — the JSON schema in response_format exceeds the platform’s payload cap. Trim the schema (fewer properties, shorter descriptions) and retry.
response_format_too_deep (400) — the JSON schema nests deeper than the parser’s cap. Flatten nested definitions or pull them into $defs references.

Get started

Guides

Concepts

API Reference

Resources

Tools and function calling

Tool schema

Single-turn example

Round-tripping the tool result

Parallel tool calls

Forcing a specific tool

Streaming and tools

Errors

​Tool schema

​Single-turn example

​Round-tripping the tool result

​Parallel tool calls

​Forcing a specific tool

​Streaming and tools

​Errors

Tool schema

Single-turn example

Round-tripping the tool result

Parallel tool calls

Forcing a specific tool

Streaming and tools

Errors