从工具到语境：Anthropic 双文启示下的 AI 代理工程实践心得

在 AI 代理技术飞速发展的当下，Anthropic 发布的《为 AI 代理编写有效的工具》与《为人工智能代理提供有效的情境工程》两篇文章，犹如为开发者打开了深入理解代理工程的两扇大门。通过研读这两篇内容，整理了工具构建与语境管理的核心逻辑，更对如何打造高效、可靠的 AI 代理有了系统性的实践认知。

一、工具：AI 代理与世界交互的 “双手”

工具是 AI 代理连接外部世界、执行具体任务的核心载体，但其价值绝非简单包装现有 API 或软件功能。在传统软件开发中，函数调用具有确定性，如 getWeather("NYC") 每次调用都会返回一致结果；而 AI 代理是非确定性系统，同一任务下可能有不同响应，这就要求工具设计必须跳出 “为开发者写函数” 的思维定式，转向 “为代理设计交互契约”。

（一）工具构建：从原型到优化的闭环

1. 快速原型验证，摸清 “代理友好度”：构建工具的第一步，是快速搭建原型并本地测试。使用 Claude Code 编写工具时，提供依赖的软件库、API 文档（如 MCP SDK 相关文件）能大幅提升效率，而将工具包装在本地 MCP 服务器或桌面扩展（DXT）中，可直接在 Claude 生态内测试。这一步的关键是 “亲身体验 + 收集反馈”—— 亲自试用工具发现漏洞，同时收集用户对用例的直觉反馈，避免闭门造车。比如测试 “会议安排工具” 时，若发现代理频繁遗漏 “附加会议记录” 的需求，就能及时调整工具参数设计。

2. 评估驱动改进，拒绝 “沙盒式” 测试：有效的评估是工具优化的核心。评估任务不能是简单的 “搜索客户 ID”，而应是贴近真实场景的复杂任务，例如 “客户 ID 9182 反映单次购买被扣款三次，请查找相关日志并确认是否有其他客户受影响”。这类任务需要代理多次调用工具，能充分暴露工具的设计缺陷。同时，评估需搭配合理的验证器，避免因格式、标点差异误判正确答案；还应收集多维度指标，如工具调用次数、运行时间、令牌消耗量等 —— 曾有案例显示，某搜索工具因代理频繁在 query 参数后附加无关内容导致结果偏差，正是通过 “工具调用日志分析” 才定位到问题，最终通过优化工具描述解决。

3. 借力代理优化，实现 “自我迭代”：最令人惊喜的是，代理本身可成为工具优化的助手。将评估过程中的代理记录（包括工具调用、推理过程）输入 Claude Code，它能自动分析问题 —— 小到修正矛盾的工具描述，大到重构工具实现以保持逻辑自洽。Anthropic 内部实践表明，这种 “代理参与优化” 的模式，甚至能让工具性能超越专家手动编写的版本，足见其价值。

（二）工具设计的五大核心原则

1. 选对工具：拒绝 “越多越好”更多工具不等于更好的效果。代理的上下文空间有限，若工具仅简单复刻传统软件功能（如 list_contacts 列出所有联系人），会导致代理在无关信息上浪费上下文。正确的做法是聚焦高影响力工作流程，设计 “整合型工具”—— 比如用 schedule_event 替代 list_users+list_events+create_event，让工具在后台处理多步操作，既减少代理调用次数，又节省上下文空间。

2. 命名空间：划清工具 “功能边界”当代理面对数百种工具时，模糊的命名会导致调用混乱。通过前缀分组（如按服务分 asana_search/jira_search，按资源分 asana_projects_search/asana_users_search），能帮助代理快速定位工具。实践中发现，不同 LLM 对命名方案的适应性不同，需结合自身评估选择最合适的方式。

3. 返回有效上下文：拒绝 “技术标识符堆砌”工具返回的信息应优先 “高信号内容”，避免罗列 uuid、mime_type 等低级标识符，转而提供 name、image_url 等能直接指导代理决策的字段。曾有案例显示，将字母数字 UUID 解析为语义化名称（如 0 索引 ID），能显著降低代理幻觉，提升检索准确率。若代理需兼顾自然语言交互与下游工具调用，可添加 response_format 参数，让代理自主选择 “简洁” 或 “详细” 响应 —— 例如 “简洁模式” 仅返回 Slack 线程内容，“详细模式” 补充 channel_id/user_id 供后续调用，令牌消耗可减少约 2/3。

4. 优化令牌效率：应对 “上下文有限” 难题对大体积响应的工具，需结合分页、过滤、截断功能，并设置合理默认值（如 Claude Code 默认限制工具响应为 25,000 个词条）。截断时需给代理明确指导，比如提示 “采用多次小规模搜索替代单次广泛搜索”；错误响应也需 “提示式设计”，避免晦涩代码，转而提供可操作建议（如 “请检查客户 ID 格式，应为 5 位数字”）。下面是官网给出的一个有效响应：无效响应：写具体的错误返回内容的时候，说清楚当前展示的是什么；下一步计划是什么并且怎么实现下一步计划；error的详细错误总结；错误总结给出的正确示例；数值型的错误给出具体的取值范围等等。设计错误返回内容，跟写提示词是一个道理，我们输出的内容一定是语义化并且模型好理解的，这样才能进行下一步的纠错。

5. 精修工具描述：细节决定成败工具描述是代理理解工具的关键，应像给新员工介绍工具一样，明确查询格式、专业术语定义、输入输出规则。参数命名需清晰（如用 user_id 替代 user），微小的描述优化都可能带来显著性能提升 ——Anthropic 曾通过精准改进工具描述，让 Claude Sonnet 3.5 在 SWE-bench Verified 评估中大幅降低错误率。

二、上下文工程：AI 代理的 “注意力预算” 管理

如果说工具是代理的 “双手”，那么语境就是代理的 “大脑工作内存”。随着代理需处理更长周期、更复杂的任务，语境管理从 “提示编写” 升级为 “情境工程”—— 核心是在 LLM 有限的 “注意力预算” 内，筛选出 “最小高信号令牌集”，最大化任务成功率。

（一）上下文工程与提示工程：从 “离散” 到 “迭代”

提示工程聚焦 “编写有效系统提示”，适用于一次性分类、文本生成等简单任务；而上下文工程是 “管理整个上下文状态” 的迭代过程，涵盖系统指令、工具、外部数据、消息历史等所有信息。比如循环运行的代理会不断生成新数据，上下文工程需每次判断 “哪些信息应保留在上下文窗口”，避免代理因信息过载而 “注意力分散”。

（二）上下文衰减：不可忽视的 LLM 特性

所有 LLM 都存在 “上下文衰减”—— 随着上下文窗口中令牌数量增加，模型回忆信息的能力会下降。这源于 Transformer 架构的限制：n 个令牌间存在 n² 对关系，上下文越长，模型捕捉关系的能力越弱；同时，训练数据中短序列更常见，模型对长序列依赖的处理经验不足。因此，上下文必须被视为 “边际收益递减的有限资源”，每一个令牌的加入都需谨慎。

（三）有效上下文的四大组成要素

1. 系统提示：找对 “指导高度”系统提示需在 “过度复杂” 与 “过于模糊” 间找到平衡：既不能硬编码脆弱的 if-else 逻辑（如 “若用户问天气，先调用工具，再检查格式”），也不能仅提供模糊指导（如 “帮用户解决问题”）。最佳实践是用 XML 或 Markdown 划分模块（如 <background_information>、## Tool guidance），以 “最少信息完整概括预期行为”—— 先用最佳模型测试最小提示，再根据故障模式补充说明和示例。

2. 工具集：拒绝 “臃肿冗余”工具集臃肿会让代理在选择时困惑，若人类工程师都无法明确 “某场景该用哪个工具”，代理更难做出正确选择。应构建 “最小可行工具集”，确保工具自包含、鲁棒性强、用途明确，就像精心设计的代码库一样，每个工具都有不可替代的价值。

3. 示例：少而精，胜过多而杂少样本提示是有效手段，但无需堆砌大量边缘情况示例。应选择 “多样化、规范性” 的示例，让 LLM 通过案例理解行为模式 —— 比如教代理处理客户投诉，3-5 个涵盖 “退款请求”“产品故障”“服务不满” 的典型示例，远胜于 20 个重复的相似案例。

4. 消息历史：动态筛选，去芜存菁消息历史无需全部保留，应删除冗余内容（如已完成任务的工具调用记录），仅保留关键决策、未解决问题、核心结论。Anthropic 推出的 “工具结果清除” 功能，就是通过删除深度调用后的工具原始结果，为上下文节省空间。

（四）长期任务的上下文管理策略

对于代码库迁移、综合研究等长周期任务（令牌数超上下文窗口），需突破窗口限制，三大策略尤为关键：

1. 压缩：保留核心，丢弃冗余当对话接近上下文上限时，用模型总结关键信息（如架构决策、未解决错误），丢弃多余工具输出或重复消息，再用总结重启新上下文。比如 Claude Code 压缩时，会保留最近访问的 5 个文件和核心开发细节，确保代理能无缝继续任务。压缩的关键是 “先保召回率（不遗漏关键信息），再提准确率（删除冗余）”。

2. 结构化笔记：代理的 “外部记忆”让代理定期将关键信息写入上下文外的笔记（如 NOTES.md 文件、待办事项列表），需要时再拉回上下文。Anthropic 的 “宝可梦代理” 就是通过这种方式，在数千步游戏中记录训练进度、已探索区域、战斗策略，即使上下文重置，也能通过读取笔记继续执行长期计划。目前 Claude 开发者平台已推出记忆工具测试版，可轻松实现跨会话状态维护。

3. 子代理架构：分工协作，聚焦重点让主代理负责高层计划，子代理执行专项任务（如深度技术搜索、数据分析），子代理仅返回精简摘要（1000-2000 个令牌）。这种模式实现了 “关注点分离”—— 子代理可使用数万个令牌探索细节，主代理则专注于结果综合，在复杂研究任务中性能远超单代理系统。

三、总结：AI 代理工程的核心思维转变

研读 Anthropic 的两篇文章后，我最深的体会是：AI 代理工程本质上是一次 “思维范式的转变”—— 从传统软件开发的 “确定性契约”，转向代理系统的 “非确定性协作”；从 “追求功能完备”，转向 “优化注意力预算”。

无论是工具构建还是上下文管理，核心原则始终一致：以评估为驱动，以代理为中心，在有限资源内最大化信号价值。未来，随着 MCP 协议更新、LLM 能力提升，代理与世界交互的机制会不断演进，但 “系统化、评估驱动” 的工程方法，将始终是构建高效代理的基石。

对于开发者而言，当下最务实的做法是：从最小可行工具集和简洁上下文设计起步，通过迭代评估发现问题，借助代理自身优化工具与上下文 —— 这不仅能降低开发成本，更能让代理在真实场景中持续成长，真正成为人类的可靠协作伙伴。