2026 Claude Sonnet 5 API 部署：工具调用怎么配？

截至 2026 年 8 月 18 日，Claude Sonnet 5 API 的官方工具调用成本为每百万输入 Token 3 美元、每百万输出 Token 15 美元；上线前最快的做法不是一次接入几十个工具，而是先用 1 个只读工具跑通闭环，再开启严格参数和结构化最终输出。(Claude Sonnet 5 官方公告)

症状： Agent 能生成计划，却出现参数缺失、重复扣款、工具结果接不上，或者远程进程出了问题却没有日志。
最快解法： 按“最小工具 → tool_use → 应用执行 → tool_result → 严格化 → MCP 扩展 → 远程验收”的顺序部署，并在生产环境补齐权限、超时、幂等和人工接管。

如果你第一次使用 Claude Sonnet 5 API，本文适合你从最小工具集开始搭建。
如果你已有 Claude Tool Use 项目，重点复核严格模式、输出格式和失败分支。
如果 Agent 准备远程运行，后半部分的进程守护、环境变量与日志验收不能跳过。

最后更新于 2026 年 8 月 18 日，模型可用性、接口行为与参数限制核实自 Claude 模型页、Tool Use 文档、Structured Outputs 文档与 API Release Notes。

工具边界

不要先问“模型能接多少工具”，先问每个工具会改变什么状态。

代码 Agent 可以先提供 read_file 这类只读工具；搜索 Agent 可以先提供 search_records；业务自动化则先选择一个低风险、可撤销的动作，例如创建草稿，而不是直接发送邮件、删除数据或修改生产配置。

工具定义至少要包含 3 类信息：

name：短、稳定、能表达动作，例如 search_orders，不要使用含糊的 do_task。
description：说明何时使用、何时不要使用，以及返回什么。
input_schema：用 JSON Schema 描述参数、类型、必填字段和业务约束。

Claude Sonnet 5 API 的客户端工具由你的应用执行，模型只返回结构化的 tool_use 请求；这意味着权限校验、数据库访问、Shell 执行和副作用控制都必须放在你的执行器中，而不能因为模型“看起来已经决定执行”就直接放行。

工具设计	首次部署适合度	主要优点	主要风险	建议
1 个只读工具	✅ 高	容易复现，几乎没有业务副作用	覆盖场景有限	首轮必选
只读工具 + 低风险动作	✅ 较高	能验证完整 Agent 流程	需要审批和幂等	第二阶段加入
多个直接托管工具	⚠️ 中	开发速度快，调用路径短	工具选择、权限和日志变复杂	有明确边界再增加
MCP 远程工具集	⚠️ 后置	多客户端发现和复用方便	授权、连接、清单变化、第三方数据边界	共享需求成立后再用

经验提醒： 工具描述不是给人看的接口注释，而是模型进行工具选择的重要输入。把“只能查询，不得修改”写进描述，同时在执行器中再次强制检查，不能只依赖提示词。

Claude Sonnet 5 API 的首个闭环

最小闭环只有 4 个关键节点：

应用发送用户问题、工具定义和 messages。
Claude 返回 stop_reason: "tool_use"，并在内容中给出 tool_use，包括 id、name 和 input。
应用根据 name 找到真实函数，校验参数后执行。
应用以新的 user 消息发送 tool_result，再请求模型生成最终回答。

Anthropic 的接口要求，tool_result 必须紧跟产生它的 assistant 消息；如果在两者之间插入普通文本，可能触发工具结果无法匹配的错误。具体消息顺序可参考 Tool Use 结果处理文档。

import json
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

tools = [
    {
        "name": "search_orders",
        "description": "只查询订单状态，不修改订单。传入订单号后返回状态和更新时间。",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "业务订单号"
                }
            },
            "required": ["order_id"],
            "additionalProperties": False
        }
    }
]

messages = [
    {
        "role": "user",
        "content": "查询订单 A-1008 的当前状态。"
    }
]

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1200,
    tools=tools,
    messages=messages
)

messages.append({
    "role": "assistant",
    "content": response.content
})

tool_use = next(
    block for block in response.content
    if block.type == "tool_use"
)

if tool_use.name != "search_orders":
    raise ValueError("未知工具，拒绝执行")

result = search_orders(tool_use.input["order_id"])

messages.append({
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": tool_use.id,
            "content": json.dumps(result, ensure_ascii=False)
        }
    ]
})

final_response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1200,
    tools=tools,
    messages=messages
)

这个示例故意没有加入 MCP、并行调用和自动重试。你先确认 4 件事：模型是否正确选择工具、参数是否通过应用校验、结果是否能被准确关联、最终回答是否引用了工具返回的数据。

工具调用会增加请求中的输入内容，因为工具名称、描述、Schema、tool_use 和 tool_result 都会计入 Token；官方文档还列出了 Claude Sonnet 5 在不同 tool_choice 下的工具使用系统提示开销，auto 或 none 为 354 Token，any 或 tool 为 474 Token。相关开销说明见官方 Tool Use 概览。

严格参数

Claude Tool Use 和 Structured Outputs 要分开理解。

strict: true 约束的是“模型如何调用你的工具”。
output_config.format 约束的是“模型最后返回什么结构”。
两者可以同时使用，但一个不能替代另一个。

例如，订单 Agent 需要工具参数严格符合 order_id、reason 和 dry_run 的定义，就在工具上加入 strict: true。如果你的后端还要求最终结果必须包含 status、evidence 和 next_action，则另外配置 JSON Schema 输出。

tools = [
    {
        "name": "create_refund_draft",
        "description": "创建退款草稿，不直接提交退款。",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"},
                "reason": {"type": "string"},
                "dry_run": {"type": "boolean"}
            },
            "required": ["order_id", "reason", "dry_run"],
            "additionalProperties": False
        }
    }
]

output_config = {
    "format": {
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {
                "status": {"type": "string"},
                "evidence": {"type": "array", "items": {"type": "string"}},
                "next_action": {"type": "string"}
            },
            "required": ["status", "evidence", "next_action"],
            "additionalProperties": False
        }
    }
}

Anthropic 当前文档明确说明，Structured Outputs 可以减少非法 JSON、缺失字段和类型不一致问题，但拒绝响应和 max_tokens 截断仍然是异常分支；遇到拒绝时，HTTP 状态可能仍是 200，但内容不一定符合你的 Schema。具体限制见 Structured Outputs 官方文档。

因此，解析器不要只写成：

data = json.loads(response.content[0].text)

你还应先检查：

if response.stop_reason == "refusal":
    return {"status": "manual_review"}

if response.stop_reason == "max_tokens":
    return retry_with_larger_budget()

# 再解析文本并做业务层校验

Schema 也不能无限堆叠。当前 Structured Outputs 文档列出的显式限制包括：单次请求最多 20 个严格工具、所有严格工具和 JSON 输出合计最多 24 个可选参数、联合类型参数最多 16 个；复杂 Schema 还可能触发 180 秒编译超时。

配置项	解决的问题	不负责解决的问题	上线判断
`strict: true`	工具名和输入参数不符合 Schema	工具是否有权限、是否重复执行	高风险工具优先开启
JSON 输出 Schema	最终报告难解析、字段不稳定	工具执行失败、外部系统超时	需要下游自动消费时开启
`tool_choice`	模型没有按预期调用工具	工具执行本身是否成功	必须查数据时可强制
应用层校验	越权、业务规则、参数范围	模型是否选择了最佳工具	永远保留
人工审批	付款、删除、发送等不可逆动作	普通只读查询	高风险动作必备

首次使用某个 Schema 时，服务端还需要编译语法结构；官方说明编译结果会从最后一次使用起缓存 24 小时，修改 Schema 结构或工具集合会使缓存失效。上线前不要只测“第二次请求”，应单独记录首次请求延迟。

失败控制

生产 Agent 最容易出问题的地方，不是模型是否会调用工具，而是调用失败后应用如何处理。

建议把错误分成 4 类：

参数错误： 不重试模型调用，先返回可修复的校验信息，或让模型重新生成参数。
临时网络错误： 允许有限次数重试，并使用相同幂等键。
业务拒绝： 例如账户无权限、订单已关闭，直接记录原因，不要盲目重试。
不可逆动作： 进入人工审批队列，审批通过后才执行。

每一次工具执行都应生成一个业务级幂等键，例如：

agent_run_id + tool_name + logical_action_id

执行器收到相同幂等键时，先查询历史状态。如果之前已经成功，不要再次扣款、发信或修改记录；如果之前处于处理中，则返回处理中状态，让 Agent 继续解释，而不是再次发起动作。

超时也应按工具区分。只读搜索、文件读取和本地状态查询可以采用较短的工具级超时；涉及远程构建、测试或图形界面操作的工具，必须把排队时间、执行时间和回收时间分开记录。不要用一个全局超时覆盖所有工具，否则慢任务会拖垮整个 Agent，快任务又无法及时失败。

日志至少包含：

agent_run_id 与请求时间；
模型名、请求版本和 stop_reason；
tool_use.id、工具名和脱敏后的参数摘要；
参数校验结果、执行开始与结束时间；
超时、重试、幂等命中和人工审批状态；
tool_result 的状态摘要；
最终响应是否通过业务 Schema 校验。

密钥、用户隐私数据和完整源码不应直接写入普通日志。你可以在 Macstripe 帮助中心中继续核对远程运行所需的账号、连接和基础环境事项，但密钥轮换仍应由你的部署系统负责。

MCP 扩展

MCP 不是 Claude Tool Use 的替代品，而是共享工具的连接层。

如果只有一个后端服务、几个自有函数，并且工具权限可以在应用内部统一管理，直接把工具定义传入 Claude Sonnet 5 API 通常更简单。只有在多个客户端需要发现和复用同一批工具时，MCP 的收益才会超过额外复杂度。

MCP 接入前检查：

远程 MCP Server 是否使用稳定的 HTTPS 连接。
授权令牌是否按用户、团队或环境隔离。
工具清单变化是否会被记录和审核。
第三方工具返回的数据边界是否明确。
网络断开、授权过期和工具下线时是否有降级路径。
工具是否真的需要暴露给每个 Agent，而不是按需加载。

官方 MCP Connector 文档支持在 Messages API 中连接远程 MCP Server；响应中会出现 MCP 工具调用与结果类型，因此你的日志和解析器不能只识别普通 tool_use。接入前可参考 MCP Connector 官方说明。

不要把 MCP 当作“多接工具就更强”。 工具数量增加后，模型选择、授权范围、Schema 编译、网络故障和第三方数据泄露面都会扩大。先证明共享需求，再增加协议层。

上线验收

远程环境的验收目标不是证明某一次调用成功，而是证明 Agent 在真实任务中可恢复、可追踪、可回滚。

建议按下面的时间线执行：

阶段	验收动作	通过标准	不通过时的回退
第 1 阶段	只读工具闭环	`tool_use`、执行、`tool_result` 全部可追踪	移除所有副作用工具
第 2 阶段	低风险动作	幂等键生效，重复请求不重复执行	改为草稿或模拟执行
第 3 阶段	严格参数与最终 JSON	正常、拒绝、截断均有分支	暂时关闭复杂 Schema
第 4 阶段	MCP 远程连接	授权、清单、断线恢复可记录	回退到应用直接托管工具
第 5 阶段	远程长期运行	进程、日志、密钥、网络和回滚均可操作	先小规模灰度，不接生产数据

远程 Mac 上至少检查以下项目：

进程是否由守护机制自动拉起，异常退出后是否能区分崩溃与主动停止；
环境变量是否通过安全注入，而不是写进仓库或启动脚本；
SSH、HTTPS、MCP 连接是否分别设置网络超时；
日志是否包含轮转策略、错误级别和请求关联 ID；
API 密钥、MCP 授权令牌和业务凭据是否可以单独轮换；
新版本发布失败时，是否能回退到上一份可运行的 Agent；
实际任务是否覆盖工具成功、工具超时、权限拒绝、重复调用和人工审批。

如果你需要在 Mac 上运行代码 Agent、测试自动化脚本或验证 MCP Server，建议先阅读 Macstripe 的配置下单页面，按任务周期选择临时环境，再把真实任务拆成小批量验收。本文不把远程 Mac 当成 Claude API 的替代品：模型调用仍由 Anthropic API 完成，Mac 负责承载你的执行器、项目文件、进程和日志。

常见疑点

FAQ：工具结果为什么没有被 Claude 接收？

最常见原因是 tool_result 没有紧跟对应的 assistant 消息，或者 tool_use_id 没有使用模型返回的原始 ID。你还要确认结果消息使用 user 角色，并检查并行工具调用时是否为每个工具都返回了对应结果。

FAQ：严格模式是不是越早开启越好？

不是。严格模式适合参数错误会造成真实损失的工具，但复杂 Schema 会增加编译和维护成本。建议先用简单 Schema 跑通业务，再只给关键工具开启 strict: true，并在应用层继续执行权限、范围和幂等检查。

FAQ：MCP 连接失败时应该怎么办？

先记录授权状态、远程连接错误、工具清单版本和失败时间，再把该工具标记为不可用。不要让 Agent 无限重试；如果业务允许，应回退到本地只读工具或人工处理，并在恢复后重新执行未完成任务。

方案取舍

自建一台本地 Mac 适合长期稳定运行、需要物理接口或必须完全掌控系统环境的团队，但你要承担设备采购、系统更新、远程访问、磁盘维护、进程守护和故障恢复。临时云主机则可能遇到 macOS 兼容性、图形化工具、签名环境或本地开发链路不一致的问题。

如果你的任务是短期验证 Claude Agent、跑一轮真实代码任务、测试 MCP Server，或者需要一个可随时释放的远程 Mac 环境，Macstripe 的租赁方式通常比临时采购设备更容易控制周期；但对于持续高负载、需要固定硬件接口或已经拥有成熟运维团队的项目，直接自购设备可能更合理。先用小规模真实任务验收工具闭环，再决定是否延长租赁周期，通常比一开始就把整个生产系统迁移过去更稳妥。

常见问题

Claude Sonnet 5 API 怎么调用外部工具？

你需要先在请求中声明工具名称、用途和 input_schema，再读取 Claude 返回的 tool_use 内容块。外部代码由你的应用执行，随后用紧邻的 tool_result 消息返回结果，最后再让模型生成用户可读的答案。

Claude strict tool use 应该怎么配置？

在自定义工具定义中加入 strict: true，并让对象使用 required 与 additionalProperties: false。严格模式只负责约束工具名称和输入参数，不负责保证最终自然语言或 JSON 报告的格式，后者应交给 Structured Outputs。

Claude 工具调用后如何返回结果？

应用必须保存 tool_use.id，并在下一条 user 消息中用 tool_result.tool_use_id 精确匹配。tool_result 要紧跟产生它的 assistant 消息；执行失败时可以设置 is_error: true，让模型决定如何解释或重试。

Claude API 和 MCP 应该一起使用吗？

不必一开始就同时使用。单个 Agent 或单个服务优先采用应用直接托管的客户端工具；当多个客户端需要发现、复用和统一授权同一批远程工具时，再增加 MCP 层，避免过早引入连接与权限故障。

Claude Agent 部署需要哪些日志？

至少记录请求关联 ID、模型、工具名、tool_use.id、参数校验结果、执行耗时、超时与重试次数、tool_result 摘要、stop_reason、最终状态和人工审批结果。不要把 API 密钥或完整敏感业务数据直接写入普通日志。