能力

工具

工具让模型成为函数调用方。你声明它能做什么，模型决定何时调用，你负责执行，结果再回到对话中。

工具调用循环

在请求中声明 tools 后发出。
模型要么正常回复（stop_reason: end_turn），要么请求调用工具（stop_reason: tool_use）。
出现 tool_use 时，在 content 中找到 tool_use 块，用其提供的 input 运行你的代码，然后追加一条 user 消息，里面带上引用同一 tool_use_id 的 tool_result 块。
把更新后的消息列表回发。模型会带着结果继续。重复直到 stop_reason 不再是 tool_use。

声明工具

工具由名称、描述和输入的 JSON schema 组成。请在描述以及每个参数的描述上多花点时间——模型就是靠这些文字来决定是否调用你的工具。

工具定义

{
  "name": "get_weather",
  "description": "Get the current weather for a city. Use this when the user asks about temperature, rain, or conditions outside.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name in plain English." },
      "units": { "type": "string", "enum": ["celsius","fahrenheit"], "description": "Default celsius." }
    },
    "required": ["city"]
  }
}

端到端完整循环

下面的示例发送一次提示，处理由此产生的工具调用，并打印模型的最终答案。生产环境里你还需要处理：模型请求一个你不认识的工具（在 tool_result 内容里返回错误），以及循环超过合理迭代次数（限制在 8 或 10 轮内）。

curl https://caicaini.com/v1/messages \
  -H "Authorization: Bearer cai_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caicaini/sonnet",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather for a city.",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": {"type": "string"},
          "units": {"type": "string", "enum": ["celsius","fahrenheit"]}
        },
        "required": ["city"]
      }
    }],
    "messages": [
      {"role": "user", "content": "What is the weather in Lisbon right now?"}
    ]
  }'

tool_use 响应长什么样

响应 · stop_reason: tool_use

{
  "id": "msg_01H...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01XyZ...",
      "name": "get_weather",
      "input": { "city": "Lisbon", "units": "celsius" }
    }
  ],
  "model": "caicaini/sonnet",
  "stop_reason": "tool_use",
  "usage": { "input_tokens": 122, "output_tokens": 38, "credits_consumed": 76 }
}

用 tool_result 回复

user 消息

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01XyZ...",
      "content": "{\"city\":\"Lisbon\",\"temperature\":21,\"units\":\"celsius\",\"conditions\":\"Sunny\"}"
    }
  ]
}

强制工具调用

默认由模型决定是否调用工具。可以用 tool_choice 覆盖：

developers.docs.tools.toolChoiceItem1
developers.docs.tools.toolChoiceItem2
developers.docs.tools.toolChoiceItem3

并行工具调用

一次 assistant 轮次可以包含多个 tool_use 块。在客户端并行执行它们，并以一条 user 消息回复，里面包含数量相同、顺序一致的 tool_result 块。

把错误回报给模型

如果你的工具失败，请返回一个 JSON 编码错误体的 tool_result，并把 is_error 设为 true。模型会看到失败信息，然后要么换一组输入重试，要么向用户致歉。

带 is_error 的 tool_result

{
  "type": "tool_result",
  "tool_use_id": "toolu_01XyZ...",
  "is_error": true,
  "content": "{\"error\":\"city_not_found\",\"city\":\"Atlantis\"}"
}

哪些模型支持工具

五个虚拟 ID 都接受工具。质量与可靠性最高的是 caicaini/opus 和 caicaini/sonnet；更小的模型在范围窄、歧义少的工具上表现也很好。在涉及多个工具和长链路推理的复杂智能体循环里，请把工具与 caicaini/opus 的扩展思考配合使用。

上一篇视觉

下一篇深度思考