工具调用

工具调用（也称为函数调用）允许模型请求执行您定义的特定函数。模型决定何时调用工具以及使用什么参数——您的应用程序执行工具并返回结果。 ARouter 支持所有主要供应商的工具调用。接口遵循 OpenAI 工具调用标准。

工作原理

工具调用遵循 3 步循环：

带工具的推理 — 您发送带有工具定义的请求。模型决定调用工具并返回 tool_calls 响应。
工具执行（客户端） — 您的应用程序运行请求的函数并收集结果。
带工具结果的推理 — 您将工具结果返回给模型，模型生成最终响应。

第 1 步：带工具的推理

{
  "model": "openai/gpt-5.4",
  "messages": [
    { "role": "user", "content": "What is the weather in San Francisco?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name, e.g. 'San Francisco'"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

模型返回 tool_calls 数组：

{
  "id": "chatcmpl-xxx",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"San Francisco\", \"unit\": \"fahrenheit\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

第 2 步：工具执行（客户端）

您的应用程序使用模型的参数执行函数：

import json

tool_call = response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)

# 执行您的函数
result = get_weather(
    location=args["location"],
    unit=args.get("unit", "fahrenheit")
)
# result = {"temperature": 72, "condition": "sunny", "unit": "fahrenheit"}

第 3 步：带工具结果的推理

将工具结果作为 tool 角色消息发送回去：

{
  "model": "openai/gpt-5.4",
  "messages": [
    { "role": "user", "content": "What is the weather in San Francisco?" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\": \"San Francisco\", \"unit\": \"fahrenheit\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": 72, \"condition\": \"sunny\", \"unit\": \"fahrenheit\"}"
    }
  ],
  "tools": [...]
}

完整示例

Python (OpenAI)
Node.js (OpenAI)
Go
cURL

import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# 定义工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name, e.g. 'San Francisco'",
                    },
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What is the weather in San Francisco?"}]

# 第 1 步：首次推理
response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

assistant_message = response.choices[0].message
messages.append(assistant_message)

# 第 2 步：执行工具
if assistant_message.tool_calls:
    for tool_call in assistant_message.tool_calls:
        if tool_call.function.name == "get_weather":
            args = json.loads(tool_call.function.arguments)
            # 模拟天气 API
            result = {"temperature": 72, "condition": "sunny", "unit": args.get("unit", "fahrenheit")}

            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(result),
            })

# 第 3 步：最终推理
final_response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=messages,
    tools=tools,
)

print(final_response.choices[0].message.content)
# "The current weather in San Francisco is 72°F and sunny."

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.arouter.ai/v1",
  apiKey: "lr_live_xxxx",
});

// 定义工具
const tools: OpenAI.Chat.ChatCompletionTool[] = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the current weather for a location",
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "City name, e.g. 'San Francisco'",
          },
          unit: { type: "string", enum: ["celsius", "fahrenheit"] },
        },
        required: ["location"],
      },
    },
  },
];

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  { role: "user", content: "What is the weather in San Francisco?" },
];

// 第 1 步：首次推理
const response = await client.chat.completions.create({
  model: "openai/gpt-5.4",
  messages,
  tools,
  tool_choice: "auto",
});

const assistantMessage = response.choices[0].message;
messages.push(assistantMessage);

// 第 2 步：执行工具
if (assistantMessage.tool_calls) {
  for (const toolCall of assistantMessage.tool_calls) {
    if (toolCall.function.name === "get_weather") {
      const args = JSON.parse(toolCall.function.arguments);
      const result = {
        temperature: 72,
        condition: "sunny",
        unit: args.unit ?? "fahrenheit",
      };

      messages.push({
        role: "tool",
        tool_call_id: toolCall.id,
        content: JSON.stringify(result),
      });
    }
  }
}

// 第 3 步：最终推理
const finalResponse = await client.chat.completions.create({
  model: "openai/gpt-5.4",
  messages,
  tools,
});

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

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/arouter-ai/arouter-go"
)

func main() {
    client := arouter.NewClient("lr_live_xxxx",
        arouter.WithBaseURL("https://api.arouter.ai/v1"),
    )

    tools := []arouter.Tool{
        {
            Type: "function",
            Function: &arouter.FunctionDefinition{
                Name:        "get_weather",
                Description: "Get the current weather for a location",
                Parameters: map[string]any{
                    "type": "object",
                    "properties": map[string]any{
                        "location": map[string]any{
                            "type":        "string",
                            "description": "City name",
                        },
                        "unit": map[string]any{
                            "type": "string",
                            "enum": []string{"celsius", "fahrenheit"},
                        },
                    },
                    "required": []string{"location"},
                },
            },
        },
    }

    messages := []arouter.Message{
        {Role: "user", Content: "What is the weather in San Francisco?"},
    }

    // 第 1 步
    resp, err := client.CreateChatCompletion(context.Background(), arouter.ChatCompletionRequest{
        Model:    "openai/gpt-5.4",
        Messages: messages,
        Tools:    tools,
    })
    if err != nil {
        log.Fatal(err)
    }

    assistantMsg := resp.Choices[0].Message
    messages = append(messages, assistantMsg)

    // 第 2、3 步
    for _, tc := range assistantMsg.ToolCalls {
        var args map[string]string
        json.Unmarshal([]byte(tc.Function.Arguments), &args)
        result := fmt.Sprintf(`{"temperature":72,"condition":"sunny","unit":"%s"}`, args["unit"])
        messages = append(messages, arouter.Message{
            Role:       "tool",
            ToolCallID: tc.ID,
            Content:    result,
        })
    }

    finalResp, err := client.CreateChatCompletion(context.Background(), arouter.ChatCompletionRequest{
        Model:    "openai/gpt-5.4",
        Messages: messages,
        Tools:    tools,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(finalResp.Choices[0].Message.Content)
}

# 第 1 步：带工具的推理
curl https://api.arouter.ai/v1/chat/completions \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string"},
              "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

# 第 3 步：发送工具结果
curl https://api.arouter.ai/v1/chat/completions \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"},
      {
        "role": "assistant",
        "content": null,
        "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"San Francisco\"}"}}]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 72, \"condition\": \"sunny\"}"
      }
    ]
  }'

流式工具调用

启用流式传输后，工具调用参数通过 delta.tool_calls 增量传递：

const stream = await client.chat.completions.create({
  model: "openai/gpt-5.4",
  messages: [{ role: "user", content: "What's the weather in NYC?" }],
  tools,
  stream: true,
});

let toolCallArgs = "";
let toolCallId = "";
let toolCallName = "";

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

  if (delta?.tool_calls) {
    const tc = delta.tool_calls[0];
    if (tc.id) toolCallId = tc.id;
    if (tc.function?.name) toolCallName = tc.function.name;
    if (tc.function?.arguments) toolCallArgs += tc.function.arguments;
  }

  if (chunk.choices[0]?.finish_reason === "tool_calls") {
    // 所有参数已接收完毕
    const args = JSON.parse(toolCallArgs);
    console.log(`Calling ${toolCallName} with:`, args);
  }
}

支持的模型

使用 GET /v1/models 查找支持工具调用的模型。功能列表中包含 tools 的模型支持此功能。

curl https://api.arouter.ai/v1/models \
  -H "Authorization: Bearer lr_live_xxxx"

大多数前沿模型都支持工具调用，包括：

openai/gpt-5.4, openai/gpt-5.4-pro
anthropic/claude-sonnet-4.6, anthropic/claude-opus-4.5
google/gemini-2.5-flash, google/gemini-2.5-pro
deepseek/deepseek-v3.2

快速开始

核心概念

路由

功能特性

使用指南

隐私

管理

最佳实践

框架与集成

供应商接入

帮助

工作原理

第 1 步：带工具的推理

第 2 步：工具执行（客户端）

第 3 步：带工具结果的推理

完整示例

流式工具调用

支持的模型

​工作原理

​第 1 步：带工具的推理

​第 2 步：工具执行（客户端）

​第 3 步：带工具结果的推理

​完整示例

​流式工具调用

​支持的模型

工作原理

第 1 步：带工具的推理

第 2 步：工具执行（客户端）

第 3 步：带工具结果的推理

完整示例

流式工具调用

支持的模型