工具呼叫

工具呼叫（也稱為函式呼叫）允許模型請求執行您定義的特定函式。模型決定何時呼叫工具以及使用什麼參數——您的應用程式執行工具並回傳結果。 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 步：帶工具結果的推理

完整範例

串流工具呼叫

支援的模型