Claude Code官方权威指南：如何构建有效的 Agent

构建有效的 Agent（智能体）

原文：Building effective agents，Anthropic，2024 年 12 月 19 日

过去这一年，我们和几十个团队打交道，他们在各行各业构建 LLM（大语言模型）Agent（智能体）。看下来，那些真正做成的，都没有用多么复杂的框架或专门的库——靠的是简单、可组合的模式。

这篇文章把我们从客户合作和自己动手构建 Agent（智能体）中积累的经验总结出来，希望对开发者有用。

什么是 Agent（智能体）？

这个词，不同的人定义差很远。有人把 Agent（智能体）理解成完全自主的系统，能独立运行很长时间，调用各种工具完成复杂任务；也有人用这个词描述那些按预定流程走的实现。

Anthropic 的叫法是：所有这些都叫 Agentic System（智能体系统）。但在架构上，我们区分两种：

• Workflow（工作流）：LLM（大语言模型）和工具按预先定好的代码路径执行。
• Agent（智能体）：LLM（大语言模型）自己动态决定怎么做，自主调用工具，掌控整个执行过程。

下面会分别展开说。附录一会介绍两个客户实际落地的领域。

什么时候该用 Agent（智能体）

造东西之前先想清楚：能用简单方案解决的，就别往复杂了搞。很多时候，根本用不上 Agentic System（智能体系统）。

这类系统的代价是更高的延迟和成本，换来的是更好的任务表现。值不值，要看具体情况。

如果确实需要更复杂的方案：任务边界清晰的，用 Workflow（工作流），更可预测、更稳定；需要灵活性、需要模型自主决策的，才上 Agent（智能体）。但说真的，很多场景把单次 LLM（大语言模型）调用优化好，加上 Retrieval（检索）和 In-context Examples（上下文示例），就够用了。

什么时候该用框架

市面上有不少框架，可以让 Agentic System（智能体系统）更好上手：

• Claude Agent SDK（Claude 智能体开发工具包）
• Strands Agents SDK（AWS 出品的智能体 SDK）
• Rivet（拖拽式 LLM Workflow（工作流）构建工具）
• Vellum（另一款 GUI 工具，用于构建和测试复杂 Workflow（工作流））

这些框架确实降低了入门门槛，帮你处理调用 LLM（大语言模型）、定义和解析 Tool（工具）、串联多次调用这些底层事务。但问题也在这里——多了一层抽象，底层的 Prompt（提示词）和 Response（响应）就看不清楚了，Debug（调试）起来很麻烦。而且框架容易让人觉得"功能多就是好"，诱导你把系统搞得比实际需要的复杂。

建议：先直接用 LLM API（大语言模型接口）写，很多模式几行代码就能实现。如果确实要用框架，搞清楚它底层在干什么——很多客户踩的坑，都是对框架内部机制有错误假设。

基础模块、Workflow（工作流）与 Agent（智能体）

下面介绍我们在生产环境中见过的常见模式。从最基础的模块开始，逐步到复杂的 Autonomous Agent（自主智能体）。

基础模块：增强型 LLM（大语言模型）

Agentic System（智能体系统）的基础是带有增强能力的 LLM（大语言模型）——Retrieval（检索）、Tool（工具）、Memory（记忆）。现在的模型能主动用这些能力：自己生成搜索 Query（查询语句）、选择合适的 Tool（工具）、决定保留哪些信息。

实现时重点关注两件事：一是针对你的具体场景裁剪这些能力，二是给 LLM（大语言模型）提供简洁、有文档的接口。Model Context Protocol（模型上下文协议，MCP）是我们最近推出的一种方案，让开发者可以用简单的 Client（客户端）接入不断壮大的第三方工具生态。

Workflow（工作流）一：Prompt Chaining（提示词链）

把任务拆成一系列步骤，每次 LLM（大语言模型）调用处理上一步的输出。中间可以加程序化的检查点（Gate（门控））确保流程没有跑偏。

适合场景：任务能干净地拆成固定子步骤。用牺牲一点延迟换来更高准确率——每次 LLM（大语言模型）调用只做一件事，做得更好。

典型例子：

• 先生成营销文案，再翻译成目标语言
• 先写文档大纲，检查大纲是否符合要求，再根据大纲写正文

Workflow（工作流）二：Routing（路由）

先对输入分类，再把它导向对应的处理流程。好处是各类输入互不干扰，可以针对性地优化各自的 Prompt（提示词）。如果不分流，为某类输入优化往往会伤害其他类输入的表现。

适合场景：任务有明显的分类，各类别适合不同处理方式，且分类本身可以准确完成（用 LLM（大语言模型）或传统分类算法都行）。

典型例子：

• 客服系统：把通用咨询、退款申请、技术支持分别导向不同的处理流程和 Prompt（提示词）
• 成本优化：简单常见的问题走 Claude Haiku 4.5 这类轻量模型，复杂罕见的问题走 Claude Sonnet 4.5 这类强力模型

Workflow（工作流）三：Parallelization（并行化）

让多个 LLM（大语言模型）同时处理任务，再把结果汇总。有两种变体：

• Sectioning（分段）：把任务拆成独立子任务并行执行
• Voting（投票）：同一任务跑多次，用多个结果提高置信度

适合场景：子任务之间互相独立，可以并行加速；或者需要多视角、多次尝试来提升结果可靠性。对于涉及多个考量维度的复杂任务，让每次 LLM（大语言模型）调用专注一个维度，往往比让一次调用考虑所有维度效果更好。

典型例子：

分段：

• 内容安全系统：一个模型实例处理用户请求，另一个实例专门做内容审核。比同一次调用兼顾两件事效果更好
• LLM（大语言模型）性能评估：每次调用评估模型在不同维度上的表现

投票：

• 代码安全审查：多个不同 Prompt（提示词）分别扫描同一段代码，标记发现的漏洞
• 内容合规判断：多个 Prompt（提示词）从不同角度评估，通过调整投票阈值平衡误报和漏报

Workflow（工作流）四：Orchestrator-Workers（编排者-工作者）

一个中心 LLM（大语言模型）作为 Orchestrator（编排者），动态拆解任务、分配给 Worker LLM（工作者大语言模型）执行，再汇总结果。

适合场景：复杂任务，子任务无法预先确定。比如写代码时，需要改哪些文件、怎么改，取决于具体任务内容。表面上和 Parallelization（并行化）类似，核心区别是灵活性——子任务不是提前定好的，而是 Orchestrator（编排者）根据输入动态决定的。

典型例子：

• 编程产品：每次任务需要跨多个文件做复杂修改
• 信息收集任务：从多个来源搜集和分析信息

Workflow（工作流）五：Evaluator-Optimizer（评估者-优化者）

一个 LLM（大语言模型）负责生成内容，另一个负责评估并给出反馈，形成循环迭代。

适合场景：有清晰的评估标准，且反复迭代能带来明显提升。两个判断信号：一是人工给出反馈时 LLM（大语言模型）的输出质量能显著提升；二是 LLM（大语言模型）本身能提供有效的评估反馈。这有点像人类作者反复修改打磨一篇文章的过程。

典型例子：

• 文学翻译：翻译 LLM（大语言模型）可能没捕捉到某些细微之处，评估 LLM（大语言模型）能给出有针对性的改进意见
• 复杂信息检索：需要多轮搜索和分析才能获取全面信息，由评估者决定是否需要继续搜索

Agent（智能体）

随着 LLM（大语言模型）在几个关键能力上的成熟——理解复杂输入、推理规划、可靠地调用 Tool（工具）、从错误中恢复——Agent（智能体）开始在生产环境里真正跑起来。

Agent（智能体）的工作从用户的指令或交互开始。任务明确后，它自主规划和执行，期间可能回来询问人的意见或寻求判断。执行过程中，Agent（智能体）需要在每一步从环境获取"真实反馈"（比如 Tool Call（工具调用）结果、代码执行结果）来判断进展。可以设置 Checkpoint（检查点）让人介入，也可以设置停止条件（比如最大迭代次数）来保持控制。

Agent（智能体）能处理复杂任务，但实现往往并不复杂——通常就是 LLM（大语言模型）在循环里根据环境反馈调用 Tool（工具）。所以 Toolset（工具集）的设计和文档写得好不好，至关重要。

适合场景：开放性问题，无法预测需要多少步骤，无法写死执行路径。LLM（大语言模型）可能要跑很多轮，需要对它的决策有一定信任。Agent（智能体）的自主性让它特别适合在受信任环境中扩展任务规模。

自主性越强，成本越高，错误叠加的风险也越大。建议在沙箱环境中充分测试，配上合适的 Guardrail（护栏）。

我们自己的例子：

• 用于解决 SWE-bench 任务的编程 Agent（智能体）：仅根据任务描述，跨多个文件做修改
• “computer use”（计算机使用）参考实现：Claude 直接操作计算机完成任务

模式的组合与定制

上面这些不是死规定，是常见的模式，开发者可以根据需要自由组合、改造。关键跟其他 LLM（大语言模型）功能一样：测量效果，持续迭代。只有在确实能带来提升的时候，再增加复杂度。

总结

在 LLM（大语言模型）这个领域，成功靠的不是造出最复杂的系统，而是造出最适合自己需求的系统。先从简单 Prompt（提示词）开始，配上全面的 Evaluation（评估），只有更简单的方案不够用时，才引入多步骤的 Agentic System（智能体系统）。

我们在实现 Agent（智能体）时遵循三条原则：

1. 保持设计简单
2. 优先保证透明度，明确展示 Agent（智能体）的规划步骤
3. 认真打磨 ACI（Agent-Computer Interface，智能体-计算机接口），工具的文档和测试要和 Prompt（提示词）同等重视

框架可以帮你快速起步，但进入生产环境时，不要犹豫，减少抽象层，用基础组件直接构建。这样做出来的 Agent（智能体）更强大，也更可靠、可维护，用户更信任。

附录一：Agent（智能体）的实践场景

我们见过两个特别有价值的落地方向，它们都满足 Agent（智能体）最能发挥作用的条件：既有对话又有行动、有清晰的成功标准、能形成反馈闭环、有合理的人工监督。

A. 客户支持（Customer Support）

客服天然适合开放式 Agent（智能体）：

• 支持交互本来就是对话形式，同时需要访问外部信息和执行操作
• 可以接入 Tool（工具）拉取客户数据、订单历史、知识库文章
• 退款、更新工单等操作可以程序化处理
• 成功标准清晰：问题是否解决了

有些公司已经在用按成功解决计费的定价模式，这说明他们对自己 Agent（智能体）的效果是有信心的。

B. 编程 Agent（智能体）

软件开发领域展示了 LLM（大语言模型）能力进化的轨迹，从代码补全到自主解决问题。Agent（智能体）在这里特别有效：

• 代码结果可以通过自动化测试验证
• Agent（智能体）可以用测试结果作为反馈持续迭代
• 问题空间定义清晰、结构明确
• 输出质量可以客观衡量

我们自己的实现已经能仅凭 Pull Request（拉取请求）描述，在 SWE-bench Verified 基准上解决真实的 GitHub Issue（问题）。当然，自动化测试能验证功能正确性，但人工 Review（审查）仍然不可或缺——要确保解决方案和整体系统设计是对齐的。

附录二：Tool（工具）的 Prompt Engineering（提示词工程）

不管构建哪种 Agentic System（智能体系统），Tool（工具）都是核心。Tool（工具）让 Claude 能调用外部服务和 API（接口），通过在 API（接口）中指定其结构和定义来实现。Tool（工具）的定义和文档，应该和整体 Prompt（提示词）一样认真对待。

同一个操作往往有多种表达方式。比如文件编辑：可以写 Diff（差异），也可以重写整个文件。结构化输出：可以把代码放在 Markdown（标记语言）里，也可以放在 JSON（数据格式）里。在软件工程中这些只是格式差异，可以无损转换。但对 LLM（大语言模型）来说，有些格式要难写得多——比如写 Diff（差异）需要在写新代码之前就知道改了多少行；把代码放进 JSON（数据格式）需要额外转义换行符和引号。

关于 Tool Format（工具格式）的建议：

• 给模型足够的 Token（词元）来"思考"，别让它一开始就把自己逼进死角
• 格式尽量贴近模型在互联网文本里自然见过的样子
• 避免格式"开销"，比如让模型时刻维护几千行代码的准确行数，或者要对代码做字符串转义

一个实用的思考框架：想想人们在 HCI（Human-Computer Interface，人机接口）上花了多少心思，在 ACI（Agent-Computer Interface，智能体-计算机接口）上也该花同等心思。具体怎么做：

换位思考。只看工具描述和参数，用起来明不明显？如果你自己也要想半天，模型大概率也会。好的 Tool（工具）定义应该包含使用示例、边界情况、输入格式要求，以及和其他类似工具的明确边界。

打磨参数名和描述。就像给团队里的新人写文档注释一样认真。工具多、工具类似时尤其重要。

测试模型的实际用法。在 Workbench（工作台）里跑大量示例输入，看模型犯什么错，针对性迭代。

Poka-yoke（防呆设计）你的 Tool（工具）。调整参数设计，让犯错更难。

我们在构建 SWE-bench Agent（智能体）的过程中，花在优化 Tool（工具）上的时间比优化整体 Prompt（提示词）还多。举个例子：我们发现当 Agent（智能体）离开根目录后，用相对路径调用工具会出错。解决办法是把工具改成强制要求绝对路径——改完之后，模型用这个工具几乎没再出过错。