Claude 做 AI Agent 实战：从工具调用到长文本处理的落地经验（2026）

去年底拿到一个需求：做一个能自动审合同的 Agent。用户丢进来一份 PDF，Agent 提取关键条款、检查风险点、标注不合理的地方、生成审查报告。合同长度从几页到几百页都有。

一开始想得挺简单——调 Claude API，传文档进去，让它输出分析结果。做下来才发现，“调一次 API”和”做一个 Agent”之间差着十万八千里。单次调用处理不了多步推理，长文档得想分段策略，工具调用得设计循环编排。跑久了 token 成本像水表一样转，这个后面细说。

这篇不是 Agent SDK 的入门教程，那些官方文档写得够清楚了。我主要想聊三件事：什么场景值得上 Agent、工具编排怎么设计比较省心、1M 上下文到底该怎么用才不翻车。

什么时候该用 Agent，什么时候单次调用就够了

这是第一个要想清楚的问题，因为答案直接影响开发成本和系统复杂度。

单次调用能搞定的事情，就别上 Agent。比如：翻译一段文本、总结一篇文章、回答一个知识性问题。这些任务有明确的输入和输出，中间不需要决策分叉，一次 API 请求就能拿到结果。

Agent 解决的是另一类问题——任务本身需要多步决策，每一步的结果影响下一步该做什么。回到合同审查的例子：Agent 先要判断合同类型（劳动合同、采购合同、服务协议），然后根据类型加载对应的审查规则，接着逐条提取条款并比对，发现问题后还要回头交叉验证上下文。这个过程不是线性的，Agent 需要在中间做判断、调工具、循环往复。

我的判断标准很粗暴：如果你发现自己在 prompt 里写了”如果…则…”的逻辑超过三层，大概率应该拆成 Agent。

几个典型场景：

客户问”我的订单什么时候到”，Agent 要先查订单系统拿到物流单号，再查物流接口拿到运输状态，最后组织语言回复。两次工具调用的顺序和参数都依赖前一步的结果，单次 API 调用做不到。

代码生成也是。Agent 写完代码，执行一下，发现报错，读错误信息，修改代码，再执行。这个循环可能跑好几轮。Claude Code 就是这么干的。

还有数据分析这种跨工具的场景：SQL 查数据库，Python 做清洗计算，图表工具出可视化，最后输出报告。工具之间有依赖关系，不是简单的并行。

Agent SDK 选型：Python 还是 TypeScript

Anthropic 的 Agent SDK 有 Python 和 TypeScript 两个版本，核心功能一致。选哪个取决于你的技术栈，不用纠结。

Python 版的生态更成熟一些，和 LangChain、LlamaIndex 等框架的集成更方便，做数据处理和机器学习相关的 Agent 首选 Python。TypeScript 版在 Web 应用场景更顺手，如果你的 Agent 要嵌入到 Node.js 后端或者 Next.js 应用里，TypeScript 省去了跨语言通信的麻烦。

两个版本都包含几个我觉得比较关键的能力。工具定义和调用循环不用说了，你定义 JSON Schema，SDK 管整个”模型决策→调工具→返回结果→继续推理”的循环。上下文自动压缩也很实用，对话太长时 SDK 自动把早期内容摘要化，不会因为上下文溢出而崩掉。MCP 服务器可以直接接入，不用自己写适配层。还有个 max_budget_usd 参数能设花费上限，防止跑飞了。

一个关键的设计选择是工具的粒度。我最开始犯的错误是工具定义得太细——把”读文件""写文件""列目录""搜索文件”拆成四个独立工具。结果 Agent 在执行简单的文件操作时也要跑好几轮工具调用循环，每轮都消耗 token。后来把相关操作合并成一个”文件系统”工具，通过参数区分动作类型，调用次数直接减少了一半多。

但也不能合并得太狠。如果一个工具的参数组合太多，模型选参数的准确率会下降。经验上，每个工具的参数控制在 5 个以内、工具总数控制在 15-20 个以内，Claude 的调用准确率最好。超过 20 个工具之后，可以考虑按任务阶段动态加载——比如”分析阶段”只暴露读取和查询类工具，“执行阶段”再加入写入和发送类工具。这个思路在之前的 Claude Tool Use 教程里详细讲过。

1M 上下文：不是越长越好

Claude Opus 4.6 和 Sonnet 4.6 都支持 1M token 的上下文窗口，这是 2026 年 3 月正式 GA 的功能，标准定价不加钱。1M token 大约相当于 50 万中文字，放进去一整本《三体》都绰绰有余。

但用长上下文有个大坑——不是把所有东西都往 context 里塞就完事了。

长上下文的正确打开方式

最适合长上下文的场景是”信息密度高、检索难度大”的任务。

比如整体代码库分析。把一个中型项目的源码全部塞进上下文，让 Claude 理解完整的架构后再回答问题或做修改。比 RAG 好在哪？不会因为检索不到某个关键文件而遗漏依赖关系。Claude Code 就是这么工作的——它把整个项目的文件树和关键文件都读进上下文。

合同审查、学术论文综述、财报分析也适合。这类任务需要前后交叉引用，文档内容之间有复杂的指代和逻辑关系，切片后单独分析会丢失全局信息。

还有一种场景容易被忽略：多轮对话记忆。Agent 跑了好几个小时，早期的对话内容随着时间推移可能再次变得重要。完整保留上下文比事后检索更可靠。

不适合硬塞的场景

如果你的文档内容是”扁平”的——比如一千条客户反馈、一大堆日志条目——每条之间没有关联性，那用 RAG 检索相关条目再喂给模型更划算。把一千条反馈都塞进上下文，模型会认真读完每一条，token 费用上去了，结果未必比检索 top-20 再分析好多少。

简单来说：需要全局理解的用长上下文，需要局部查找的用 RAG。

成本意识

1M token 的输入不便宜。Opus 4.6 的输入定价是 $5/百万 token，这意味着填满整个窗口一次就是 $5。如果 Agent 跑了十几轮，每轮都带着完整上下文，成本会很快失控。

两个实用的控制手段：

用 Sonnet 4.6 替代 Opus 4.6 做”粗活”。 Sonnet 的输入价格是 $3/百万 token，输出是 $15/百万 token。合同审查这个项目里，我让 Sonnet 做初步的条款提取和分类，只在发现高风险条款需要深度分析时才切换到 Opus。整体成本降了大约 40%。

善用上下文压缩。 Agent SDK 的自动压缩机制会在上下文接近窗口上限时，把最早的对话内容摘要化。这个机制是服务端处理的，你不需要自己写压缩逻辑。但要注意：压缩会损失细节。如果你的 Agent 可能在第 50 轮对话中需要引用第 3 轮的某个具体数据，最好把关键数据持久化到外部存储，而不是依赖上下文记忆。

关于 Claude API 的定价和成本优化，之前那篇 Claude API 流式输出和批量调用教程有更详细的拆解，特别是 Batch API 可以打五折这件事，跑大量 Agent 任务时非常值得用。

Agent 工具编排：我趟过的几个坑

做了三个月 Agent 项目，踩过的坑不少。挑几个有代表性的说。

工具描述比工具实现更重要

这话听起来反直觉，但事实如此。Claude 选择调用哪个工具、传什么参数，完全依赖你写的工具描述（description）和参数描述。工具的实际实现可以很糙，但描述必须精确。

一个反面例子：我最初给”查询订单”工具的描述写成”查询订单信息”。结果 Claude 在用户问”帮我取消订单”的时候也调了这个工具——因为”取消订单”也涉及”订单信息”。改成”根据订单号查询订单状态、物流信息和金额明细，仅限读操作，不修改任何数据”之后，误调用消失了。

几条经验：说清楚工具做什么和不做什么，“读操作，不修改数据”这种约束比你想象的重要。参数描述带上格式和范例——不要只写”订单号”，写”订单号，格式为 ORD-XXXXXX，例如 ORD-202604”。另外，明确触发条件，比如”当用户询问订单状态或物流进度时使用”。

错误处理决定 Agent 的鲁棒性

Agent 和单次 API 调用最大的区别是：Agent 会出错，而且必须能从错误中恢复。

工具调用失败是常态。数据库偶尔超时、第三方 API 返回 500、文件路径不存在。如果你的 Agent 遇到工具报错就直接崩溃，那它在生产环境活不过一天。

我的做法是：工具执行失败时，把错误信息原封不动地返回给 Claude，让它自己决定怎么处理。Claude 在这方面意外地靠谱——它会尝试换参数重试，或者换个工具绕过去，实在不行就直接告诉用户”这个操作暂时没法完成”。

如果调用 Claude API 本身出了问题（比如 429 限流或者 529 过载），Agent SDK 有内置的重试机制。具体的错误码和处理策略可以参考 Claude API 报错汇总。

多 Agent 协作不如单 Agent 多工具

有段时间流行”Agent Swarm”的说法——多个 Agent 各自负责一个子任务，通过消息传递协作。我试过这个架构，结论是：大多数场景下，一个 Agent 配上足够的工具就够了，拆成多个 Agent 反而增加了通信开销和状态同步的复杂度。

多 Agent 真正有价值的场景是工具集完全不重叠、且子任务之间相对独立的情况。比如一个负责代码分析、一个负责文档写作、一个负责测试执行。它们各自干活、最后汇总结果，中间不需要频繁交互。如果你的子任务之间需要频繁传递上下文，单 Agent 方案的效率远高于多 Agent。

长文本处理：分段还是整塞

回到一开始的合同审查需求。合同文档长度差异极大，短的几页，长的几百页。怎么处理？

短文档（< 50 页）：直接塞

50 页以下的文档，token 数通常在 5 万以内，Opus 4.6 的 1M 窗口完全装得下。直接把全文 + 审查指令一起发给 Claude，一次搞定。这是最简单也最准确的方案，因为模型看到的是完整信息。

中等文档（50-300 页）：整塞 + 分步指令

这个范围的文档（大约 5-30 万 token）塞进上下文没问题，但一次让模型完成所有审查任务容易丢漏。更好的做法是分步提问：第一轮让模型提取所有关键条款的摘要，第二轮针对具体条款做风险评估，第三轮生成报告。每一轮都能看到完整原文，但任务范围是收敛的。

超长文档（> 300 页）：分段 + 汇总

超过 30 万 token 的文档可能接近窗口上限，需要分段处理。但分段不是随便切——按章节或按条款切，保证每一段的语义完整。每段单独分析后，再把各段结果汇总，用 Claude 做全局交叉检查。

分段处理时有个技巧：每段开头附上全文的目录和前一段的分析摘要。这样模型在处理当前段时，至少知道全局结构和前面的结论，不会产生矛盾。

国内接入：换个地址就行

Claude Agent SDK 默认连接 api.anthropic.com，国内直连不了。但解决方案和普通 Claude API 调用一样——SDK 初始化时把 base_url 改成国内可访问的 API 聚合平台地址。

通过 ofox.ai 这样的聚合平台接入，tool use、streaming、长上下文等功能全部可用，体验和直连官方没区别。平台兼容 OpenAI SDK 协议，如果你习惯用 OpenAI 的 function calling 格式，也不用改代码。

具体的配置步骤在《Claude API 国内怎么用》里写过了，这里不重复。Claude Code 的接入方式也是类似的思路。

成本参考

用 Claude 做 Agent 到底要花多少钱，取决于三个变量：模型选择、上下文长度、调用轮数。

以合同审查 Agent 为例，处理一份 100 页的合同（约 10 万 token），通常需要 3-5 轮工具调用：

如果用 Batch API 处理不急的任务，成本再打五折。一天审 100 份标准合同，全程 Sonnet + Batch，日均成本大约 $40-75。

具体到你的项目，建议先用 max_budget_usd 设一个上限跑几天，看看实际消耗，再决定优化方向。

回头看

做了三个月，最大的感受是 Agent 开发的难度不在调 API，在工程设计。Agent SDK 把底层的脏活封装得已经很好了，1M 上下文也基本消灭了”文档太长处理不了”这个老问题。真正让项目卡壳的是工具描述没写好导致的误调用、上下文管理不当导致的成本失控、以及错误恢复机制没做全导致的线上崩溃。

这些东西没有捷径，只能靠跑真实场景积累经验。如果你也在做类似的事情，几篇可能有帮助的文章：tool use 基础、MCP 协议、API 报错排查。国内接入的话，走聚合平台最省事。