构建有效的 Agent智能体原文Building effective agentsAnthropic2024 年 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 SDKClaude 智能体开发工具包Strands Agents SDKAWS 出品的智能体 SDKRivet拖拽式 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智能体时遵循三条原则保持设计简单优先保证透明度明确展示 Agent智能体的规划步骤认真打磨 ACIAgent-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词元来思考别让它一开始就把自己逼进死角格式尽量贴近模型在互联网文本里自然见过的样子避免格式开销比如让模型时刻维护几千行代码的准确行数或者要对代码做字符串转义一个实用的思考框架想想人们在 HCIHuman-Computer Interface人机接口上花了多少心思在 ACIAgent-Computer Interface智能体-计算机接口上也该花同等心思。具体怎么做换位思考。只看工具描述和参数用起来明不明显如果你自己也要想半天模型大概率也会。好的 Tool工具定义应该包含使用示例、边界情况、输入格式要求以及和其他类似工具的明确边界。打磨参数名和描述。就像给团队里的新人写文档注释一样认真。工具多、工具类似时尤其重要。测试模型的实际用法。在 Workbench工作台里跑大量示例输入看模型犯什么错针对性迭代。Poka-yoke防呆设计你的 Tool工具。调整参数设计让犯错更难。我们在构建 SWE-bench Agent智能体的过程中花在优化 Tool工具上的时间比优化整体 Prompt提示词还多。举个例子我们发现当 Agent智能体离开根目录后用相对路径调用工具会出错。解决办法是把工具改成强制要求绝对路径——改完之后模型用这个工具几乎没再出过错。
Claude Code官方权威指南：如何构建有效的 Agent
构建有效的 Agent智能体原文Building effective agentsAnthropic2024 年 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 SDKClaude 智能体开发工具包Strands Agents SDKAWS 出品的智能体 SDKRivet拖拽式 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智能体时遵循三条原则保持设计简单优先保证透明度明确展示 Agent智能体的规划步骤认真打磨 ACIAgent-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词元来思考别让它一开始就把自己逼进死角格式尽量贴近模型在互联网文本里自然见过的样子避免格式开销比如让模型时刻维护几千行代码的准确行数或者要对代码做字符串转义一个实用的思考框架想想人们在 HCIHuman-Computer Interface人机接口上花了多少心思在 ACIAgent-Computer Interface智能体-计算机接口上也该花同等心思。具体怎么做换位思考。只看工具描述和参数用起来明不明显如果你自己也要想半天模型大概率也会。好的 Tool工具定义应该包含使用示例、边界情况、输入格式要求以及和其他类似工具的明确边界。打磨参数名和描述。就像给团队里的新人写文档注释一样认真。工具多、工具类似时尤其重要。测试模型的实际用法。在 Workbench工作台里跑大量示例输入看模型犯什么错针对性迭代。Poka-yoke防呆设计你的 Tool工具。调整参数设计让犯错更难。我们在构建 SWE-bench Agent智能体的过程中花在优化 Tool工具上的时间比优化整体 Prompt提示词还多。举个例子我们发现当 Agent智能体离开根目录后用相对路径调用工具会出错。解决办法是把工具改成强制要求绝对路径——改完之后模型用这个工具几乎没再出过错。
