Building Effective Agents - Anthropic

Source: https://www.anthropic.com/engineering/building-effective-agents Published: December 19, 2024 Authors: Erik Schluntz, Barry Zhang

详细重点总结

一、核心主题与立场

Anthropic 基于过去一年与数十个团队合作构建 LLM Agent 的经验，总结出一个核心观点：最成功的实现并非使用复杂框架或专门库，而是基于简单、可组合的模式构建。文章系统性地介绍了从简单工作流到自主 Agent 的一系列构建模式，并给出了明确的选择指南。

二、关键概念定义

Agentic Systems（智能体系统）

Anthropic 将所有包含 LLM + 工具的系统统称为 agentic systems，并在内部区分两类：

这一区分非常重要：Workflows 适合结构明确的任务，Agents 适合需要灵活性的开放式问题。

The Augmented LLM（增强 LLM）

所有 agentic 系统的基础构建块。核心 LLM 通过三项能力增强：

• Retrieval（检索）：获取外部知识
• Tools（工具）：与外部服务交互
• Memory（记忆）：跨交互保持上下文

当前模型已能主动使用这些能力——自主生成搜索查询、选择合适工具、决定保留哪些信息。

三、六大构建模式详解

模式 1：Prompt Chaining（提示链）

原理：将任务分解为顺序步骤，每个 LLM 调用处理上一步的输出。可在中间步骤设置程序化检查点（gates）确保流程正确。

适用场景：

• 任务可分解为固定子任务
• 愿意用延迟换取准确性
• 每个子步骤需要简化 LLM 调用

典型示例：

• 生成营销文案 → 翻译为不同语言
• 编写文档大纲 → 验证是否满足标准 → 基于大纲写完整文档

设计要点：通过 gate 机制在每步之间验证输出质量，如果不满足条件可以回退或终止。

模式 2：Routing（路由）

原理：对输入进行分类，引导到专门化的后续任务。实现关注点分离，允许为不同类别优化专门提示。

适用场景：

• 复杂任务有不同类别，需要分别处理
• 分类可通过 LLM 或传统算法准确完成

典型示例：

• 客服查询分流：一般问题 / 退款 / 技术支持 → 不同处理流程
• 模型路由：简单问题 → Claude Haiku（高效低成本），复杂问题 → Claude Sonnet（强能力）

关键洞察：不使用路由时，为一种输入类型优化会降低其他类型的表现。

模式 3：Parallelization（并行化）

原理：多个 LLM 同时工作，输出通过编程方式聚合。两种变体：

• Sectioning（分段）：将任务拆分为独立的并行子任务
• Voting（投票）：多次运行相同任务获取多样化输出

适用场景：

• 子任务可并行化以提升速度
• 需要多个视角提高置信度

典型示例：

• 分段：一个实例处理用户查询，另一个筛查不当内容（guardrails）
• 分段：自动评估中每个调用评估不同的性能方面
• 投票：多个提示审查代码漏洞
• 投票：多个提示评估内容适当性

模式 4：Orchestrator-Workers（编排者-工作者）

原理：中央 LLM 动态分解任务、委派给工作者 LLM、综合结果。

与 Parallelization 的区别：Parallelization 的子任务是预定义的；Orchestrator-Workers 的子任务由编排者根据输入动态决定，灵活性是关键。

适用场景：

• 复杂任务，所需子任务无法提前预测
• 编排者需要根据输入判断如何分解

典型示例：

• 编码产品：对多个文件进行复杂修改（修改哪些文件取决于具体任务）
• 搜索任务：从多个来源收集和分析信息

模式 5：Evaluator-Optimizer（评估者-优化者）

原理：一个 LLM 生成响应，另一个提供评估和反馈，形成迭代循环。类似人类的写作修改过程。

适用场景：

• 评估标准明确
• 迭代改进带来可衡量的价值
• LLM 响应在人类反馈后有明显改善
• LLM 能提供类似人类水平的反馈

典型示例：

• 文学翻译：评估者批评细微差异
• 复杂搜索任务：需要多轮搜索和分析

模式 6：Autonomous Agents（自主智能体）

原理：LLM 在连续循环中基于环境反馈使用工具。从命令或交互式讨论开始，任务明确后独立规划和执行。

工作流程：

1. 接收命令或与人类讨论确定任务
2. 独立规划和执行
3. 从环境获取"ground truth"（工具结果、代码执行结果）评估进展
4. 在关键节点暂停请求人类反馈
5. 任务完成或达到停止条件（如最大迭代次数）时终止

适用场景：

• 开放式问题，所需步骤难以预测
• 无法硬编码固定路径
• 需要 LLM 做多轮决策

重要警告：

• 成本更高
• 错误可能累积
• 需要在沙箱环境中充分测试
• 必须设置适当的 guardrails

实际案例：

• 编码 Agent：解决 SWE-bench 任务（多文件编辑）
• Computer Use 参考实现：Claude 操作计算机完成任务

四、框架使用策略

文章对框架持谨慎态度：

推荐的框架：

• Claude Agent SDK
• Strands Agents SDK (AWS)
• Rivet（拖拽式 GUI 工作流构建器）
• Vellum（GUI 复杂工作流构建工具）

核心建议：

1. 从原始 LLM API 开始——许多模式只需几行代码
2. 框架创建的抽象层会隐藏底层提示和响应，使调试困难
3. 框架容易诱导不必要的复杂性
4. 如果使用框架，必须理解底层机制——客户常见错误源于对实现细节的错误假设

五、三大核心实现原则

1. Simplicity（简单性）：保持 Agent 设计简洁直接
2. Transparency（透明性）：明确展示规划步骤
3. Tool Documentation（工具文档）：像精心设计人机界面（HCI）一样设计 Agent-Computer Interface（ACI）

六、工具设计最佳实践（Appendix 2 精华）

文章强调：工具定义需要与整体提示同等的 prompt engineering 投入。这是一个经常被忽视但极其重要的观点。

格式选择原则

• 给模型足够的 token 进行推理，避免过早限制输出格式
• 保持格式接近互联网上自然出现的文本
• 消除格式开销（如行号计数、字符串转义）

实际考量

• 相同操作常有多种实现方式（如文件编辑：diff vs 全文件重写；结构化输出：markdown vs JSON）
• 有些格式对 LLM 更难处理：diff 需要在写新代码前知道行数变化；JSON 代码需要额外的换行符和引号转义

ACI（Agent-Computer Interface）设计原则

• 明确性：如果描述和参数对人类不清楚，对模型同样不清楚
• 参数命名：改善参数名和描述以提高清晰度
• 测试：用大量示例输入在 workbench 中测试模型的工具使用
• 防错设计（Poka-yoke）：让错误变得更难发生

SWE-bench 开发中的实际经验

Anthropic 团队在 SWE-bench Agent 开发中花在工具优化上的时间超过了整体提示优化。一个具体例子：发现模型在离开根目录后使用相对文件路径会出错，改为要求绝对文件路径后，模型使用完美无误。

七、实际应用场景分析

客户支持 Agent

自然适合 Agent 的场景，因为：

• 交互本质上结合了对话流和外部数据访问
• 工具集成（客户数据、订单历史、知识库）
• 可执行操作（退款、工单更新）可编程化
• 成功标准可衡量（用户定义的解决方案）
• 部分公司已采用按成功解决收费的使用定价模式

编码 Agent

特别有效，因为：

• 解决方案可通过自动化测试客观验证
• Agent 可使用测试结果作为反馈进行迭代
• 问题空间定义明确、结构化
• 输出质量可客观衡量
• 当前已能解决 SWE-bench Verified 中的真实 GitHub issue

注意：自动化测试验证功能性，但人工审查仍对确保方案符合更广泛系统需求至关重要。

八、模式组合与选择策略

文章明确指出这些模式不是规定性的，而是可以根据不同用例塑造和组合的通用模式。选择策略：

1. 从最简单的解决方案开始
2. 通过全面评估优化
3. 仅在简单方案不足时才添加多步 Agent 系统
4. 复杂性增加必须可证明地改善结果
5. 衡量性能并迭代实现

九、与 Shannon 项目的关联要点

十、核心结论

1. 从简单开始：不要追求最复杂的系统，而是构建适合需求的正确系统
2. 可组合性：六大模式是积木而非蓝图，可自由组合
3. 工具设计被低估：工具定义的 prompt engineering 与整体提示同等重要
4. 框架要谨慎：抽象层增加调试难度，鼓励不必要复杂性
5. 透明性：明确展示 Agent 的规划步骤
6. 衡量驱动：只在能证明改善结果时增加复杂性

完整文章内容

以下为从 Anthropic 工程博客获取的文章完整内容，以原始结构还原。

Introduction

Over the past year, Anthropic has worked with dozens of teams building LLM agents across industries. The most successful implementations were not using complex frameworks or specialized libraries. Instead, they were building with simple, composable patterns.

This post shares what Anthropic has learned from working with customers and building agents internally, offering practical advice for developers on building effective agents.

What are agents?

"Agent" has varied definitions. Some define agents as fully autonomous systems that operate independently over extended periods, using various tools to accomplish complex tasks. Others use it to describe more prescriptive implementations that follow predefined workflows. Anthropic categorizes all these variations as agentic systems, and draws an important architectural distinction between:

• Workflows: systems where LLMs and tools are orchestrated through predefined code paths
• Agents: systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks

When (and when not) to use agents

When building applications with LLMs, it is recommended to find the simplest solution possible, and only increase complexity when needed. This might mean not building agentic systems at all. Agentic systems often trade latency and cost for better task performance, and you should consider when this tradeoff makes sense.

When more complexity is warranted, workflows offer predictability and consistency for well-defined tasks, whereas agents are the better option when flexibility and model-driven decision making are needed at scale.

For many applications, optimizing single LLM calls with retrieval and in-context examples is the best approach.

When and how to use frameworks

There are several frameworks that make agentic systems easier to implement, including:

• The Claude Agent SDK
• Strands Agents SDK by AWS
• Rivet, a drag and drop GUI LLM workflow builder
• Vellum, another GUI tool for building and testing complex workflows

These frameworks simplify standard low-level tasks like calling LLMs, defining and parsing tools, and chaining calls together. However, they often create extra layers of abstraction that can obscure the underlying prompts and responses, making them harder to debug. They can also make it tempting to add complexity when a simpler setup would suffice.

Suggestion: start by using LLM APIs directly: many patterns need just a few lines of code. If you do use a framework, ensure you understand the underlying code. Incorrect assumptions about what's under the hood are one of the most common sources of customer errors.

Building blocks, workflows, and agents

Building Block: The Augmented LLM

The basic building block of agentic systems is an LLM enhanced with augmentations such as retrieval, tools, and memory. Current models can actively use these capabilities -- generating their own search queries, selecting appropriate tools, and determining what information to retain.

It is recommended to focus on two key aspects: tailoring these capabilities to your specific use case and ensuring they provide an easy, well-documented interface for your LLM. There are many ways to implement these augmentations. One approach uses the Model Context Protocol, which allows you to integrate with a growing ecosystem of third-party tools with a simple client implementation.

Workflow: Prompt Chaining

Prompt chaining decomposes a task into a sequence of steps, where each LLM call processes the output of the previous one. You can add programmatic checks (called "gates") on any intermediate steps to ensure that the process is still on track.

When to use this workflow: This workflow is ideal for situations where the task can be easily and cleanly decomposed into fixed subtasks. The main goal is to trade latency for higher accuracy, by making each LLM call an easier task.

Examples where prompt chaining is useful:

• Generating a marketing copy, then translating it into a separate language
• Writing a document outline, checking that the outline meets certain criteria, then writing the document based on the outline

Workflow: Routing

Routing classifies an input and directs it to a specialized followup task. This workflow allows for separation of concerns, and building more specialized prompts. Without this workflow, optimizing for one kind of input can hurt performance on other inputs.

When to use this workflow: Routing works well for complex tasks where there are distinct categories that are better handled separately, and where classification can be handled accurately, either by an LLM or a more traditional classification model/algorithm.

Examples where routing is useful:

• Directing different types of customer service queries (general questions, refund requests, technical support) into different downstream processes, prompts, and tools
• Routing easy/common questions to smaller models like Claude Haiku and hard/unusual questions to more capable models like Claude Sonnet

Workflow: Parallelization

LLMs can sometimes work simultaneously on a task and have their outputs aggregated programmatically. This workflow, parallelization, manifests in two key variations:

• Sectioning: Breaking a task into independent subtasks run in parallel
• Voting: Running the same task multiple times to get diverse outputs

When to use this workflow: Parallelization is effective when the divided subtasks can be parallelized for speed, or when multiple perspectives or attempts are needed for higher confidence results. For complex tasks with multiple considerations, LLMs generally perform better when each consideration is handled by a separate LLM call, allowing focused attention on each specific aspect.

Examples where parallelization is useful:

Sectioning:

• Implementing guardrails where one model instance processes the user query while another screens it for inappropriate content or requests. This tends to perform better than having the same LLM call handle both guardrails and the core response.
• Automating evals for LLM performance, where each LLM call evaluates a different aspect of the model's performance on a given prompt.

Voting:

• Reviewing a piece of code for vulnerabilities, where several different prompts review and flag the code if they find a problem.
• Evaluating whether a given piece of content is inappropriate, with multiple prompts evaluating different aspects or requiring different vote thresholds to balance false positives and negatives.

Workflow: Orchestrator-Workers

In the orchestrator-workers workflow, a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results.

When to use this workflow: This workflow is well-suited for complex tasks where you can't predict the subtasks needed (e.g., in coding, the number of files that need to be changed and the nature of the change in each file likely depend on the task). Whereas it's topologically similar, the key difference from parallelization is its flexibility -- subtasks aren't pre-defined, but determined by the orchestrator based on the specific input.

Examples where orchestrator-workers are useful:

• Coding products that make complex changes to multiple files each time
• Search tasks that involve gathering and analyzing information from multiple sources

Workflow: Evaluator-Optimizer

In the evaluator-optimizer workflow, one LLM call generates a response while another provides evaluation and feedback in a loop.

When to use this workflow: This workflow is particularly effective when we have clear evaluation criteria, and when iterative refinement provides measurable value. The two signs of a good fit are, first, that LLM responses can be demonstrably improved when a human articulates their feedback; and second, that the LLM can provide such feedback. This is analogous to the iterative writing process a human writer might go through when producing a polished document.

Examples where evaluator-optimizer is useful:

• Literary translation where there are nuances that the translator LLM might not capture initially, but where an evaluator LLM can provide useful critiques
• Complex search tasks that require multiple rounds of searching and analysis to gather comprehensive information, where the evaluator decides whether further searches are warranted

Agents

Agents are emerging in production as LLMs mature in key capabilities -- understanding complex inputs, engaging in reasoning and planning, using tools reliably, and recovering from errors.

Agents begin their work with either a command from, or interactive discussion with, the human user. Once the task is clear, agents plan and operate independently, potentially returning to the human for further information or judgment. During execution, it's crucial for the agent to gain "ground truth" from the environment at each step (such as tool call results or code execution) to assess its progress. Agents can then pause for human feedback at checkpoints or when encountering blockers. The task often terminates upon completion, but it's also common to include stopping conditions (such as a maximum number of iterations) to maintain control.

Agents can handle sophisticated tasks, but their implementation is often straightforward. They are typically just LLMs using tools based on environmental feedback in a loop. It is therefore crucial to design toolsets and their documentation clearly and thoughtfully.

When to use agents: Agents can be used for open-ended problems where it's difficult or impossible to predict the required number of steps, and where you can't hardcode a fixed path. The LLM will potentially operate for many turns, and you must have some level of trust in its decision-making. Agents' autonomy makes them ideal for scaling tasks in trusted environments.

The autonomous nature of agents means higher costs, and the potential for compounding errors. Extensive testing in sandboxed environments, along with the appropriate guardrails, is recommended.

Examples where agents are useful:

• A coding agent to resolve SWE-bench tasks, which involve edits to many files based on a task description
• The "computer use" reference implementation, where Claude uses a computer to accomplish tasks

Combining and customizing these patterns

These building blocks aren't prescriptive. They're common patterns that developers can shape and combine to fit different use cases. As with any LLM features, the key to success is measuring performance and iterating on implementations. Repeated emphasis: you should consider adding complexity only when it demonstrably improves outcomes.

Summary

Success in the LLM space isn't about building the most sophisticated system. It's about building the right system for your needs. Start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short.

When implementing agents, three core principles should be followed:

1. Maintain simplicity in your agent's design
2. Prioritize transparency by explicitly showing the agent's planning steps
3. Carefully craft your agent-computer interface (ACI) through thorough tool documentation and testing

Frameworks can help you get started quickly, but don't hesitate to reduce abstraction layers and build with basic components as you move to production. By following these principles, you can create agents that are not only powerful but also reliable, maintainable, and trusted by their users.

Appendix 1: Agents in Practice

Through work with customers, two particularly promising applications for AI agents have been identified, demonstrating how agents add value for tasks requiring both conversation and action, where clear success criteria exist, enabling feedback loops, and meaningful human-in-the-loop oversight.

A. Customer Support

Customer support combines familiar chatbot interfaces with enhanced capabilities through tool integration. This is a natural fit for more open-ended agents because:

• Support interactions naturally follow a conversational flow while requiring access to external information and actions
• Tools can be integrated for pulling customer data, order history, and knowledge base articles
• Actions such as issuing refunds or updating tickets can be handled programmatically
• Success can be clearly measured through user-defined resolutions

Several companies have demonstrated the viability of this approach through usage-based pricing models that charge only for successful resolutions, showing confidence in their agents' effectiveness.

B. Coding Agents

The software development domain has shown remarkable potential for LLM features, with capabilities evolving from code completion to autonomous problem-solving. Agents are particularly effective because:

• Code solutions can be verified through automated tests
• Agents can iterate on solutions using test results as feedback
• The problem space is well-defined and structured
• Output quality is measurably evaluated

In benchmarks, agents have now solved real GitHub issues in the SWE-bench Verified benchmark based solely on the pull request description. However, while automated testing helps verify functionality, human review remains crucial for ensuring solutions align with broader system requirements.

Appendix 2: Prompt Engineering Your Tools

In any agentic system, tools are an essential part. They enable Claude to interact with external services and APIs by specifying their exact structure and definition in the API. When Claude responds, it includes tool use blocks in the API response when it wants to invoke a tool. Tool definitions and specifications deserve just as much prompt engineering attention as your overall prompts in an agentic system.

There are often several different ways to specify the same action. For instance, you can specify a file edit by writing a diff, or by rewriting the entire file. For structured output, you can return code inside markdown or within JSON. In isolation, each of these is equally fine. But some formats are much harder for LLMs to write. Writing a diff requires knowing how many lines are changing in the chunk header before the new code is written. Writing code inside JSON requires extra escaping of newlines and quotes.

Suggestions for how to think about tool formats:

• Give the model enough tokens to "think" before it writes itself into a corner
• Keep the format close to what the model has seen naturally occurring in text on the internet
• Make sure there is no formatting "overhead" such as having to keep an accurate count of thousands of lines of code, or string-escaping any code it writes

Think about investing the same effort in the agent-computer interface (ACI) as you do in the human-computer interface (HCI). Here are some practical suggestions:

• Put yourself in the model's shoes. Is it obvious how to use this tool, based on the description and parameters, or would you need to think carefully about it? If so, then it's probably not obvious to the model either. A good tool definition often includes example calls, edge cases, input format requirements, and clear boundaries on what the tool does vs. does not do.
• How can you change parameter names or descriptions to make things more obvious? Think of this as writing a great docstring for a junior developer. This is especially important when using many similar tools.
• Test how the model uses your tools: run many example inputs in the workbench to see what mistakes the model makes, and iterate.
• Poka-yoke your tools. Change the tools so that it is harder to make mistakes.

When building agents for SWE-bench, more time was spent optimizing the tools than the overall prompt. For example, after the agent moved out of its root directory, the model started making mistakes with relative file paths. The fix was to change the tool to require absolute file paths -- and the model used this flawlessly.

Written by: Erik Schluntz and Barry Zhang

This work draws on experiences building agents at Anthropic and valuable insights shared by customers.

文中提及的外部资源链接

• Claude Agent SDK: https://platform.claude.com/docs/en/agent-sdk/overview
• Strands Agents SDK (AWS): https://strandsagents.com/latest/
• Rivet: https://rivet.ironcladapp.com/
• Vellum: https://www.vellum.ai/
• Model Context Protocol: https://www.anthropic.com/news/model-context-protocol
• MCP Client Tutorial: https://modelcontextprotocol.io/tutorials/building-a-client
• Cookbook Patterns: https://platform.claude.com/cookbook/patterns-agents-basic-workflows
• Tool Use Documentation: https://www.anthropic.com/news/tool-use-ga
• Tool Use API Reference: https://docs.anthropic.com/en/docs/build-with-claude/tool-use
• SWE-bench Research: https://www.anthropic.com/research/swe-bench-sonnet
• Computer Use Demo: https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo