这次我们来看 Claude Platform 系列里的第三个主题tools。前两期如果已经聊过模型基础能力和平台入口那这一期的重点就很明确让 AI 不只会“说”还能“做”。所谓 tools在 Claude Platform 的语境里就是模型通过 API 调用外部函数、搜索引擎、数据库、HTTP 服务等能力拿到结果后继续推理、继续回答。这套机制有四个关键点第一它解决的是模型输出与真实系统之间的交接问题。模型不直接执行代码而是给出一份结构化的“调用请求”由你自己的程序去执行再把结果回传给模型。第二它让你的业务系统可以通过标准接口把私有能力暴露给 AI 使用。你不需要把订单数据、用户信息直接塞进提示词而是让模型按需查询。第三它天然适合自动化流程、批量任务和 Agent 式应用。模型可以在一次任务里连续调用多个工具直到把问题解决。第四它不需要本地 GPU不需要显存只需要调用云端 API。这意味着普通开发者电脑只要能联网、能跑 Python就能开发出具备工具调用能力的应用。这篇文章会用 Python SDK 走通一个完整的 tools 示例从定义工具到触发调用再到回传结果最后做成一个能批量处理的工具循环。如果你想在自己的业务里接入 Claude Platform或者想理解 AI Agent 底层的工作方式这篇文章可以直接收藏。1. 核心能力速览能力项说明项目/能力Claude Platform 工具调用Tool Use / Tools官方来源Anthropic Claude Platform以官方文档为准核心价值让 Claude 模型通过 API 调用外部工具再把结果用于后续推理使用方式Anthropic API / Python SDK / API Console是否依赖本地 GPU不依赖是否支持 CPU 推理不涉及本地推理模型在云端运行是否提供接口是标准 REST API 与官方 SDK是否支持批量任务可以结合工具循环和任务队列实现批量处理是否支持 MCP以官方文档当前支持情况为准MCP 是工具标准化的重要方向适合场景自动化流程、Agent 应用、业务系统集成、私有数据查询、外部服务联动这里先说明一下Claude Platform 是托管 API 服务不是本地模型所以不需要讨论显存占用和一键启动这类本地部署问题。更值得关注的是它的接口能力、工具定义方式、模型调用逻辑和批量任务编排。从实际开发角度看tools 的定位非常明确模型负责理解意图、拆解任务、生成结构化调用请求程序负责真正执行然后把执行结果交给模型做下一步判断。这种“模型做大脑、代码做手脚”的分工是当前 AI 应用落地最常见也最稳的形态。2. Tools 是什么AI 从“生成文本”到“执行动作”先理清一个基础问题为什么模型需要 toolsClaude 这类大模型本身是文本生成模型。它接收文本输入输出文本结果。它不能直接查你的数据库不能直接调用你的订单系统也不能直接操作系统文件。它的一切知识都来自训练数据和上下文一旦遇到需要实时数据或业务系统数据的问题直接问模型是得不到准确答案的。tools 机制解决了这个问题。它的工作流程可以概括为四个步骤第一步开发者在请求里定义工具列表。每个工具包含名称、描述和参数结构例如“query_order_status”这个工具接收一个 order_id 参数。第二步模型在回答用户问题时如果发现调用工具能更好地回答就会返回一个 tool_use 块里面包含工具名和参数例如{name: query_order_status, input: {order_id: ORD-2024-001}}。第三步你的程序收到 tool_use 后执行对应的业务函数拿到结果再把结果包装成 tool_result 回传给模型。第四步模型根据工具返回的结果生成最终回答。整个过程是个多轮循环。模型可以连续调用多个工具每调用一次就获得新信息然后继续推理。这就是 Agent 式应用的基础循环。一个容易理解的类比是甲方负责提需求和做判断乙方负责执行具体动作。模型是甲方你的代码是乙方。模型不会自己登录系统但它会告诉你“我需要订单 ORD-2024-001 的状态”你的代码去查然后把状态告诉模型模型再根据这个状态给你一个完整的回答。这种设计有三个好处一是职责清晰。模型只负责语义理解和任务规划实际动作由可控的代码执行。二是安全可控。你可以在工具函数里做权限校验、限流、审计而不是把整个系统敞给模型。三是可扩展。任何系统能力都可以封装成一个工具让模型按需调用。3. Claude Platform 中的 Tools 体系在 Claude Platform 里tools 并不是一个单独的功能按钮而是一整套可供模型调用的能力集合。从开发者的角度可以分成三个层次来看。3.1 自定义工具 / Function Calling这是最基础、最核心的能力。开发者通过 API 的 tools 参数传入 JSON Schema 格式的工具定义模型就会在合适的时候发起调用。工具定义的核心字段包括name工具名必须是唯一的。description描述说明这个工具是做什么的、什么时候该用。模型就是靠描述来决定是否调用。input_schema参数结构遵循 JSON Schema 规范。模型会在这里面提取参数。自定义工具适合所有业务场景。你需要的不是“让模型什么都做”而是让模型按你的规则调用你提供的函数。3.2 工具选择策略Claude API 提供了 tool_choice 参数用来控制模型调用工具的行为。常见的选择策略有auto模型自行判断是否需要调用工具适合大多数场景。any强制模型在本次请求中必须调用至少一个工具适合需要固定工具流程的场景。指定工具强制模型调用某个特定工具例如tool_choice{type: tool, name: query_order_status}适合已经确定要执行某类操作时使用。不同策略对应不同业务。如果是开放式问答用 auto如果是固定流程例如所有请求都必须先查数据库用指定工具会更稳定。3.3 MCP 与工具生态随着工具调用逐渐普及一个很现实的问题出现了每个数据源、每个软件都单独对接适配成本太高。于是出现了 MCPModel Context Protocol一种开放协议目标是让模型通过统一方式连接数据源和工具。从工程实践看MCP 确实减少了大量重复适配工作。它把“工具的定义、执行、结果返回”标准化一次接入多处复用。不过需要说明的是MCP 是否已经成为“标准结构”还得看生态后续发展。在 Claude Platform 中如何接入 MCP、支持哪些版本的 MCP Server建议以官方文档当前的说明为准。如果你正在做 Agent 或企业级 AI 集成MCP 值得重点关注但不要急着把所有能力都迁过去。先把自定义工具跑通再评估是否引入 MCP这是更稳妥的路径。4. 环境准备与前置条件Claude Platform 的 tools 开发门槛很低不需要本地 GPU也不需要下载模型文件。你需要准备的是4.1 基础条件一个 Anthropic 账号并进入 Console 管理后台。一个 API Key用于通过 API 访问 Claude 模型。Python 3.9 或更高版本。能正常访问 Claude API 服务端点。具体网络要求以你的实际环境和合规要求为准。安装 anthropic 官方 Python SDK。4.2 安装 SDK 与配置密钥推荐把 API Key 写入环境变量而不是硬编码在代码里。pip install anthropic在 Linux / macOS 上设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxxxx在 Windows PowerShell 上设置环境变量$env:ANTHROPIC_API_KEY sk-ant-xxxxxx设置完成后可以用下面这段代码验证 SDK 是否安装成功、密钥是否生效import os import anthropic client anthropic.Anthropic() # 打印环境变量是否存在不打印密钥本身 print(API Key configured:, bool(os.getenv(ANTHROPIC_API_KEY)))4.3 最小请求验证在写工具调用之前先发一个最简单的消息请求确认 API 通路正常。import anthropic client anthropic.Anthropic() response client.messages.create( # model 参数请以官方文档当前可用的模型 ID 为准 modelclaude-3-5-sonnet-latest, max_tokens100, messages[ {role: user, content: 请回复OK} ] ) print(response.content[0].text)如果这一步能返回文本说明账号、密钥、SDK、网络链路都没问题。接下来就可以进入工具调用的正题。5. 完整示例让 Claude 调用自定义工具下面用一个“订单状态查询”场景演示完整流程。这个示例的核心是模型不直接知道你订单系统里的数据它通过调用 query_order_status 工具获得结果再基于结果回答用户。5.1 定义工具import anthropic client anthropic.Anthropic() # 需要配置 ANTHROPIC_API_KEY 环境变量 TOOLS [ { name: query_order_status, description: 根据订单号查询当前配送状态。当用户询问订单、发货、物流状态时使用。, input_schema: { type: object, properties: { order_id: { type: string, description: 订单号例如 ORD-2024-001 } }, required: [order_id] } } ]description 字段非常关键。模型根据 description 判断“什么时候调用这个工具”。描述越清晰模型调用越准确。如果描述写得太含糊模型可能在没必要的时候也调用。5.2 实现工具函数def query_order_status(order_id: str) - dict: # 真实场景中替换为你的数据库查询或内部接口调用逻辑 fake_orders { ORD-2024-001: {status: 已发货, logistics: 顺丰, eta: 2025-02-20}, ORD-2024-002: {status: 待发货, logistics: -, eta: 待确认}, } return fake_orders.get(order_id, {status: 未找到, logistics: -, eta: -})真实开发中这个函数内部可以写数据库查询、调用内部 RPC、请求第三方物流 API。只要返回结果是可序列化的字符串或字典即可。5.3 实现工具调用循环工具调用是多轮交互。模型返回 tool_use 后程序执行工具把结果回传然后模型继续生成。代码如下def run_with_tools(user_message: str, max_loops: int 5): messages [{role: user, content: user_message}] for _ in range(max_loops): response client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens1024, toolsTOOLS, messagesmessages ) # 判断是否需要调用工具 tool_results [] for block in response.content: if block.type tool_use: result query_order_status(block.input[order_id]) tool_results.append( { type: tool_result, tool_use_id: block.id, content: str(result) } ) if tool_results: # 先把模型的 tool_use 输出追加到消息历史 messages.append({role: assistant, content: response.content}) # 再把工具执行结果回传给模型 messages.append({role: user, content: tool_results}) # 继续下一轮让模型基于结果生成回答 continue # 没有工具调用说明模型已经准备好最终回答 return response raise RuntimeError(超过最大工具调用轮次)这个循环是 Claude tools 开发的核心模式第一步携带 tools 定义发给模型。第二步检查 stop_reason 或 content 中是否有 tool_use。第三步执行工具把 tool_result 回传。第四步继续循环直到模型不再请求工具。注意tool_result 里的 tool_use_id 必须和模型返回的 block.id 严格一致。如果对不上API 会报错。5.4 测试运行if __name__ __main__: response run_with_tools(订单 ORD-2024-001 现在到哪里了) for block in response.content: if block.type text: print(block.text)预期输出类内容订单 ORD-2024-001 已通过顺丰发货预计 2025-02-20 送达。整个过程模型其实并不知道订单数据它只是请求调用工具然后再把工具返回的信息组织成自然语言回答。这就是 tools 的本质把外部数据接入模型推理链。6. 进阶多工具、批量任务与 Agent 场景6.1 多工具并存实际业务中不会只有一个工具。你可以同时定义 query_order_status、refund_order、send_message 等工具模型会根据用户意图自动选择。工具变多之后描述要尽量精简但语义明确。每个工具都占用输入 token工具列表太长会增加请求体积和成本。更合理的做法是按业务域拆分不同的请求只带相关的工具。6.2 强制调用指定工具有些场景下你不能让模型随意选择需要强制调用某个工具。这时候用 tool_choiceresponse client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens1024, toolsTOOLS, tool_choice{type: tool, name: query_order_status}, messagesmessages )强制指定工具适合“固定流程”场景。例如所有客服请求都必须先查订单再决定后续动作。6.3 批量任务处理tools 调用的批量处理最直接的方式是循环。把一批输入依次交给 run_with_tools然后收集结果。order_ids [ORD-2024-001, ORD-2024-002, ORD-2024-003] results [] for order_id in order_ids: user_msg f帮我查询订单 {order_id} 的状态 try: response run_with_tools(user_msg, max_loops3) text .join( block.text for block in response.content if block.type text ) results.append({order_id: order_id, result: text}) print(f{order_id}: {text}) except Exception as e: results.append({order_id: order_id, error: str(e)}) print(f{order_id}: FAILED - {e})批量任务要注意三个问题控制并发。官方 API 有速率限制大批量任务建议串行或设置 semaphore。记录日志。每个订单的 tool_use、工具返回值、最终输出都建议落盘方便排查。失败重试。API 超时、限流都可能收到异常建议加指数退避重试。6.4 从 Tool Use 到 Agent当模型可以连续多次调用工具并在每次调用后根据结果调整下一步计划这套循环就变成了 Agent。一个典型的多步 Agent 流程可能是查询用户订单 - 判断是否发货 - 如果未发货则查询库存 - 如果无库存则通知人工。每一步都依赖上一步的工具结果而模型负责根据这些结果做决策。这种模式比简单的“一问一答”更接近真实业务系统。不过 Agent 开发和调试成本也更高因为模型可能走错分支、调用错误工具、陷入死循环。工程上要有限制手段最大调用轮次、必调工具白名单、人工审批节点、日志审计。7. 成本、速率与性能观察虽然是云端 API没有显存和显卡的问题但 tools 开发同样需要关注资源消耗和性能。7.1 Token 消耗每次请求你都要把完整的工具列表作为输入传给模型。工具 schema 越多越长消耗的输入 token 越多。如果同时还有很长的消息历史输入 token 会快速累积。建议在开发时打印每次请求的 usage观察工具定义和上下文对 token 的影响print(response.usage)如果工具描述写得冗长可以考虑精简字段描述、减少工具数量或者按路由拆分不同的工具集合。7.2 响应延迟工具调用通常意味着多个 round trip。比如第一次请求模型返回 tool_use第二次请求带上 tool_result这个来回至少多出一次完整请求的延迟。如果任务依赖多个工具延迟会更高。批量任务不要使用单线程同步调用跑几千条数据。建议配合异步队列限制并发数并且设置合理超时。7.3 速率限制官方 API 对每分钟请求数、每分钟 token 数都有速率限制。开发阶段遇到的问题通常不大生产环境一定要关注。做法是在代码里统一管理请求入口遇到 429 状态码做退避重试。7.4 本地程序的资源占用Claude 模型不在本地跑但你的调度程序、工具函数、日志系统都消耗本地资源。批量处理大文件、频繁调用外部接口时注意内存使用、磁盘日志增长和第三方接口配额。8. 常见问题与排查方法问题现象可能原因排查方式解决方案401 AuthenticationErrorAPI Key 无效或未设置环境变量检查环境变量和 Console 密钥状态重新生成 Key确认 ANTHROPIC_API_KEY 已设置400 工具 schema 格式错误input_schema 不符合 JSON Schema 规范打印 tools 定义检查 name/description/required按官方 schema 规范修正stop_reason 为 tool_use 但没有执行任务工具执行结果未正确回传检查 messages 是否包含 tool_result 且 tool_use_id 匹配确保 tool_use_id 对应模型返回的 block.id工具调用后模型仍答错工具返回内容格式混乱查看 tool_result 的 content 是否可读规范工具返回值使用结构化 JSON批量任务超时最大调用轮次过小或 API 限流查看日志、检查 usage 和状态码增大 max_loops、增加重试和退避输入 token 超限工具定义过多且历史上下文过长查看 usage 中 input_tokens精简 schema、截断历史消息、增大 max_tokens无法强制调用指定工具tool_choice 参数写错检查参数格式和工具名使用tool_choice{type: tool, name: xxx}tool_result 报错assistant 消息顺序不正确检查消息历史是否按 user、assistant 交替工具调用后必须先追加 assistant content再追加 user tool_resultMCP Server 连不上地址、鉴权或协议版本不匹配查看 MCP Server 端日志以官方文档为准检查配置和版本这里重点提一个最容易踩的坑消息历史顺序。在工具调用循环中你不能在模型返回 tool_use 之后直接追加 tool_result。必须先把模型返回的整个 response.content 作为 assistant 消息追加然后再追加 tool_result 作为 user 消息。顺序错了API 会报错或者模型上下文理解错乱。另一个常见坑是 tool_use_id 不匹配。工具执行完回传时tool_result 中的 tool_use_id 一定要用模型返回的 block.id而不是工具名或手动生成的随机值。多工具并行调用时尤其容易漏。9. 最佳实践与安全边界tools 能力越强安全边界就越重要。模型执行真实操作时不能无约束放权。9.1 最小权限原则给模型暴露的工具权限要足够小。查询工具只给查询权限不要给写权限写操作如果需要也要在工具内部做好权限校验。9.2 高危操作人工确认涉及删除、退款、下单、发布、转账等高危动作不要在工具函数里直接执行。更稳妥的做法是让工具返回一个“待确认”状态由用户在前端确认后再真正执行。9.3 隐私与数据合规工具涉及用户个人信息、通讯录、订单数据时必须做访问控制和脱敏。模型每次工具调用都会把参数发送到 API敏感字段要避免出现在工具参数里。日志中也不要记录完整敏感信息。9.4 版权与素材授权如果工具用于抓取外部内容、生成图片视频、处理他人作品必须确认素材的合法来源和授权范围。生成内容如果用于商用还要留意模型使用条款和生成内容的知识产权归属。9.5 日志与审计记录每一次 tool_use 的工具名、参数、执行结果、耗时和 token 消耗。生产和测试环境都要留痕。这是排查问题和责任追溯的基础。9.6 工程化建议第一次接入时先小参数测试跑通一个最小工具工具函数和 API 调用分开封装模型返回、工具结果、最终回答分文件管理批量任务加日志和失败重试发布前做一轮完整的效果复核。10. 总结与下一步这一期把 Claude Platform 的 tools 能力从机制讲到了完整示例。核心是理解那个循环模型请求调用工具代码执行工具结果回传给模型模型继续判断。这个循环是所有 Agent 和工具型应用的底座。最值得先验证的是跑通一个自定义工具。随便定一个查询函数看模型什么时候返回 tool_use看 stop_reason 如何变化看 tool_result 回传后模型的最终回答质量。这一圈走下来你对 AI 如何“动手做事”的认识会清晰很多。最容易踩的坑是消息历史顺序和 tool_use_id 匹配。写循环之前先把这两点刻在脑子里。下一步可以考虑往三个方向扩展一是把真实业务接口封装成工具二是研究一下 MCP统一数据源接入三是把工具循环升级成带决策能力的 Agent加上任务队列和人工审批节点。建议先收藏这篇文章动手跑通示例后再往自己的场景迁移。工具调用的上限取决于你愿意开放多少真实能力给模型使用。