构建高效的智能体

Note: Much of the tooling landscape described in this post has changed since December 2024.

For our current approach, see how we built Claude Managed Agents and the Managed Agents documentation.

Over the past year, we've worked with dozens of teams building large language model (LLM) agents across industries.

Consistently, the most successful implementations weren't using complex frameworks or specialized libraries.

Instead, they were building with simple, composable patterns.

In this post, we share what we’ve learned from working with our customers and building agents ourselves, and give practical advice for developers on building effective agents.

"Agent" can be defined in several ways.

Some customers define agents as fully autonomous systems that operate independently over extended periods, using various tools to accomplish complex tasks.

Others use the term to describe more prescriptive implementations that follow predefined workflows.

At Anthropic, we categorize all these variations as agentic systems, but draw an important architectural distinction between workflows and agents:

Below, we will explore both types of agentic systems in detail.

In Appendix 1 (“Agents in Practice”), we describe two domains where customers have found particular value in using these kinds of systems.

When building applications with LLMs, we recommend finding the simplest solution possible, and only increasing 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, however, optimizing single LLM calls with retrieval and in-context examples is usually enough.

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

These frameworks make it easy to get started by simplifying 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.

We suggest that developers start by using LLM APIs directly: many patterns can be implemented in 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 a common source of customer error.

See our cookbook for some sample implementations.

In this section, we’ll explore the common patterns for agentic systems we’ve seen in production.

We'll start with our foundational building block—the augmented LLM—and progressively increase complexity, from simple compositional workflows to autonomous agents.

The basic building block of agentic systems is an LLM enhanced with augmentations such as retrieval, tools, and memory.

Our current models can actively use these capabilities—generating their own search queries, selecting appropriate tools, and determining what information to retain.

We recommend focusing on two key aspects of the implementation: tailoring these capabilities to your specific use case and ensuring they provide an easy, well-documented interface for your LLM.

While there are many ways to implement these augmentations, one approach is through our recently released Model Context Protocol, which allows developers to integrate with a growing ecosystem of third-party tools with a simple client implementation.

For the remainder of this post, we'll assume each LLM call has access to these augmented capabilities.

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 (see "gate” in the diagram below) 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 off latency for higher accuracy, by making each LLM call an easier task.

Examples where prompt chaining is useful:

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:

LLMs can sometimes work simultaneously on a task and have their outputs aggregated programmatically.

This workflow, parallelization, manifests in two key variations:

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:

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 (in coding, for example, 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 topographically similar, the key difference from parallelization is its flexibility—subtasks aren't pre-defined, but determined by the orchestrator based on the specific input.

Example where orchestrator-workers is useful:

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 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:

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 judgement.

During execution, it's crucial for the agents 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.

We expand on best practices for tool development in Appendix 2 ("Prompt Engineering your Tools").

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.

We recommend extensive testing in sandboxed environments, along with the appropriate guardrails.

Examples where agents are useful:

The following examples are from our own implementations:

These building blocks aren't prescriptive.

They're common patterns that developers can shape and combine to fit different use cases.

The key to success, as with any LLM features, is measuring performance and iterating on implementations.

To repeat: you should consider adding complexity only when it demonstrably improves outcomes.

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, we try to follow three core principles:

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.

Written by Erik S. and Barry Zhang.

This work draws upon our experiences building agents at Anthropic and the valuable insights shared by our customers, for which we're deeply grateful.

Our work with customers has revealed two particularly promising applications for AI agents that demonstrate the practical value of the patterns discussed above.

Both applications illustrate how agents add the most value for tasks that require both conversation and action, have clear success criteria, enable feedback loops, and integrate meaningful human oversight.

Customer support combines familiar chatbot interfaces with enhanced capabilities through tool integration.

This is a natural fit for more open-ended agents because:

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.

The software development space has shown remarkable potential for LLM features, with capabilities evolving from code completion to autonomous problem-solving.

Agents are particularly effective because:

In our own implementation, agents can now solve real GitHub issues in the SWE-bench Verified benchmark based on the pull request description alone.

However, whereas automated testing helps verify functionality, human review remains crucial for ensuring solutions align with broader system requirements.

No matter which agentic system you're building, tools will likely be an important part of your agent.

Tools enable Claude to interact with external services and APIs by specifying their exact structure and definition in our API.

When Claude responds, it will include a tool use block in the API response if it plans to invoke a tool.

Tool definitions and specifications should be given just as much prompt engineering attention as your overall prompts.

In this brief appendix, we describe how to prompt engineer your tools.

There are often several 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 inside JSON.

In software engineering, differences like these are cosmetic and can be converted losslessly from one to the other.

However, some formats are much more difficult for an LLM to write than others.

Writing a diff requires knowing how many lines are changing in the chunk header before the new code is written.

Writing code inside JSON (compared to markdown) requires extra escaping of newlines and quotes.

Our suggestions for deciding on tool formats are the following:

One rule of thumb is to think about how much effort goes into human-computer interfaces (HCI), and plan to invest just as much effort in creating good agent-computer interfaces (ACI).

Here are some thoughts on how to do so:

While building our agent for SWE-bench, we actually spent more time optimizing our tools than the overall prompt.

For example, we found that the model would make mistakes with tools using relative filepaths after the agent had moved out of the root directory.

To fix this, we changed the tool to always require absolute filepaths—and we found that the model used this method flawlessly.