AI Agent 定义的社区参考

• 1: 概述
• 2: Building effective agents
• 3: OpenAI构建Agent的实用指南
• 3.1: 英文
• 3.2: 中文翻译
• 3.3: 中英文双语
• 4: I think “agent” may finally have a widely enough agreed upon definition to be useful jargon now

1 - 概述

定义在 什么是 AI Agent 和 什么不是 AI Agent。

写那两页的时候，我担心四要素是自己收窄出来的口径，和社区讲的不是一回事。对照过 2024–2026 社区常用的几份原文之后，我有了信息：我没有另起流派，只是把已经收敛的说法收成可判定的四要素，并故意比光谱派更窄、比「独立干活的数字员工」营销更严格。

最短的对照句

各家用词不同，落到工程上几乎是同一句。拿来对照的，是 Simon Willison 写成的这一句：

An LLM agent runs tools in a loop to achieve a goal.

LLM Agent = 为了达成目标，在循环里调用工具。出处：I think “agent” may finally have a widely enough agreed upon definition。Anthropic 在 Effective context engineering 里也收敛成：LLMs autonomously using tools in a loop。

本笔记的四要素就是把这句话拆开：谁在决策、是不是多步骤、有没有碰到环境、看没看反馈。Simon 也强调了停止条件（完成、失败、交给人）——这不是无限循环。

主要参考对象

经典教材（Russell & Norvig）仍然是另一套：任何能感知环境、按性能度量行动的东西。那套定义太过宽泛，已经写进 什么不是AI Agent，这里不再展开。下面只列 LLM Agent 这一波里，比较有参考意义的几份：

和本笔记对齐的地方

工程侧这几年基本都在对齐，只是用词不同。对照下来，我认可这四条：

1. 决策核心是语言模型，不是写死的 if/else — Anthropic / LangChain 说的 control flow。
2. 有环境行动（tools），不是只吐文本。
3. 有循环：看结果，再决定下一步 — ReAct / Anthropic 的 loop。
4. 有停止条件：目标完成、失败、或交给人。

OpenAI 也把 chatbot、单轮调用划出去，和我在「什么不是AI Agent」里的处理一致。Function Calling 我标记为「地基不是系统」：工具接口是模型能力，循环才是 Agent。社区里普遍这样区分。

弱自主也算 AI Agent。Anthropic、LangChain、OpenAI 都承认 human-in-the-loop。Agent 不是「完全没人管」。这一点我写进定义，不是为了放宽，而是不认可「必须全自动才叫 Agent」那种说法。

明确的差异点

Workflow 算不算 Agent。 Anthropic（以及部分 LangChain 论述）认为：路径若全是代码编排，哪怕每步都调 LLM+工具，仍叫 workflow，不叫 agent。本笔记写「弱自主也算」。如果弱自主被理解成「人写死步骤、模型只填槽」，按 Anthropic 会落在 workflow 一侧。我认他们这条更严的线：模型必须至少能选下一步或选工具，否则降为 workflow，不进本笔记的主线对象。

记忆是不是定义的一部分。 Lilian Weng 把 Memory 写成三大件之一。Simon 明确反对：对话里的 tool 回执已经是短期记忆，不必另立一条。我没把长期记忆写进四要素，更接近后者。长期记忆是能力，不是「算不算 Agent」的门槛。

「独立完成任务」容易被营销带跑。 OpenAI 的 independently、产品名里的 Agent，和工程上的 tools in a loop 经常不是一回事。所以我把定义拆成「什么是 AI Agent / 什么不是 AI Agent」两页，就是不认可「比较能干活的 AI」这种起名。

推荐阅读

对照社区口径，以下三篇文章比较值得阅读：

1. Anthropic · Building effective agents — workflow vs agent，后面引用最多。
2. OpenAI 指南 PDF — 明确列出什么不是 Agent。
3. Simon Willison, 2025-09 — 最短、最好记的工程行话。

结构上最像本笔记那两页的，是 Hugging Face Agents Course · What is an Agent（定义 + agency 光谱 + Think/Act/Observe）。光谱那张表可以看，但不要拿它替换本笔记的四要素门槛。

补充内容

Agent 到底是什么？ By orange.ai 橘子

https://blog.orangesai.com/p/agent-what-is-it

2 - Building effective agents

来源： Building effective agents
日期： 2024 年 12 月 19 日
作者： Erik S.、Barry Zhang

构建有效的 Agent

We’ve worked with dozens of teams building LLM agents across industries. Consistently, the most successful implementations use simple, composable patterns rather than complex frameworks.

我们和几十个团队一起做过跨行业的 LLM Agent。一直成立的是：最成功的实现用的是简单、可组合的模式，而不是复杂框架。

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.

注：本文描述的工具生态自 2024 年 12 月以来已有不少变化。若看 Anthropic 现在的做法，见 how we built Claude Managed Agents 以及 Managed Agents 文档。

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.

过去一年，我们和几十个团队一起做过跨行业的大语言模型（LLM）Agent。一直成立的是：最成功的实现并没有用复杂框架或专用库，而是用简单、可组合的模式来搭建。

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 里学到的东西，并给开发者一些能落地的建议。

什么是 Agent？

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

「Agent」可以有好几套定义。有的客户把 Agent 说成长时间独立运行、用各种工具完成复杂任务的全自主系统。有的则用来指更处方化、跟着预定义 workflow 走的实现。在 Anthropic，我们把这些变体都归进 agentic systems（具代理性的系统），但在架构上把 workflow 和 agent 切开：

• Workflows are systems where LLMs and tools are orchestrated through predefined code paths.

• Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.

• Workflow：LLM 和工具沿着预定义的代码路径被编排。

• Agent：LLM 动态地主导自己的流程和工具使用，把「如何完成任务」的控制权留在模型手里。

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.

下面分别把两类 agentic system 讲清楚。附录 1（「实践中的 Agent」）写了两个客户感觉特别有价值的领域。

何时该用、何时不该用 Agent

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.

用 LLM 做应用时，我们建议先找最简单的解，只在需要时再加复杂度。这可能意味着根本不该做 agentic system。这类系统常常拿延迟和成本换更好的任务表现，你得判断这笔交换何时划算。

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.

真需要更复杂时：任务边界清楚，workflow 更可预期、更稳定；需要灵活、并且要在规模上靠模型做决策，才更适合 Agent。对很多应用来说，把单次 LLM 调用用检索和上下文示例优化好，通常就够了。

何时、如何使用框架

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

让 agentic system 更好实现的框架有很多，包括：

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

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.

这些框架把调用 LLM、定义和解析工具、把调用串起来这类底层活简化了，上手容易。但它们常常多出一层抽象，把底层的 prompt 和回复盖住，调试更难。它们也会诱使人在更简单的搭法就够用时，仍去加复杂度。

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.

我们建议开发者先直接用 LLM API：很多模式几行代码就能写出来。如果还是用框架，确保你读得懂底下的代码。对「罩子下面是什么」的错误假设，是客户踩坑的常见来源。

See our cookbook for some sample implementations.

示例实现见 cookbook。

构建块、workflow 与 Agent

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.

这一节写我们在生产里见到的常见模式。从基础构建块—增强型 LLM——开始，再逐步加复杂度：从简单的组合式 workflow，到自主 Agent。

构建块：增强型 LLM

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.

agentic system 的基础构建块，是带了检索、工具、记忆这类增强的 LLM。现在的模型已经能主动用这些能力：自己生成检索查询、选择合适的工具、决定留下什么信息。

配图1：增强型 LLM

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.

实现时我们建议关注两点：按你的用例裁剪这些能力，并给 LLM 一个好用、文档清楚的接口。增强的做法很多，其中一种是当时刚发布的 Model Context Protocol：用一个简单的客户端实现，就能接到不断变大的第三方工具生态。

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

后文默认：每一次 LLM 调用都能用上这些增强能力。

Workflow：提示链

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.

提示链（Prompt chaining）把任务拆成一串步骤，每一次 LLM 调用处理上一次的输出。你可以在任意中间步加上程序化检查（见图里的 “gate” / 门控），确认流程正常。

配图2：提示链 workflow

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.

使用场景：任务能干净地拆成固定子任务时最合适。主要目的是用延迟换更高准确度——让每一次 LLM 调用都变成更简单的任务。

Examples where prompt chaining is useful:

提示链好用的例子：

• Generating Marketing copy, then translating it into a different language.

• Writing an outline of a document, checking that the outline meets certain criteria, then writing the document based on the outline.

• 先写营销文案，再翻译成另一种语言。

• 先写文档提纲，检查提纲是否满足若干标准，再按提纲写正文。

Workflow：路由

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.

路由先给输入分类，再送到专门的后续任务。这样能把关注点拆开，prompt 也可以做得更专。没有这条 workflow，为一种输入做的优化往往会伤到其他输入。

配图3：路由 workflow

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.

使用场景：复杂任务里类别清楚、分开处理更好，并且分类本身能做准——无论是 LLM 还是更传统的分类模型/算法。

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, cost-efficient models like Claude Haiku 4.5 and hard/unusual questions to more capable models like Claude Sonnet 4.5 to optimize for best performance.

• 把不同类型的客服问询（一般问题、退款、技术支持）送到不同的下游流程、prompt 和工具。

• 把容易/常见的问题分给更小、更省成本的模型（如 Claude Haiku 4.5），把难/少见的问题分给更强的模型（如 Claude Sonnet 4.5），用来换更好的性价比。

Workflow：并行化

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

有时可以让多个 LLM 同时做一件事，再用程序把输出汇总。这条并行化 workflow 有两个主要变体：

• Sectioning: Breaking a task into independent subtasks run in parallel.

• Voting: Running the same task multiple times to get diverse outputs.

• 切分（Sectioning）：把任务拆成彼此独立的子任务并行跑。

• 投票（Voting）：同一任务跑多次，拿到多样化的输出。

配图4：并行化 workflow

何时使用此工作流：当拆分的子任务可以并行处理以提高速度时，或者为了获得更可靠的结果而需要多种视角或多次尝试时，并行化是有效的。对于涉及多重考量因素的复杂任务，通常通过将每个考量因素分别交由独立的LLM调用来处理，使每个LLM能够专注于特定方面，这样LLM的表现通常会更好。

Examples where parallelization is useful:

并行化好用的例子：

Sectioning:

分层处理：

• Implementing guardrails where one model instance processes user queries while another screens them 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 evaluating LLM performance, where each LLM call evaluates a different aspect of the model’s performance on a given prompt.

• 实施“防护机制”：由一个模型实例处理用户查询，同时由另一个模型实例对查询进行筛查，以过滤不适当的内容或请求。这种方式通常比让同一个大语言模型（LLM）调用同时处理防护机制和核心响应的性能更优。

• 自动化评估以衡量大语言模型（LLM）的性能，即每次LLM调用都针对给定的提示语，评估模型性能的不同方面。

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.

• 审查一段代码有没有漏洞：用几条不同的 prompt 去看，发现问题就标出来。

• 判断某段内容是否不合适：多条 prompt 评不同侧面，或用不同的投票阈值来平衡误报和漏报。

Workflow：编排器–工人

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

在编排器–工人这条 workflow 里，中央 LLM 动态拆任务、委派给工人 LLM，再综合他们的结果。

配图5：编排器–工人 workflow

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:

编排器–工人好用的例子：

• Coding products that make complex changes to multiple files each time.

• Search tasks that involve gathering and analyzing information from multiple sources for possible relevant information.

• 每次都要对多个文件做复杂修改的编码产品。

• 要从多个来源收集、分析可能相关信息的搜索任务。

Workflow：评估器–优化器

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

在评估器–优化器这条 workflow 里，一次 LLM 调用生成回复，另一次在循环里给评估和反馈。

配图6：评估器–优化器 workflow

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.

何时使用此工作流：当我们拥有明确的评估标准，且迭代优化能带来可量化的价值时，此工作流尤为有效。判断其适用性的两个标志是：首先，当人类明确表达反馈意见时，大型语言模型（LLM）的响应能够得到明显改善；其次，大型语言模型能够提供此类反馈。这类似于人类作家在撰写一篇精炼的文档时所经历的迭代写作过程。

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.

• 文学翻译：译者 LLM 一开始可能抓不住某些细微处，评估器 LLM 能给出有用的批评。

• 需要多轮搜索和分析才能收全信息的复杂检索：由评估器决定还要不要再搜。

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

随着 LLM 在关键能力上成熟——理解复杂输入、做推理和规划、可靠地用工具、从错误里恢复——Agent 开始出现在生产里。Agent 的工作从人对它的一条命令、或一次交互讨论开始。任务清楚之后，它们独立规划、独立运转，必要时再回来向人要信息或判断。执行过程中，关键是每一步都要从环境拿到「ground truth / 环境真值」（例如工具回执或代码执行结果），用来评估进度。然后可以在检查点、或碰到阻塞时停下来等人反馈。任务常常在完成时结束，但也很常见会加上停止条件（例如最大迭代次数）来保持可控。

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”).

Agent 能处理复杂任务，实现却往往很直白。它们通常就是：LLM 根据环境反馈、在循环里使用工具。因此，工具集和文档必须设计得清楚、用心。工具开发的实践写在附录 2（「把工具当作 prompt 来工程化」）。

配图7：自主智能体

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.

何时使用智能体：智能体适用于那些难以或无法预测所需步骤数、且无法硬编码固定路径的开放式问题。大型语言模型（LLM）可能会运行多个回合，因此你必须对其决策能力抱有一定程度的信任。智能体的自主性使其成为在可信环境中扩展任务的理想选择。

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:

Agent 好用的例子：

The following examples are from our own implementations:

下面两个例子来自我们自己的实现：

• A coding Agent to resolve SWE-bench tasks, which involve edits to many files based on a task description;

• Our “computer use” reference implementation, where Claude uses a computer to accomplish tasks.

• 一个编码 Agent，用来解 SWE-bench 任务：根据任务描述改许多文件；

• 我们的 「computer use」参考实现：Claude 操作电脑来完成任务。

（原文配图：High-level flow of a coding agent。）

组合与定制这些模式

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.

这些积木不是处方。它们是常见模式，开发者可以按用例去塑造、去组合。和任何 LLM 功能一样，成功的关键是测量表现、迭代实现。再说一遍：只在能证明它改善结果时，才考虑加复杂度。

总结

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.

LLM 这件事上的成功，不是做出最精巧的系统，而是做出适合你需求的系统。从简单 prompt 开始，用充分的评测去优化，只有更简单的方案不够用时，再加多步的 agentic system。

When implementing agents, we try to follow three core principles:

实现 Agent 时，我们尽量守三条：

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.

4. 保持 Agent 设计简单。

5. 把规划步骤显式展示出来，优先透明。

6. 用心打磨 agent-computer interface（ACI / Agent–计算机接口）：把工具文档写透，并把工具测透。

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.

框架能帮你快点起步，但走向生产时，不要犹豫去减抽象层、用基本组件来搭。守住这几条，做出的 Agent 才不仅有能力，还能可靠、可维护、被使用者信任。

致谢

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.

Erik S. 与 Barry Zhang 执笔。这篇文章来自我们在 Anthropic 做 Agent 的经验，以及客户分享的洞见。非常感谢。

附录 1：实践中的 Agent

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.

和客户合作下来，有两类应用特别有前景，也把上面那些模式的实际价值说清楚了。两者都说明：Agent 最能加分的任务，是既要对话又要行动、成功标准清楚、能形成反馈循环、并且能接进有意义的人的监督。

A. 客户支持

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

客户支持把熟悉的聊天机器人界面，和通过工具集成得到的增强能力合在一起。它天然适合更开放的 Agent，因为：

• Support interactions naturally follow a conversation flow while requiring access to external information and actions;

• Tools can be integrated to pull customer data, order history, and knowledge base articles;

• Actions such as issuing refunds or updating tickets can be handled programmatically; and

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

已有几家公司用按次、且只对成功解决收费的定价，证明这条路走得通——这本身就是对 Agent 有效性的信心。

B. 编码 Agent

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:

软件开发这块已经显示出 LLM 能力的明显潜力：从代码补全走到自主解题。Agent 在这里特别有效，因为：

• Code solutions are verifiable through automated tests;

• Agents can iterate on solutions using test results as feedback;

• The problem space is well-defined and structured; and

• Output quality can be measured objectively.

• 代码方案可以用自动测试验证；

• Agent 能把测试结果当反馈，迭代方案；

• 问题空间清楚、有结构；

• 输出质量可以客观度量。

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.

在我们自己的实现里，Agent 现在已经能仅凭拉取请求描述，解 SWE-bench Verified 基准里真实的 GitHub issue。不过自动测试只能帮着验证功能是否成立；要保证方案还对齐更宽的系统要求，人的审阅仍然关键。

附录 2：把工具当作 prompt 来工程化

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.

无论你在搭哪一种 agentic system，工具多半会是 Agent 的重要部分。工具让 Claude 能和外部服务、API 交互：你在 API 里把工具的结构和定义写精确。Claude 若打算调用工具，回复里会带上一个 tool use 块。工具的定义和规格，该得到和整体 prompt 同等分量的 prompt engineering 注意力。这篇短附录写怎么把工具当作 prompt 来工程化。

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.

同一件动作往往有好几种写法。例如改文件：可以写 diff，也可以重写整个文件。结构化输出：代码可以放在 markdown 里，也可以放在 JSON 里。在软件工程里，这类差别是表面的，可以无损互转。但对 LLM 来说，有些格式比另一些难写得多。写 diff 要求在新代码写出来之前，就知道 chunk header 里改了多少行。把代码写进 JSON（相对 markdown）还要额外转义换行和引号。

Our suggestions for deciding on tool formats are the following:

关于工具格式，我们的建议是：

• 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’s no formatting “overhead” such as having to keep an accurate count of thousands of lines of code, or string-escaping any code it writes.

• 给模型足够的 token 去「想」，免得它把自己写进死角。

• 让格式贴近模型在互联网文本里自然见过的样子。

• 不要有格式上的「额外负担」：例如必须准确数清几千行代码，或对它写下的任何代码做字符串转义。

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:

一条经验：想想人机接口（HCI）花过多少功夫，就准备花同样多的功夫去做像样的 Agent–计算机接口（ACI）。一些做法：

• 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 also true for the model. A good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools.

• 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 on your team. This is especially important when using many similar tools.

• Test how the model uses your tools: Run many example inputs in our workbench to see what mistakes the model makes, and iterate.

• Poka-yoke your tools. Change the arguments so that it is harder to make mistakes.

• 把自己放进模型的位置。只看描述和参数，用这个工具是否一目了然，还是你也得仔细想？若你都要想，模型大概也要想。一份好的工具定义常常包括：用法示例、边界情况、输入格式要求、以及和其他工具的清楚边界。

• 怎样改参数名或描述能让事情更显然？把它当成给组里一名初级开发者写一份出色的 docstring。工具很多、又很像的时候尤其重要。

• 测试模型怎么用你的工具：在 workbench 里跑大量示例输入，看它会犯什么错，再迭代。

• 给工具做 poka-yoke（防呆）。改参数，让出错更难。

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.

做 SWE-bench 的 Agent 时，我们花在优化工具上的时间，其实比花在整体 prompt 上更多。例如：Agent 离开根目录之后，用相对路径的工具就会出错。我们改成始终要求绝对路径——之后模型用这个方法几乎不出错。

3 - OpenAI构建Agent的实用指南

内容来源：

https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf

3.1 - 英文

备注： 使用 marker 工具从 pdf 转换而来，命令为 arker_single --mode fast --disable_ocr --output_format markdown --output_dir /home/sky/Downloads/markdown /home/sky/Downloads/a-practical-guide-to-building-agents.pdf

Introduction

Large language models are becoming increasingly capable of handling complex, multi-step tasks. Advances in reasoning, multimodality, and tool use have unlocked a new category of LLM-powered systems known as agents.

This guide is designed for product and engineering teams exploring how to build their first agents, distilling insights from numerous customer deployments into practical and actionable best practices. It includes frameworks for identifying promising use cases, clear patterns for designing agent logic and orchestration, and best practices to ensure your agents run safely, predictably, and effectively.

After reading this guide, you’ll have the foundational knowledge you need to confidently start building your first agent.

What is an agent?

While conventional software enables users to streamline and automate workflows, agents are able to perform the same workflows on the users’ behalf with a high degree of independence.

Agents are systems that independently accomplish tasks on your behalf.

A workflow is a sequence of steps that must be executed to meet the user’s goal, whether that’s resolving a customer service issue, booking a restaurant reservation, committing a code change, or generating a report.

Applications that integrate LLMs but don’t use them to control workflow execution—think simple chatbots, single-turn LLMs, or sentiment classifiers—are not agents.

More concretely, an agent possesses core characteristics that allow it to act reliably and consistently on behalf of a user:

When should you build an agent?

Building agents requires rethinking how your systems make decisions and handle complexity. Unlike conventional automation, agents are uniquely suited to workflows where traditional deterministic and rule-based approaches fall short.

Consider the example of payment fraud analysis. A traditional rules engine works like a checklist, flagging transactions based on preset criteria. In contrast, an LLM agent functions more like a seasoned investigator, evaluating context, considering subtle patterns, and identifying suspicious activity even when clear-cut rules aren’t violated. This nuanced reasoning capability is exactly what enables agents to manage complex, ambiguous situations effectively.

As you evaluate where agents can add value, prioritize workflows that have previously resisted automation, especially where traditional methods encounter friction:

Before committing to building an agent, validate that your use case can meet these criteria clearly. Otherwise, a deterministic solution may suffice.

Agent design foundations

In its most fundamental form, an agent consists of three core components:

Here’s what this looks like in code when using OpenAI’s Agents SDK. You can also implement the same concepts using your preferred library or building directly from scratch.

weather_agent = Agent(
    name="Weather agent",
    instructions="You are a helpful agent who can talk to users about the weather.",
    tools=[get_weather],
)

Selecting your models

Different models have different strengths and tradeoffs related to task complexity, latency, and cost. As we’ll see in the next section on Orchestration, you might want to consider using a variety of models for different tasks in the workflow.

Not every task requires the smartest model—a simple retrieval or intent classification task may be handled by a smaller, faster model, while harder tasks like deciding whether to approve a refund may benefit from a more capable model.

An approach that works well is to build your agent prototype with the most capable model for every task to establish a performance baseline. From there, try swapping in smaller models to see if they still achieve acceptable results. This way, you don’t prematurely limit the agent’s abilities, and you can diagnose where smaller models succeed or fail.

In summary, the principles for choosing a model are simple:

You can find a comprehensive guide to selecting OpenAI models here.

Defining tools

Tools extend your agent’s capabilities by using APIs from underlying applications or systems. For legacy systems without APIs, agents can rely on computer-use models to interact directly with those applications and systems through web and application UIs—just as a human would.

Each tool should have a standardized definition, enabling flexible, many-to-many relationships between tools and agents. Well-documented, thoroughly tested, and reusable tools improve discoverability, simplify version management, and prevent redundant definitions.

Broadly speaking, agents need three types of tools:

For example, here’s how you would equip the agent defined above with a series of tools when using the Agents SDK:

from agents import Agent, WebSearchTool, function_tool
@function_tool 
def save_results(output): 
    db.insert({ : output, : datetime.time()})
    return "File saved"
    
search_agent = Agent(
    name="Search agent",
    instructions="Help the user search the internet and save results if asked.",
    tools=[WebSearchTool(),save_results],
) 

As the number of required tools increases, consider splitting tasks across multiple agents (see Orchestration).

Configuring instructions

High-quality instructions are essential for any LLM-powered app, but especially critical for agents. Clear instructions reduce ambiguity and improve agent decision-making, resulting in smoother workflow execution and fewer errors.

Best practices for agent instructions

You can use advanced models, like o1 or o3-mini, to automatically generate instructions from existing documents. Here’s a sample prompt illustrating this approach:

Orchestration

With the foundational components in place, you can consider orchestration patterns to enable your agent to execute workflows effectively.

While it’s tempting to immediately build a fully autonomous agent with complex architecture, customers typically achieve greater success with an incremental approach.

In general, orchestration patterns fall into two categories:

1. Single-agent systems, where a single model equipped with appropriate tools and instructions executes workflows in a loop

2. Multi-agent systems, where workflow execution is distributed across multiple coordinated agents

Let’s explore each pattern in detail.

Single-agent systems

A single agent can handle many tasks by incrementally adding tools, keeping complexity manageable and simplifying evaluation and maintenance. Each new tool expands its capabilities without prematurely forcing you to orchestrate multiple agents.

Every orchestration approach needs the concept of a ‘run’, typically implemented as a loop that lets agents operate until an exit condition is reached. Common exit conditions include tool calls, a certain structured output, errors, or reaching a maximum number of turns.

For example, in the Agents SDK, agents are started using the method, which loops over the LLM until either: Runner.run()

1. A final-output tool is invoked, defined by a specific output type

2. The model returns a response without any tool calls (e.g., a direct user message)

Example usage:

Agents.run(agent, [UserMessage("What's the capital of the USA?")]) 

This concept of a while loop is central to the functioning of an agent. In multi-agent systems, as you’ll see next, you can have a sequence of tool calls and handoffs between agents but allow the model to run multiple steps until an exit condition is met.

An effective strategy for managing complexity without switching to a multi-agent framework is to use prompt templates. Rather than maintaining numerous individual prompts for distinct use cases, use a single flexible base prompt that accepts policy variables. This template approach adapts easily to various contexts, significantly simplifying maintenance and evaluation. As new use cases arise, you can update variables rather than rewriting entire workflows.

When to consider creating multiple agent

Our general recommendation is to maximize a single agent’s capabilities first. More agents can provide intuitive separation of concepts, but can introduce additional complexity and overhead, so often a single agent with tools is sufficient.

For many complex workflows, splitting up prompts and tools across multiple agents allows for improved performance and scalability. When your agents fail to follow complicated instructions or consistently select incorrect tools, you may need to further divide your system and introduce more distinct agents.

Practical guidelines for splitting agents include:

• Complex logic: When prompts contain many conditional statements (multiple if-then-else branches), and prompt templates get difficult to scale, consider dividing each logical segment across separate agents.

• Tool overload: The issue isn’t solely the number of tools, but their similarity or overlap. Some implementations successfully manage more than 15 well-defined, distinct tools while others struggle with fewer than 10 overlapping tools. Use multiple agents if improving tool clarity by providing descriptive names, clear parameters, and detailed descriptions doesn’t improve performance.

Multi-agent systems

While multi-agent systems can be designed in numerous ways for specific workflows and requirements, our experience with customers highlights two broadly applicable categories:

• Manager (agents as tools): A central “manager” agent coordinates multiple specialized agents via tool calls, each handling a specific task or domain.

• Decentralized (agents handing off to agents): Multiple agents operate as peers, handing off tasks to one another based on their specializations.

Multi-agent systems can be modeled as graphs, with agents represented as nodes. In the manager pattern, edges represent tool calls whereas in the decentralized pattern, edges represent handoffs that transfer execution between agents.

Regardless of the orchestration pattern, the same principles apply: keep components flexible, composable, and driven by clear, well-structured prompts.

The manager pattern empowers a central LLM—the “manager”—to orchestrate a network of specialized agents seamlessly through tool calls. Instead of losing context or control, the manager intelligently delegates tasks to the right agent at the right time, effortlessly synthesizing the results into a cohesive interaction. This ensures a smooth, unified user experience, with specialized capabilities always available on-demand.

This pattern is ideal for workflows where you only want one agent to control workflow execution and have access to the user.

Manager pattern

from agents import Agent, Runner

 manager_agent = Agent(
    name="manager_agent",
    instructions=(
        "You are a translation agent. You use the tools given to you to translate."
        "If asked for multiple translations, you call the relevant tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="translate_to_spanish",
            tool_description="Translate the user's message to Spanish",
        ),
        french_agent.as_tool(
            tool_name="translate_to_french",
            tool_description="Translate the user's message to French",
        ),
        italian_agent.as_tool(
            tool_name="translate_to_italian",
            tool_description="Translate the user's message to Italian",
        ),
    ]
 )
 
async def main():
     msg = input("Translate 'hello' to Spanish, French and Italian for me!")

     orchestrator_output =  await Runner.run(
        manager_agent,msg)

    message orchestrator_output.new_messages:
        print(f"  - Translation step: {message.content}")

Decentralized pattern

In a decentralized pattern, agents can ‘handoff’ workflow execution to one another. Handoffs are a one way transfer that allow an agent to delegate to another agent. In the Agents SDK, a handoff is a type of tool, or function. If an agent calls a handoff function, we immediately start execution on that new agent that was handed off to while also transferring the latest conversation state.

This pattern involves using many agents on equal footing, where one agent can directly hand off control of the workflow to another agent. This is optimal when you don’t need a single agent maintaining central control or synthesis—instead allowing each agent to take over execution and interact with the user as needed.

For example, here’s how you’d implement the decentralized pattern using the Agents SDK for a customer service workflow that handles both sales and support:

# 源码太长见 pdf 文件

This pattern is especially effective for scenarios like conversation triage, or whenever you prefer specialized agents to fully take over certain tasks without the original agent needing to remain involved. Optionally, you can equip the second agent with a handoff back to the original agent, allowing it to transfer control again if necessary.

Guardrails

Well-designed guardrails help you manage data privacy risks (for example, preventing system prompt leaks) or reputational risks (for example, enforcing brand aligned model behavior). You can set up guardrails that address risks you’ve already identified for your use case and layer in additional ones as you uncover new vulnerabilities. Guardrails are a critical component of any LLM-based deployment, but should be coupled with robust authentication and authorization protocols, strict access controls, and standard software security measures.

Think of guardrails as a layered defense mechanism. While a single one is unlikely to provide sufficient protection, using multiple, specialized guardrails together creates more resilient agents.

In the diagram below, we combine LLM-based guardrails, rules-based guardrails such as regex, and the OpenAI moderation API to vet our user inputs.

Types of guardrails

Building guardrails

Set up guardrails that address the risks you’ve already identified for your use case and layer in additional ones as you uncover new vulnerabilities.

We’ve found the following heuristic to be effective:

1. Focus on data privacy and content safety

2. Add new guardrails based on real-world edge cases and failures you encounter

3. Optimize for both security and user experience, tweaking your guardrails as your agent evolves.

For example, here’s how you would set up guardrails when using the Agents SDK:

# 源码太长见 pdf 文件

The Agents SDK treats guardrails as first-class concepts, relying on optimistic execution by default. Under this approach, the primary agent proactively generates outputs while guardrails run concurrently, triggering exceptions if constraints are breached.

Guardrails can be implemented as functions or agents that enforce policies such as jailbreak prevention, relevance validation, keyword filtering, blocklist enforcement, or safety classification. For example, the agent above processes a math question input optimistically until the math_homework_tripwire guardrail identifies a violation and raises an exception.

Conclusion

Agents mark a new era in workflow automation, where systems can reason through ambiguity, take action across tools, and handle multi-step tasks with a high degree of autonomy. Unlike simpler LLM applications, agents execute workflows end-to-end, making them well-suited for use cases that involve complex decisions, unstructured data, or brittle rule-based systems.

To build reliable agents, start with strong foundations: pair capable models with well-defined tools and clear, structured instructions. Use orchestration patterns that match your complexity level, starting with a single agent and evolving to multi-agent systems only when needed. Guardrails are critical at every stage, from input filtering and tool use to human-in-the-loop intervention, helping ensure agents operate safely and predictably in production.

The path to successful deployment isn’t all-or-nothing. Start small, validate with real users, and grow capabilities over time. With the right foundations and an iterative approach, agents can deliver real business value—automating not just tasks, but entire workflows with intelligence and adaptability.

If you’re exploring agents for your organization or preparing for your first deployment, feel free to reach out. Our team can provide the expertise, guidance, and hands-on support to ensure your success.

3.2 - 中文翻译

引言

大型语言模型正日益能够处理复杂的多步骤任务。推理、多模态和工具使用方面的进步开启了一类新的由 LLM 驱动的系统，称为 agent。

本指南专为探索如何构建其首批 agent 的产品和工程团队而设计，将大量客户部署中的洞见提炼为实用且可操作的最佳实践。它包含用于识别有前景用例的框架、设计 agent 逻辑与编排的清晰模式，以及确保你的 agent 安全、可预测且高效运行的最佳实践。

阅读本指南后，你将掌握自信地开始构建你的第一个代理所需的基础知识。

什么是代理？

传统软件使用户能够简化和自动化工作流，而 agent 则能够以高度自主性代表用户执行相同的工作流。

代理是能够代表你独立完成任务的系统。

工作流是为达成用户目标而必须执行的一系列步骤，无论是解决客户服务问题、预订餐厅、提交代码更改，还是生成报告。

集成了 LLM 但不用其控制工作流执行的应用程序——比如简单的聊天机器人、单轮 LLM 或情感分类器——都不是 agent。

更具体地说，agent 具备一些核心特征，使其能够代表用户可靠且一致地行动：

1. 它利用 LLM 来管理工作流执行并做出决策。它能识别工作流何时完成，并可在需要时主动纠正自己的行动。如果失败，它可以停止执行并将控制权交还给用户。
2. 它可以访问各种工具与外部系统交互——既用于收集上下文，也用于采取行动——并根据工作流的当前状态动态选择合适的工具，始终在明确定义的护栏内运行。

你应该在什么时候构建 agent？

构建 agent 需要重新思考你的系统如何做出决策并处理复杂性。与传统自动化不同，agent 特别适合那些传统确定性和基于规则的方法难以胜任的工作流。

以支付欺诈分析为例。传统的规则引擎像一份检查清单，根据预设标准标记交易。相比之下，LLM 智能体更像一位经验丰富的调查员，评估上下文、考虑细微模式，并在即使没有违反明确规则的情况下识别可疑活动。这种细微推理能力正是使智能体能够有效管理复杂、模糊情况的关键。

在评估智能体可以在哪些方面增加价值时，优先考虑那些此前一直抗拒自动化的工作流，尤其是传统方法遇到阻力的地方：

在决定构建智能体之前，请明确验证你的用例能否满足这些标准。否则，确定性解决方案可能就足够了。

Agent 设计基础

在最基本的形式中，一个 Agent 由三个核心组件构成：

以下是使用 OpenAI 的 Agents SDK 时这在代码中的样子。你也可以使用你偏好的库或直接从零开始构建来实现相同的概念。

weather_agent = Agent(
    name="Weather agent",
    instructions="You are a helpful agent who can talk to users about the weather.",
    tools=[get_weather],
)

选择你的模型

不同的模型在任务复杂度、延迟和成本方面各有优势和权衡。正如我们将在下一节关于编排的内容中看到的，你可能需要考虑在工作流中为不同任务使用多种模型。

并非每项任务都需要最智能的模型——简单的检索或意图分类任务可以由更小、更快的模型处理，而像决定是否批准退款这样的更难任务则可能受益于能力更强的模型。

一个行之有效的方法是，在每个任务上都使用能力最强的模型来构建你的智能体原型，以建立性能基线。在此基础上，尝试换用更小的模型，看看它们是否仍能达到可接受的结果。这样，你就不会过早地限制智能体的能力，并且可以诊断出更小的模型在哪些方面成功或失败。

总之，选择模型的原则很简单：

你可以在这里找到选择 OpenAI 模型的全面指南。

定义工具

工具通过使用底层应用程序或系统的 API 来扩展智能体的能力。对于没有 API 的遗留系统，智能体可以依靠计算机使用模型，像人类一样通过网页和应用程序界面直接与这些应用程序和系统交互。

每个工具都应有标准化定义，从而实现工具与智能体之间灵活的多对多关系。文档完善、经过充分测试且可复用的工具能提高可发现性、简化版本管理并防止重复定义。

广义而言，智能体需要三类工具：

例如，以下是在使用 Agents SDK 时，如何为上面定义的智能体配备一系列工具：

from agents import Agent, WebSearchTool, function_tool
@function_tool 
def save_results(output): 
    db.insert({ : output, : datetime.time()})
    return "File saved"
    
search_agent = Agent(
    name="Search agent",
    instructions="Help the user search the internet and save results if asked.",
    tools=[WebSearchTool(),save_results],
) 

随着所需工具数量的增加，考虑将任务拆分给多个 agent（参见编排）。

配置指令

高质量的指令对于任何由 LLM 驱动的应用都至关重要，但对 agent 来说尤为关键。清晰的指令能减少歧义，提升 agent 的决策能力，从而实现更顺畅的工作流执行和更少的错误。

指令的最佳实践

你可以使用高级模型，如 o1 或 o3-mini，从现有文档中自动生成指令。以下是一个示例提示词，展示了这种方法：

编排

有了基础组件之后，你可以考虑编排模式，使你的智能体能够有效执行工作流。

虽然人们很容易想要立即构建一个具有复杂架构的完全自主智能体，但客户通常通过渐进式方法取得更大的成功。

一般来说，编排模式分为两类：

1. 单智能体系统，即单个模型配备适当的工具和指令，在循环中执行工作流
2. 多智能体系统，工作流执行分布在多个协同工作的智能体上

让我们详细探讨每种模式。

单智能体系统

单个智能体可以通过逐步添加工具来处理许多任务，保持复杂性可控，并简化评估和维护。每添加一个新工具都能扩展其能力，而不会过早地迫使你去编排多个智能体。

每种编排方法都需要“运行”的概念，通常实现为一个循环，让 agent 持续运行，直到达到退出条件。常见的退出条件包括工具调用、特定的结构化输出、错误，或达到最大轮次。

例如，在 Agents SDK 中，agent 通过该方法启动，它会在 LLM 上循环，直到满足以下任一条件：Runner.run()

1. 调用最终输出工具，由特定的输出类型定义
2. 模型返回一个不包含任何工具调用的响应（例如，直接的用户消息）

示例用法：

Agents.run(agent, [UserMessage("What's the capital of the USA?")]) 

while 循环这一概念对 agent 的运行至关重要。在多 agent 系统中，正如你接下来会看到的，你可以让一系列工具调用和 agent 之间的交接依次进行，但允许模型运行多个步骤，直到满足退出条件。

在不切换到多智能体框架的情况下管理复杂性的一种有效策略是使用提示模板。与其为不同的用例维护大量单独的提示，不如使用一个接受策略变量的灵活基础提示。这种模板方法可以轻松适应各种场景，显著简化维护和评估。当新的用例出现时，你可以更新变量，而不是重写整个工作流。

何时考虑创建多个智能体

我们的一般建议是首先最大化单个智能体的能力。更多的智能体可以提供直观的概念分离，但会引入额外的复杂性和开销，因此通常一个配备工具的智能体就足够了。

对于许多复杂的工作流程，将提示和工具分散到多个智能体中可以提高性能和可扩展性。当你的智能体无法遵循复杂的指令或持续选择错误的工具时，你可能需要进一步拆分系统并引入更多不同的智能体。

拆分智能体的实用指南包括：

• 复杂逻辑：当提示词包含大量条件语句（多个 if-then-else 分支），且提示词模板难以扩展时，考虑将每个逻辑段划分到不同的智能体中。
• 工具过载：问题不仅仅在于工具的数量，还在于它们的相似性或重叠。有些实现成功管理了超过 15 个定义明确、各不相同的工具，而另一些则在不到 10 个重叠工具时就举步维艰。如果通过提供描述性名称、清晰的参数和详细的描述来提升工具清晰度后性能仍未改善，则应使用多个智能体。

多智能体系统

虽然多 agent 系统可以针对特定工作流和需求以多种方式设计，但我们与客户的实践经验突出了两个广泛适用的类别：

• 管理者（agent 即工具）：一个中央“管理者”agent 通过工具调用协调多个专业化 agent，每个 agent 处理特定任务或领域。
• 去中心化（智能体交接给智能体）：多个智能体作为对等体运行，根据各自的专长相互交接任务。

多智能体系统可以建模为图，智能体表示为节点。在管理者模式中，边表示工具调用，而在去中心化模式中，边表示在智能体之间转移执行的交接。

无论采用何种编排模式，相同的原则都适用：保持组件灵活、可组合，并由清晰、结构良好的提示词驱动。

管理者模式赋予一个中央 LLM——即“管理者”——通过工具调用无缝编排专业化 agent 网络的能力。管理者不会丢失上下文或控制权，而是智能地在正确的时间将任务委派给正确的 agent，轻松地将结果综合为连贯的交互。这确保了流畅、统一的用户体验，专业化能力始终可按需调用。

这种模式非常适合那些你只希望由一个智能体控制工作流执行并直接与用户交互的工作流。

管理者模式

from agents import Agent, Runner

 manager_agent = Agent(
    name="manager_agent",
    instructions=(
        "You are a translation agent. You use the tools given to you to translate."
        "If asked for multiple translations, you call the relevant tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="translate_to_spanish",
            tool_description="Translate the user's message to Spanish",
        ),
        french_agent.as_tool(
            tool_name="translate_to_french",
            tool_description="Translate the user's message to French",
        ),
        italian_agent.as_tool(
            tool_name="translate_to_italian",
            tool_description="Translate the user's message to Italian",
        ),
    ]
 )
 
async def main():
     msg = input("Translate 'hello' to Spanish, French and Italian for me!")

     orchestrator_output =  await Runner.run(
        manager_agent,msg)

    message orchestrator_output.new_messages:
        print(f"  - Translation step: {message.content}")

声明式图与非声明式图

一些框架是声明式的，要求开发者通过由节点（智能体）和边（确定性或动态交接）构成的图，预先明确地定义工作流中的每一个分支、循环和条件。虽然这有利于视觉上的清晰性，但随着工作流变得更加动态和复杂，这种方法很快就会变得繁琐且具有挑战性，往往还需要学习专门的领域特定语言。

相比之下，Agents SDK 采用了更灵活的代码优先方法。开发者可以使用熟悉的编程结构直接表达工作流逻辑，而无需预先定义整个图，从而实现更动态、更适应性强的智能体编排。

去中心化模式

在去中心化模式中，智能体可以将工作流执行“移交”给彼此。移交是一种单向转移，允许一个智能体委托给另一个智能体。在 Agents SDK 中，移交是一种工具或函数。如果一个智能体调用移交函数，我们会立即开始在移交目标的新智能体上执行，同时转移最新的对话状态。

这种模式涉及在平等基础上使用多个智能体，其中一个智能体可以直接将工作流的控制权移交给另一个智能体。当你不需要单个智能体维持集中控制或综合时，这是最优选择——而是允许每个智能体接管执行并按需与用户交互。

例如，以下是如何使用 Agents SDK 为同时处理销售和支持的客户服务工作流实现去中心化模式：

# 源码太长见 pdf 文件

这种模式对于对话分流等场景特别有效，或者当你希望由专门的智能体完全接管某些任务、而原始智能体无需继续参与时，也非常适用。你还可以选择为第二个智能体配备一个移交回原始智能体的功能，使其在必要时能够再次转移控制权。

护栏

设计良好的护栏有助于你管理数据隐私风险（例如，防止系统提示泄露）或声誉风险（例如，确保模型行为符合品牌规范）。你可以设置护栏来应对已经为你的用例识别出的风险，并在发现新的漏洞时逐步增加更多护栏。护栏是任何基于 LLM 的部署的关键组成部分，但应与稳健的身份验证和授权协议、严格的访问控制以及标准软件安全措施相结合。

将护栏视为一种分层防御机制。虽然单一护栏不太可能提供足够的保护，但将多个专门的护栏结合使用可以创建更具弹性的代理。

在下图中，我们结合了基于 LLM 的护栏、基于规则的护栏（如正则表达式）以及 OpenAI 审核 API 来审查用户输入。

护栏类型

构建护栏

设置护栏以应对您已为用例识别的风险，并在发现新漏洞时增加更多护栏。

我们发现以下启发式方法非常有效：

1. 关注数据隐私和内容安全
2. 根据你在实际应用中遇到的边缘情况和失败案例，添加新的防护措施
3. 在安全性和用户体验之间进行优化，随着你的智能体不断演进，调整你的防护措施。

例如，以下是使用 Agents SDK 时设置护栏的方法：

# 源码太长见 pdf 文件

Agents SDK 将护栏视为一等概念，默认依赖乐观执行。在这种方法下，主智能体主动生成输出，而护栏则并发运行，一旦违反约束便触发异常。

护栏可以实现为函数或智能体，用于执行诸如防越狱、相关性验证、关键词过滤、黑名单执行或安全分类等策略。例如，上述智能体乐观地处理数学问题输入，直到 math_homework_tripwire 护栏识别出违规并引发异常。

人工干预计划

人工干预是一项关键保障，使你能够在不损害用户体验的情况下提升智能体在真实世界中的表现。它在部署初期尤为重要，有助于识别故障、发现边缘情况并建立稳健的评估循环。

实施人工干预机制能让智能体在无法完成任务时优雅地移交控制权。在客户服务中，这意味着将问题升级给人工客服。对于编程智能体，这意味着将控制权交还给用户。

通常有两种主要触发条件需要人工干预：

• 超出失败阈值：为智能体的重试次数或操作设置限制。如果智能体超出这些限制（例如多次尝试后仍无法理解客户意图），则升级至人工干预。
• 高风险操作：敏感、不可逆或高风险的操作应触发人工监督，直到对智能体可靠性的信心增强为止。例如取消用户订单、批准大额退款或进行支付。

结论

Agent 标志着工作流自动化的新时代，系统能够在模糊情境中进行推理、跨工具采取行动，并以高度自主性处理多步骤任务。与更简单的 LLM 应用不同，Agent 能够端到端地执行工作流，因此非常适合涉及复杂决策、非结构化数据或脆弱规则系统的用例。

要构建可靠的 Agent，首先要打好基础：将能力强的模型与定义明确的工具以及清晰、结构化的指令相结合。使用与你的复杂程度相匹配的编排模式，从单 Agent 开始，仅在需要时演进到多 Agent 系统。护栏在每个阶段都至关重要，从输入过滤和工具使用到人工介入干预，有助于确保 Agent 在生产环境中安全且可预测地运行。

成功部署的路径并非全有或全无。从小处着手，用真实用户进行验证，并随着时间推移逐步扩展能力。有了正确的基础和迭代方法，Agent 可以带来真正的商业价值——不仅自动化任务，还能以智能和适应性自动化整个工作流。

如果您正在为您的组织探索智能体，或正在为首次部署做准备，欢迎随时联系我们。我们的团队可以提供专业知识、指导以及实操支持，确保您取得成功。

3.3 - 中英文双语

Introduction

引言

Large language models are becoming increasingly capable of handling complex, multi-step tasks. Advances in reasoning, multimodality, and tool use have unlocked a new category of LLM-powered systems known as agents. 大型语言模型正日益能够处理复杂的多步骤任务。推理、多模态和工具使用方面的进步开启了一类新的由 LLM 驱动的系统，称为 agent。

This guide is designed for product and engineering teams exploring how to build their first agents, distilling insights from numerous customer deployments into practical and actionable best practices. It includes frameworks for identifying promising use cases, clear patterns for designing agent logic and orchestration, and best practices to ensure your agents run safely, predictably, and effectively. 本指南专为探索如何构建其首批 agent 的产品和工程团队而设计，将大量客户部署中的洞见提炼为实用且可操作的最佳实践。它包含用于识别有前景用例的框架、设计 agent 逻辑与编排的清晰模式，以及确保你的 agent 安全、可预测且高效运行的最佳实践。

After reading this guide, you’ll have the foundational knowledge you need to confidently start building your first agent. 阅读本指南后，你将掌握自信地开始构建你的第一个代理所需的基础知识。

What is an agent?

什么是代理？

While conventional software enables users to streamline and automate workflows, agents are able to perform the same workflows on the users’ behalf with a high degree of independence. 传统软件使用户能够简化和自动化工作流，而 agent 则能够以高度自主性代表用户执行相同的工作流。

Agents are systems that independently accomplish tasks on your behalf. 代理是能够代表你独立完成任务的系统。

A workflow is a sequence of steps that must be executed to meet the user’s goal, whether that’s resolving a customer service issue, booking a restaurant reservation, committing a code change, or generating a report. 工作流是为达成用户目标而必须执行的一系列步骤，无论是解决客户服务问题、预订餐厅、提交代码更改，还是生成报告。

Applications that integrate LLMs but don’t use them to control workflow execution—think simple chatbots, single-turn LLMs, or sentiment classifiers—are not agents. 集成了 LLM 但不用其控制工作流执行的应用程序——比如简单的聊天机器人、单轮 LLM 或情感分类器——都不是 agent。

More concretely, an agent possesses core characteristics that allow it to act reliably and consistently on behalf of a user: 更具体地说，agent 具备一些核心特征，使其能够代表用户可靠且一致地行动：

When should you build an agent? 你应该在什么时候构建 agent？

Building agents requires rethinking how your systems make decisions and handle complexity. Unlike conventional automation, agents are uniquely suited to workflows where traditional deterministic and rule-based approaches fall short. 构建 agent 需要重新思考你的系统如何做出决策并处理复杂性。与传统自动化不同，agent 特别适合那些传统确定性和基于规则的方法难以胜任的工作流。

Consider the example of payment fraud analysis. A traditional rules engine works like a checklist, flagging transactions based on preset criteria. In contrast, an LLM agent functions more like a seasoned investigator, evaluating context, considering subtle patterns, and identifying suspicious activity even when clear-cut rules aren’t violated. This nuanced reasoning capability is exactly what enables agents to manage complex, ambiguous situations effectively. 以支付欺诈分析为例。传统的规则引擎像一份检查清单，根据预设标准标记交易。相比之下，LLM 智能体更像一位经验丰富的调查员，评估上下文、考虑细微模式，并在即使没有违反明确规则的情况下识别可疑活动。这种细微推理能力正是使智能体能够有效管理复杂、模糊情况的关键。

As you evaluate where agents can add value, prioritize workflows that have previously resisted automation, especially where traditional methods encounter friction: 在评估智能体可以在哪些方面增加价值时，优先考虑那些此前一直抗拒自动化的工作流，尤其是传统方法遇到阻力的地方：

Before committing to building an agent, validate that your use case can meet these criteria clearly. Otherwise, a deterministic solution may suffice. 在决定构建智能体之前，请明确验证你的用例能否满足这些标准。否则，确定性解决方案可能就足够了。

Agent design foundations Agent 设计基础

In its most fundamental form, an agent consists of three core components: 在最基本的形式中，一个 Agent 由三个核心组件构成：

Here’s what this looks like in code when using OpenAI’s Agents SDK. You can also implement the same concepts using your preferred library or building directly from scratch. 以下是使用 OpenAI 的 Agents SDK 时这在代码中的样子。你也可以使用你偏好的库或直接从零开始构建来实现相同的概念。

weather_agent = Agent(
    name="Weather agent",
    instructions="You are a helpful agent who can talk to users about the weather.",
    tools=[get_weather],
)

Selecting your models 选择你的模型

Different models have different strengths and tradeoffs related to task complexity, latency, and cost. As we’ll see in the next section on Orchestration, you might want to consider using a variety of models for different tasks in the workflow. 不同的模型在任务复杂度、延迟和成本方面各有优势和权衡。正如我们将在下一节关于编排的内容中看到的，你可能需要考虑在工作流中为不同任务使用多种模型。

Not every task requires the smartest model—a simple retrieval or intent classification task may be handled by a smaller, faster model, while harder tasks like deciding whether to approve a refund may benefit from a more capable model. 并非每项任务都需要最智能的模型——简单的检索或意图分类任务可以由更小、更快的模型处理，而像决定是否批准退款这样的更难任务则可能受益于能力更强的模型。

An approach that works well is to build your agent prototype with the most capable model for every task to establish a performance baseline. From there, try swapping in smaller models to see if they still achieve acceptable results. This way, you don’t prematurely limit the agent’s abilities, and you can diagnose where smaller models succeed or fail. 一个行之有效的方法是，在每个任务上都使用能力最强的模型来构建你的智能体原型，以建立性能基线。在此基础上，尝试换用更小的模型，看看它们是否仍能达到可接受的结果。这样，你就不会过早地限制智能体的能力，并且可以诊断出更小的模型在哪些方面成功或失败。

In summary, the principles for choosing a model are simple: 总之，选择模型的原则很简单：

You can find a comprehensive guide to selecting OpenAI models here. 你可以在这里找到选择 OpenAI 模型的全面指南。

Defining tools 定义工具

Tools extend your agent’s capabilities by using APIs from underlying applications or systems. For legacy systems without APIs, agents can rely on computer-use models to interact directly with those applications and systems through web and application UIs—just as a human would. 工具通过使用底层应用程序或系统的 API 来扩展智能体的能力。对于没有 API 的遗留系统，智能体可以依靠计算机使用模型，像人类一样通过网页和应用程序界面直接与这些应用程序和系统交互。

Each tool should have a standardized definition, enabling flexible, many-to-many relationships between tools and agents. Well-documented, thoroughly tested, and reusable tools improve discoverability, simplify version management, and prevent redundant definitions. 每个工具都应有标准化定义，从而实现工具与智能体之间灵活的多对多关系。文档完善、经过充分测试且可复用的工具能提高可发现性、简化版本管理并防止重复定义。

Broadly speaking, agents need three types of tools: 广义而言，智能体需要三类工具：

For example, here’s how you would equip the agent defined above with a series of tools when using the Agents SDK: 例如，以下是在使用 Agents SDK 时，如何为上面定义的智能体配备一系列工具：

from agents import Agent, WebSearchTool, function_tool
@function_tool 
def save_results(output): 
    db.insert({ : output, : datetime.time()})
    return "File saved"
    
search_agent = Agent(
    name="Search agent",
    instructions="Help the user search the internet and save results if asked.",
    tools=[WebSearchTool(),save_results],
) 

As the number of required tools increases, consider splitting tasks across multiple agents (see Orchestration). 随着所需工具数量的增加，考虑将任务拆分给多个 agent（参见编排）。

Configuring instructions 配置指令

High-quality instructions are essential for any LLM-powered app, but especially critical for agents. Clear instructions reduce ambiguity and improve agent decision-making, resulting in smoother workflow execution and fewer errors. 高质量的指令对于任何由 LLM 驱动的应用都至关重要，但对 agent 来说尤为关键。清晰的指令能减少歧义，提升 agent 的决策能力，从而实现更顺畅的工作流执行和更少的错误。

Best practices for agent instructions agent 指令的最佳实践

You can use advanced models, like o1 or o3-mini, to automatically generate instructions from existing documents. Here’s a sample prompt illustrating this approach: 你可以使用高级模型，如 o1 或 o3-mini，从现有文档中自动生成指令。以下是一个示例提示词，展示了这种方法：

Unset 取消设置

“You are an expert in writing instructions for an LLM agent. Convert the following help center document into a clear set of instructions, written in a numbered list. The document will be a policy followed by an LLM. Ensure that there is no ambiguity, and that the instructions are written as directions for an agent. The help center document to convert is the following {{help_center_doc}}” “你是一位为 LLM 智能体编写指令的专家。将以下帮助中心文档转换为一组清晰的指令，以编号列表的形式编写。该文档将是 LLM 遵循的政策。确保没有歧义，并且指令以面向智能体的指示形式编写。需要转换的帮助中心文档如下：{{help_center_doc}}”

Orchestration 编排

With the foundational components in place, you can consider orchestration patterns to enable your agent to execute workflows effectively. 有了基础组件之后，你可以考虑编排模式，使你的智能体能够有效执行工作流。

While it’s tempting to immediately build a fully autonomous agent with complex architecture, customers typically achieve greater success with an incremental approach. 虽然人们很容易想要立即构建一个具有复杂架构的完全自主智能体，但客户通常通过渐进式方法取得更大的成功。

In general, orchestration patterns fall into two categories: 一般来说，编排模式分为两类：

1. Single-agent systems, where a single model equipped with appropriate tools and instructions executes workflows in a loop 单智能体系统，即单个模型配备适当的工具和指令，在循环中执行工作流
2. Multi-agent systems, where workflow execution is distributed across multiple coordinated agents 多智能体系统，工作流执行分布在多个协同工作的智能体上

Let’s explore each pattern in detail. 让我们详细探讨每种模式。

Single-agent systems 单智能体系统

A single agent can handle many tasks by incrementally adding tools, keeping complexity manageable and simplifying evaluation and maintenance. Each new tool expands its capabilities without prematurely forcing you to orchestrate multiple agents. 单个智能体可以通过逐步添加工具来处理许多任务，保持复杂性可控，并简化评估和维护。每添加一个新工具都能扩展其能力，而不会过早地迫使你去编排多个智能体。

Every orchestration approach needs the concept of a ‘run’, typically implemented as a loop that lets agents operate until an exit condition is reached. Common exit conditions include tool calls, a certain structured output, errors, or reaching a maximum number of turns. 每种编排方法都需要“运行”的概念，通常实现为一个循环，让 agent 持续运行，直到达到退出条件。常见的退出条件包括工具调用、特定的结构化输出、错误，或达到最大轮次。

For example, in the Agents SDK, agents are started using the method, which loops over the LLM until either: Runner.run() 例如，在 Agents SDK 中，agent 通过该方法启动，它会在 LLM 上循环，直到满足以下任一条件：Runner.run()

1. A final-output tool is invoked, defined by a specific output type 调用最终输出工具，由特定的输出类型定义
2. The model returns a response without any tool calls (e.g., a direct user message) 模型返回一个不包含任何工具调用的响应（例如，直接的用户消息）

Example usage: 示例用法：

Agents.run(agent, [UserMessage("What's the capital of the USA?")]) 

This concept of a while loop is central to the functioning of an agent. In multi-agent systems, as you’ll see next, you can have a sequence of tool calls and handoffs between agents but allow the model to run multiple steps until an exit condition is met. while 循环这一概念对 agent 的运行至关重要。在多 agent 系统中，正如你接下来会看到的，你可以让一系列工具调用和 agent 之间的交接依次进行，但允许模型运行多个步骤，直到满足退出条件。

An effective strategy for managing complexity without switching to a multi-agent framework is to use prompt templates. Rather than maintaining numerous individual prompts for distinct use cases, use a single flexible base prompt that accepts policy variables. This template approach adapts easily to various contexts, significantly simplifying maintenance and evaluation. As new use cases arise, you can update variables rather than rewriting entire workflows. 在不切换到多智能体框架的情况下管理复杂性的一种有效策略是使用提示模板。与其为不同的用例维护大量单独的提示，不如使用一个接受策略变量的灵活基础提示。这种模板方法可以轻松适应各种场景，显著简化维护和评估。当新的用例出现时，你可以更新变量，而不是重写整个工作流。

Unset 取消设置

""" You are a call center agent. You are interacting with {{user_first_name}} who has been a member for {{user_tenure}}. The user’s most common complains are about {{user_complaint_categories}}. Greet the user, thank them for being a loyal customer, and answer any questions the user may have! 你是一名呼叫中心客服。你正在与{{user_first_name}}互动，该用户已成为会员{{user_tenure}}。该用户最常见的投诉是关于{{user_complaint_categories}}。向用户问好，感谢他们成为忠实客户，并回答用户可能提出的任何问题！

When to consider creating multiple agent 何时考虑创建多个智能体

Our general recommendation is to maximize a single agent’s capabilities first. More agents can provide intuitive separation of concepts, but can introduce additional complexity and overhead, so often a single agent with tools is sufficient. 我们的一般建议是首先最大化单个智能体的能力。更多的智能体可以提供直观的概念分离，但会引入额外的复杂性和开销，因此通常一个配备工具的智能体就足够了。

For many complex workflows, splitting up prompts and tools across multiple agents allows for improved performance and scalability. When your agents fail to follow complicated instructions or consistently select incorrect tools, you may need to further divide your system and introduce more distinct agents. 对于许多复杂的工作流程，将提示和工具分散到多个智能体中可以提高性能和可扩展性。当你的智能体无法遵循复杂的指令或持续选择错误的工具时，你可能需要进一步拆分系统并引入更多不同的智能体。

Practical guidelines for splitting agents include: 拆分智能体的实用指南包括：

• Complex logic: When prompts contain many conditional statements (multiple if-then-else branches), and prompt templates get difficult to scale, consider dividing each logical segment across separate agents. 复杂逻辑：当提示词包含大量条件语句（多个 if-then-else 分支），且提示词模板难以扩展时，考虑将每个逻辑段划分到不同的智能体中。
• Tool overload: The issue isn’t solely the number of tools, but their similarity or overlap. Some implementations successfully manage more than 15 well-defined, distinct tools while others struggle with fewer than 10 overlapping tools. Use multiple agents if improving tool clarity by providing descriptive names, clear parameters, and detailed descriptions doesn’t improve performance. 工具过载：问题不仅仅在于工具的数量，还在于它们的相似性或重叠。有些实现成功管理了超过 15 个定义明确、各不相同的工具，而另一些则在不到 10 个重叠工具时就举步维艰。如果通过提供描述性名称、清晰的参数和详细的描述来提升工具清晰度后性能仍未改善，则应使用多个智能体。

Multi-agent systems 多智能体系统

While multi-agent systems can be designed in numerous ways for specific workflows and requirements, our experience with customers highlights two broadly applicable categories: 虽然多 agent 系统可以针对特定工作流和需求以多种方式设计，但我们与客户的实践经验突出了两个广泛适用的类别：

• Manager (agents as tools): A central “manager” agent coordinates multiple specialized agents via tool calls, each handling a specific task or domain. 管理者（agent 即工具）：一个中央“管理者”agent 通过工具调用协调多个专业化 agent，每个 agent 处理特定任务或领域。
• Decentralized (agents handing off to agents): Multiple agents operate as peers, handing off tasks to one another based on their specializations. 去中心化（智能体交接给智能体）：多个智能体作为对等体运行，根据各自的专长相互交接任务。

Multi-agent systems can be modeled as graphs, with agents represented as nodes. In the manager pattern, edges represent tool calls whereas in the decentralized pattern, edges represent handoffs that transfer execution between agents. 多智能体系统可以建模为图，智能体表示为节点。在管理者模式中，边表示工具调用，而在去中心化模式中，边表示在智能体之间转移执行的交接。

Regardless of the orchestration pattern, the same principles apply: keep components flexible, composable, and driven by clear, well-structured prompts. 无论采用何种编排模式，相同的原则都适用：保持组件灵活、可组合，并由清晰、结构良好的提示词驱动。

The manager pattern empowers a central LLM—the “manager”—to orchestrate a network of specialized agents seamlessly through tool calls. Instead of losing context or control, the manager intelligently delegates tasks to the right agent at the right time, effortlessly synthesizing the results into a cohesive interaction. This ensures a smooth, unified user experience, with specialized capabilities always available on-demand. 管理者模式赋予一个中央 LLM——即“管理者”——通过工具调用无缝编排专业化 agent 网络的能力。管理者不会丢失上下文或控制权，而是智能地在正确的时间将任务委派给正确的 agent，轻松地将结果综合为连贯的交互。这确保了流畅、统一的用户体验，专业化能力始终可按需调用。

This pattern is ideal for workflows where you only want one agent to control workflow execution and have access to the user. 这种模式非常适合那些你只希望由一个智能体控制工作流执行并直接与用户交互的工作流。

Manager pattern 管理者模式

from agents import Agent, Runner

 manager_agent = Agent(
    name="manager_agent",
    instructions=(
        "You are a translation agent. You use the tools given to you to translate."
        "If asked for multiple translations, you call the relevant tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="translate_to_spanish",
            tool_description="Translate the user's message to Spanish",
        ),
        french_agent.as_tool(
            tool_name="translate_to_french",
            tool_description="Translate the user's message to French",
        ),
        italian_agent.as_tool(
            tool_name="translate_to_italian",
            tool_description="Translate the user's message to Italian",
        ),
    ]
 )
 
async def main():
     msg = input("Translate 'hello' to Spanish, French and Italian for me!")

     orchestrator_output =  await Runner.run(
        manager_agent,msg)

    message orchestrator_output.new_messages:
        print(f"  - Translation step: {message.content}")

Declarative vs non-declarative graphs 声明式图与非声明式图

Some frameworks are declarative, requiring developers to explicitly define every branch, loop, and conditional in the workflow upfront through graphs consisting of nodes (agents) and edges (deterministic or dynamic handoffs). While beneficial for visual clarity, this approach can quickly become cumbersome and challenging as workflows grow more dynamic and complex, often necessitating the learning of specialized domain-specific languages. 一些框架是声明式的，要求开发者通过由节点（智能体）和边（确定性或动态交接）构成的图，预先明确地定义工作流中的每一个分支、循环和条件。虽然这有利于视觉上的清晰性，但随着工作流变得更加动态和复杂，这种方法很快就会变得繁琐且具有挑战性，往往还需要学习专门的领域特定语言。

In contrast, the Agents SDK adopts a more flexible, code-first approach. Developers can directly express workflow logic using familiar programming constructs without needing to pre-define the entire graph upfront, enabling more dynamic and adaptable agent orchestration. 相比之下，Agents SDK 采用了更灵活的代码优先方法。开发者可以使用熟悉的编程结构直接表达工作流逻辑，而无需预先定义整个图，从而实现更动态、更适应性强的智能体编排。

Decentralized pattern 去中心化模式

In a decentralized pattern, agents can ‘handoff’ workflow execution to one another. Handoffs are a one way transfer that allow an agent to delegate to another agent. In the Agents SDK, a handoff is a type of tool, or function. If an agent calls a handoff function, we immediately start execution on that new agent that was handed off to while also transferring the latest conversation state. 在去中心化模式中，智能体可以将工作流执行“移交”给彼此。移交是一种单向转移，允许一个智能体委托给另一个智能体。在 Agents SDK 中，移交是一种工具或函数。如果一个智能体调用移交函数，我们会立即开始在移交目标的新智能体上执行，同时转移最新的对话状态。

This pattern involves using many agents on equal footing, where one agent can directly hand off control of the workflow to another agent. This is optimal when you don’t need a single agent maintaining central control or synthesis—instead allowing each agent to take over execution and interact with the user as needed. 这种模式涉及在平等基础上使用多个智能体，其中一个智能体可以直接将工作流的控制权移交给另一个智能体。当你不需要单个智能体维持集中控制或综合时，这是最优选择——而是允许每个智能体接管执行并按需与用户交互。

For example, here’s how you’d implement the decentralized pattern using the Agents SDK for a customer service workflow that handles both sales and support: 例如，以下是如何使用 Agents SDK 为同时处理销售和支持的客户服务工作流实现去中心化模式：

# 源码太长见 pdf 文件

This pattern is especially effective for scenarios like conversation triage, or whenever you prefer specialized agents to fully take over certain tasks without the original agent needing to remain involved. Optionally, you can equip the second agent with a handoff back to the original agent, allowing it to transfer control again if necessary. 这种模式对于对话分流等场景特别有效，或者当你希望由专门的智能体完全接管某些任务、而原始智能体无需继续参与时，也非常适用。你还可以选择为第二个智能体配备一个移交回原始智能体的功能，使其在必要时能够再次转移控制权。

Guardrails 护栏

Well-designed guardrails help you manage data privacy risks (for example, preventing system prompt leaks) or reputational risks (for example, enforcing brand aligned model behavior). You can set up guardrails that address risks you’ve already identified for your use case and layer in additional ones as you uncover new vulnerabilities. Guardrails are a critical component of any LLM-based deployment, but should be coupled with robust authentication and authorization protocols, strict access controls, and standard software security measures. 设计良好的护栏有助于你管理数据隐私风险（例如，防止系统提示泄露）或声誉风险（例如，确保模型行为符合品牌规范）。你可以设置护栏来应对已经为你的用例识别出的风险，并在发现新的漏洞时逐步增加更多护栏。护栏是任何基于 LLM 的部署的关键组成部分，但应与稳健的身份验证和授权协议、严格的访问控制以及标准软件安全措施相结合。

Think of guardrails as a layered defense mechanism. While a single one is unlikely to provide sufficient protection, using multiple, specialized guardrails together creates more resilient agents. 将护栏视为一种分层防御机制。虽然单一护栏不太可能提供足够的保护，但将多个专门的护栏结合使用可以创建更具弹性的代理。

In the diagram below, we combine LLM-based guardrails, rules-based guardrails such as regex, and the OpenAI moderation API to vet our user inputs. 在下图中，我们结合了基于 LLM 的护栏、基于规则的护栏（如正则表达式）以及 OpenAI 审核 API 来审查用户输入。

Types of guardrails 护栏类型

Building guardrails 构建护栏

Set up guardrails that address the risks you’ve already identified for your use case and layer in additional ones as you uncover new vulnerabilities. 设置护栏以应对您已为用例识别的风险，并在发现新漏洞时增加更多护栏。

We’ve found the following heuristic to be effective: 我们发现以下启发式方法非常有效：

1. Focus on data privacy and content safety 关注数据隐私和内容安全
2. Add new guardrails based on real-world edge cases and failures you encounter 根据你在实际应用中遇到的边缘情况和失败案例，添加新的防护措施
3. Optimize for both security and user experience, tweaking your guardrails as your agent evolves. 在安全性和用户体验之间进行优化，随着你的智能体不断演进，调整你的防护措施。

For example, here’s how you would set up guardrails when using the Agents SDK: 例如，以下是使用 Agents SDK 时设置护栏的方法：

# 源码太长见 pdf 文件

The Agents SDK treats guardrails as first-class concepts, relying on optimistic execution by default. Under this approach, the primary agent proactively generates outputs while guardrails run concurrently, triggering exceptions if constraints are breached. Agents SDK 将护栏视为一等概念，默认依赖乐观执行。在这种方法下，主智能体主动生成输出，而护栏则并发运行，一旦违反约束便触发异常。

Guardrails can be implemented as functions or agents that enforce policies such as jailbreak prevention, relevance validation, keyword filtering, blocklist enforcement, or safety classification. For example, the agent above processes a math question input optimistically until the math_homework_tripwire guardrail identifies a violation and raises an exception. 护栏可以实现为函数或智能体，用于执行诸如防越狱、相关性验证、关键词过滤、黑名单执行或安全分类等策略。例如，上述智能体乐观地处理数学问题输入，直到 math_homework_tripwire 护栏识别出违规并引发异常。

Plan for human intervention 人工干预计划

Human intervention is a critical safeguard enabling you to improve an agent’s real-world performance without compromising user experience. It’s especially important early in deployment, helping identify failures, uncover edge cases, and establish a robust evaluation cycle. 人工干预是一项关键保障，使你能够在不损害用户体验的情况下提升智能体在真实世界中的表现。它在部署初期尤为重要，有助于识别故障、发现边缘情况并建立稳健的评估循环。

Implementing a human intervention mechanism allows the agent to gracefully transfer control when it can’t complete a task. In customer service, this means escalating the issue to a human agent. For a coding agent, this means handing control back to the user. 实施人工干预机制能让智能体在无法完成任务时优雅地移交控制权。在客户服务中，这意味着将问题升级给人工客服。对于编程智能体，这意味着将控制权交还给用户。

Two primary triggers typically warrant human intervention: 通常有两种主要触发条件需要人工干预：

• Exceeding failure thresholds: Set limits on agent retries or actions. If the agent exceeds these limits (e.g., fails to understand customer intent after multiple attempts), escalate to human intervention. 超出失败阈值：为智能体的重试次数或操作设置限制。如果智能体超出这些限制（例如多次尝试后仍无法理解客户意图），则升级至人工干预。
• High-risk actions: Actions that are sensitive, irreversible, or have high stakes should trigger human oversight until confidence in the agent’s reliability grows. Examples include canceling user orders, authorizing large refunds, or making payments. 高风险操作：敏感、不可逆或高风险的操作应触发人工监督，直到对智能体可靠性的信心增强为止。例如取消用户订单、批准大额退款或进行支付。

Conclusion 结论

Agents mark a new era in workflow automation, where systems can reason through ambiguity, take action across tools, and handle multi-step tasks with a high degree of autonomy. Unlike simpler LLM applications, agents execute workflows end-to-end, making them well-suited for use cases that involve complex decisions, unstructured data, or brittle rule-based systems. Agent 标志着工作流自动化的新时代，系统能够在模糊情境中进行推理、跨工具采取行动，并以高度自主性处理多步骤任务。与更简单的 LLM 应用不同，Agent 能够端到端地执行工作流，因此非常适合涉及复杂决策、非结构化数据或脆弱规则系统的用例。

To build reliable agents, start with strong foundations: pair capable models with well-defined tools and clear, structured instructions. Use orchestration patterns that match your complexity level, starting with a single agent and evolving to multi-agent systems only when needed. Guardrails are critical at every stage, from input filtering and tool use to human-in-the-loop intervention, helping ensure agents operate safely and predictably in production. 要构建可靠的 Agent，首先要打好基础：将能力强的模型与定义明确的工具以及清晰、结构化的指令相结合。使用与你的复杂程度相匹配的编排模式，从单 Agent 开始，仅在需要时演进到多 Agent 系统。护栏在每个阶段都至关重要，从输入过滤和工具使用到人工介入干预，有助于确保 Agent 在生产环境中安全且可预测地运行。

The path to successful deployment isn’t all-or-nothing. Start small, validate with real users, and grow capabilities over time. With the right foundations and an iterative approach, agents can deliver real business value—automating not just tasks, but entire workflows with intelligence and adaptability. 成功部署的路径并非全有或全无。从小处着手，用真实用户进行验证，并随着时间推移逐步扩展能力。有了正确的基础和迭代方法，Agent 可以带来真正的商业价值——不仅自动化任务，还能以智能和适应性自动化整个工作流。

If you’re exploring agents for your organization or preparing for your first deployment, feel free to reach out. Our team can provide the expertise, guidance, and hands-on support to ensure your success. 如果您正在为您的组织探索智能体，或正在为首次部署做准备，欢迎随时联系我们。我们的团队可以提供专业知识、指导以及实操支持，确保您取得成功。

4 - I think “agent” may finally have a widely enough agreed upon definition to be useful jargon now

来源： I think “agent” may finally have a widely enough agreed upon definition to be useful jargon now
日期： 2025 年 9 月 18 日
作者： Simon Willison

作者背景： Simon Willison 是英国程序员、开源开发者，Django Web 框架的联合创建者、Datasette 的作者，如今是 AI/大模型领域最有影响力的独立技术博主之一——被称为"AI 圈里最会做笔记的人"。

我觉得 “agent” 终于有了一个足够被公认、能当行话用的定义

I’ve noticed something interesting over the past few weeks: I’ve started using the term “agent” in conversations where I don’t feel the need to then define it, roll my eyes or wrap it in scare quotes.

过去几周我注意到一件有趣的事：我开始在对话中使用“智能体”这个词，而且不再觉得有必要随后去定义它、翻白眼或给它加上引号。

This is a big piece of personal character development for me!

这对我来说是个人成长的一大步！

Moving forward, when I talk about agents I’m going to use this:

今后，当我谈论智能体时，我将使用这个：

An LLM agent runs tools in a loop to achieve a goal.

LLM agent 在循环中运行工具以实现目标。

I’ve been very hesitant to use the term “agent” for meaningful communication over the last couple of years. It felt to me like the ultimate in buzzword bingo—everyone was talking about agents, but if you quizzed them everyone seemed to hold a different mental model of what they actually were.

过去几年里，我一直非常犹豫是否在严肃交流中使用“agent”这个词。对我来说，它就像是流行语宾果游戏的终极代表——人人都在谈论 agent，但如果你考考他们，每个人似乎都对其实际含义持有不同的心智模型。

I even started collecting definitions in my agent-definitions tag, including crowdsourcing 211 definitions on Twitter and attempting to summarize and group them with Gemini (I got 13 groups, here’s the tool-using LLMS one.)

我甚至开始在自己的 agent-definitions 标签中收集定义，包括在 Twitter 上众包了 211 个定义，并尝试用 Gemini 对它们进行总结和分组（我得到了 13 个组，这里是使用工具的 LLM 那一组。）

Jargon terms are only useful if you can be confident that the people you are talking to share the same definition! If they don’t then communication becomes less effective—you can waste time passionately discussing entirely different concepts.

术语只有在你能确信与你交谈的人共享同一定义时才有用！如果他们不共享，沟通就会变得不那么有效——你可能会浪费时间热烈讨论完全不同的概念。

It turns out this is not a new problem. In 1994’s Intelligent Agents: Theory and Practice Michael Wooldridge wrote:

事实证明，这并不是一个新问题。在 1994 年的《智能体：理论与实践》中，迈克尔·伍尔德里奇写道：

Carl Hewitt recently remarked that the question what is an agent? is embarrassing for the agent-based computing community in just the same way that the question what is intelligence? is embarrassing for the mainstream AI community. The problem is that although the term is widely used, by many people working in closely related areas, it defies attempts to produce a single universally accepted definition.

卡尔·休伊特最近评论说，“什么是Agent？”这个问题让基于 Agent 的计算社区感到尴尬，就像“什么是智能？”这个问题让主流人工智能社区感到尴尬一样。问题在于，尽管这个术语被广泛使用，被许多在密切相关领域工作的人使用，但它无法形成一个被普遍接受的定义。

So long as agents lack a commonly shared definition, using the term reduces rather than increases the clarity of a conversation.

只要智能体缺乏一个共同认可的定义，使用这个术语就会降低而非提高对话的清晰度。

In the AI engineering space I think we may finally have settled on a widely enough accepted definition that we can now have productive conversations about them.

在人工智能工程领域，我认为我们可能终于达成了一个足够广泛接受的定义，以至于我们现在可以就它们进行富有成效的对话了。

循环中使用工具以达成目标

An LLM agent runs tools in a loop to achieve a goal. Let’s break that down.

LLM 智能体在循环中运行工具以达成目标。让我们来拆解一下。

The “tools in a loop” definition has been popular for a while—Anthropic in particular have settled on that one. This is the pattern baked into many LLM APIs as tools or function calls—the LLM is given the ability to request actions to be executed by its harness, and the outcome of those tools is fed back into the model so it can continue to reason through and solve the given problem.

“循环中使用工具”这一定义已经流行了一段时间——尤其是 Anthropic 已经确定了这一说法。这一模式已内置于许多 LLM API 中，表现为工具或函数调用——LLM 被赋予请求其执行框架执行操作的能力，而这些工具的结果会被反馈回模型，使其能够继续推理并解决给定的问题。

“To achieve a goal” reflects that these are not infinite loops—there is a stopping condition.

“以达成目标”反映出这些并非无限循环——存在一个停止条件。

I debated whether to specify “… a goal set by a user”. I decided that’s not a necessary part of this definition: we already have sub-agent patterns where another LLM sets the goal (see Claude Code and Claude Research).

我曾犹豫是否要明确写上“……由用户设定的目标”。我最终决定，这不是这个定义的必要组成部分：我们已经有了由另一个 LLM 设定目标的子代理模式（参见 Claude Code 和 Claude Research）。

There remains an almost unlimited set of alternative definitions: if you talk to people outside of the technical field of building with LLMs you’re still likely to encounter travel agent analogies or employee replacements or excitable use of the word “autonomous”. In those contexts it’s important to clarify the definition they are using in order to have a productive conversation.

仍然存在几乎无穷无尽的替代定义：如果你与 LLM 构建技术领域之外的人交谈，你仍然很可能遇到旅行代理的类比、员工替代的说法，或者对“自主”一词的兴奋使用。在这些语境中，为了进行富有成效的对话，明确他们使用的是哪种定义很重要。

But from now on, if a technical implementer tells me they are building an “agent” I’m going to assume they mean they are wiring up tools to an LLM in order to achieve goals using those tools in a bounded loop.

但从现在起，如果一位技术实现者告诉我他们正在构建一个“代理”，我会假设他们的意思是：他们正在将工具连接到 LLM，以便在一个有界循环中使用这些工具来实现目标。

Some people might insist that agents have a memory. The “tools in a loop” model has a fundamental form of memory baked in: those tool calls are constructed as part of a conversation with the model, and the previous steps in that conversation provide short-term memory that’s essential for achieving the current specified goal.

有些人可能会坚持认为代理必须拥有记忆。“循环中的工具”模型内置了一种基本形式的记忆：这些工具调用是作为与模型对话的一部分构建的，而该对话中之前的步骤提供了短期记忆，这对于实现当前指定的目标至关重要。

If you want long-term memory the most promising way to implement it is with an extra set of tools!

如果你想实现长期记忆，最有前景的方式是通过一组额外的工具来实现！

我最不喜欢的定义是把智能体视为人类的替代品

If you talk to non-technical business folk you may encounter a depressingly common alternative definition: agents as replacements for human staff. This often takes the form of “customer support agents”, but you’ll also see cases where people assume that there should be marketing agents, sales agents, accounting agents and more.

如果你与非技术背景的商业人士交谈，你可能会遇到一个令人沮丧且相当普遍的定义：智能体是人类员工的替代品。这通常表现为“客服智能体”，但你也会看到有人假设应该有营销智能体、销售智能体、会计智能体等等。

If someone surveys Fortune 500s about their “agent strategy” there’s a good chance that’s what is being implied. Good luck getting a clear, distinct answer from them to the question “what is an agent?” though!

如果有人就“智能体战略”对《财富》500 强企业进行调查，那么这很可能就是他们暗示的意思。不过，要想从他们那里得到一个关于“什么是智能体？”这个问题的清晰、明确的答案，那祝你好运！

This category of agent remains science fiction. If your agent strategy is to replace your human staff with some fuzzily defined AI system (most likely a system prompt and a collection of tools under the hood) you’re going to end up sorely disappointed.

这一类智能体仍然属于科幻范畴。如果你的智能体战略是用某种定义模糊的 AI 系统（很可能底层是一个系统提示词和一组工具）来取代你的人类员工，那你最终会大失所望。

That’s because there’s one key feature that remains unique to human staff: accountability. A human can take responsibility for their actions and learn from their mistakes. Putting an AI agent on a performance improvement plan makes no sense at all!

这是因为人类员工仍有一个独有的关键特征：问责能力。人类可以对自己的行为负责，并从错误中吸取教训。给 AI 智能体制定绩效改进计划根本毫无意义！

Amusingly enough, humans also have agency. They can form their own goals and intentions and act autonomously to achieve them—while taking accountability for those decisions. Despite the name, AI agents can do nothing of the sort.

有趣的是，人类也具有能动性。他们能够形成自己的目标和意图，并自主行动以实现这些目标——同时对这些决定承担责任。尽管名为“AI 代理”，但它们根本无法做到这些。

This legendary 1979 IBM training slide says everything we need to know:

这张 1979 年 IBM 的传奇培训幻灯片说明了一切：

OpenAI 需要统一口径

The single biggest source of agent definition confusion I’m aware of is OpenAI themselves.

据我所知，智能体定义混乱的最大单一来源就是 OpenAI 自己。

OpenAI CEO Sam Altman is fond of calling agents “AI systems that can do work for you independently”.

OpenAI 首席执行官 Sam Altman 喜欢将智能体称为“能够独立为你完成工作的 AI 系统”。

Back in July OpenAI launched a product feature called “ChatGPT agent” which is actually a browser automation system—toggle that option on in ChatGPT and it can launch a real web browser and use it to interact with web pages directly.

早在 7 月，OpenAI 推出了一项名为“ChatGPT 智能体”的产品功能，实际上是一个浏览器自动化系统——在 ChatGPT 中开启该选项后，它可以启动一个真实的网页浏览器，并直接用它来与网页交互。

And in March OpenAI launched an Agents SDK with libraries in Python (openai-agents) and JavaScript (@openai/agents). This one is a much closer fit to the “tools in a loop” idea.

而在三月份，OpenAI 推出了 Agents SDK，包含 Python（openai-agents）和 JavaScript（@openai/agents）库。这个更贴近“循环中的工具”这一理念。

It may be too late for OpenAI to unify their definitions at this point. I’m going to ignore their various other definitions and stick with tools in a loop!

到了这个阶段，OpenAI 可能已经来不及统一他们的定义了。我打算忽略他们其他各种定义，坚持“循环中的工具”这个说法！

已经有一个相关的梗

Josh Bickett tweeted this in November 2023:

Josh Bickett 在 2023 年 11 月发了这条推文：

What is an AI agent?

什么是 AI 智能体？

I guess I’ve climbed my way from the left side of that curve to the right.

我想我已经从那条曲线的左侧爬到了右侧。

Posted 18th September 2025 at 7:12 pm · Follow me on Mastodon, Bluesky, Twitter or subscribe to my newsletter

发布于 2025 年 9 月 18 日晚上 7:12 · 在 Mastodon、Bluesky、Twitter 上关注我，或订阅我的新闻通讯