LLM Agents 架构设计实践指南¶

1. 前置了解¶

What is an agent（智能代理）¶

定义：一种基于 LLM 的系统，能够独立执行复杂任务，代替用户完成工作流程。
特点：
- 决策与执行：利用 LLM 管理工作流，自动完成任务或在失败时将控制权交还用户；
- 多工具支持：通过调用外部系统工具（API、数据库等）获取信息或采取操作；
- 安全性保障：在明确的规则下运行，确保行为可控、安全
区别：
- 与普通 LLM 应用相比：：普通的 LLM 应用（如单轮对话、情感分析）不属于 agent，因为它们不能自主管理复杂工作流与
- Workflows（工作流）相比：：Workflows是系统通过预定义的代码路径编排 LLM 和工具，而 Agents 是系统中 LLM 动态指导自身的流程和工具使用，维持对任务完成方式的控制权

When should you build an agent¶

Agent 适用于传统自动化方法无法有效解决的问题，包括：

复杂决策场景：如客户服务中涉及判断和例外处理的任务（例如退款审批）
难以维护的规则系统：如高度复杂的规则集（例如供应商安全审查）
依赖非结构化数据：如需要解析自然语言、文档或与用户互动的任务（例如保险理赔处理）

考虑支付欺诈分析的例子🌰：

传统规则引擎就像一个清单，根据预设标准标记交易

agent 更像一位经验丰富的调查员，评估上下文，考虑可疑模式，即使在未违反明确规则的情况下也能识别

这种细微的推理能力正是使代理能够有效管理复杂、模糊情况的原因。

而我们在判断何时适合构建 agent 的时候应用遵循简单优先原则：

寻找最简单的可能解决方案，只在必要时增加复杂性
agent 通常以牺牲延迟和成本为代价获得更好的任务性能
对于许多应用，优化单个 LLM 调用（配合检索 rag 和上下文 examples）通常就足够了

所以在构建 Agent 前应明确工作流的复杂性和传统方法的局限性，若规则系统足够简单，可优先考虑传统方法。

2. 设计基础及实践指导¶

在构建 Agent 前需要了解其常见的核心组件。

Model 模型¶

作用说明：负责推理与决策的 LLM 模型

模型选择：

根据任务复杂性、延迟和成本选择模型
建议先使用最强的模型建立基准性能
- 然后尝试替换为更小的模型以优化成本
原则：先保证准确性，再优化性能与成本

Tools 工具¶

作用说明：外部系统/函数接口，Agent 用以执行任务或获取信息

工具类型

Data 数据工具：允许 agent 检索执行工作流所需的上下文和信息
- 如查询数据库、读取文档、搜索 We
Action 操作工具：使 agent 能够与系统交互以执行操作
- 如更新数据库、发送消息、提交工单等
Orchestration 编排工具：其他 Agent 可以作为工具被调用，实现协作
- 如 Refund agent、Research agent

最佳实践——工具格式

给模型足够的token进行"思考"，避免其陷入困境
保持格式接近模型在互联网文本中自然出现的内容
确保没有格式"开销"，如需要保持准确计数成千上万行代码，或对其写的代码进行字符串转义

最佳实践——ACI（代理-计算机接口）

经验法则：考虑 HCI（人机界面）投入多少精力，并计划在创建 ACI 上投入同样多的精力：

站在模型的角度思考：根据描述和参数，使用这个工具是否明显，或者您需要仔细思考？
- 如果是那么模型可能也一样
- 良好的工具定义通常包括使用示例、边缘情况、输入格式要求和与其他工具的清晰界限
如何更改参数名称或描述使事情更明显？ 将此视为为团队中初级开发人员编写出色的文档字符串
测试模型如何使用您的工具：在工作台中运行许多示例输入查看模型犯什么错误，并进行迭代
防错设计您的工具：更改参数使其更难出错

Instructions 指令¶

作用说明：明确行为准则与流程规范，指导 Agent 如何执行任务

指令配置

高质量的指令是 Agent 成功的关键
要求清晰、具体，减少歧义，并考虑边界情况
- 如用户提供信息不完整时的处理逻辑

最佳实践：

利用现有文档：使用现有操作程序、支持脚本或文档创建 LLM 友好的例程

例程即预先定义步骤序列或指导方针，告诉 agent在特定情境下应该如何行动。

引导代理分解任务：提供从密集资源中提取的更小、更清晰的步骤有助于最小化歧义，帮助模型更好地遵循指示
定义明确的操作：确保例程中的每一步都对应一个特定操作或输出。明确操作（甚至面向用户的消息措辞）可减少解释错误的空间
捕获边界情况：现实交互经常创造决策点，如用户提供不完整信息或提出意外问题时如何继续。强健的例程应预见常见变化，并包括条件步骤或分支的处理指示，如缺少所需信息时的替代步骤

3. 架构模式¶

Single-agent Systems¶

架构特点：

单一Agent，具备所有必需工具与指令，循环处理任务直至达到终态
简单易维护，适合大多数业务自动化场景

工作流示意：

用户输入Agent
依据 Instructions 及工具链进行推理和操作
达到终止条件后输出结果 |

适用场景：任务流程不复杂，工具数量有限业务逻辑变更较少
优点：结构简单，易于测试与维护架构扩展性强，可逐步增加工具
缺点：工具/逻辑过多时复杂度上升，Prompt难以维护

Why Tools → Guardrails / Hooks？¶

代表 agent 在调用外部工具时，流程会自动经过安全（Guardrails）和扩展处理（Hooks）两道“关卡”，既保证操作安全合规，也方便业务自定义流程与监控。

Text Only

          ┌─────────┐
Input → Agent → Tools
                  │
        ┌─────────┴────────┐
        │                  │
   Guardrails           Hooks
        │                  │
        └─────────┬────────┘
                  │
               Output

术语解释：

Tools（工具）指的是 agent 能调用的外部函数/接口/API，比如数据库查询、发送邮件、调用第三方服务等
Guardrails（护栏）是对 agent 行为和输入/输出的安全规则、限制（如过滤敏感词、检测越权、数据脱敏等）。Guardrails 可以在工具调用前后，对参数、结果进行检查，防止 agent 执行不安全或违规操作
Hooks（钩子）是一种编程“插槽”，允许你在 agent 执行某个环节前后插入自定义逻辑。例如：在工具调用后做日志记录、埋点统计、异常捕捉、流程追踪，或者二次处理 agent 的中间结果 |

执行链说明：

Agent 接收输入，产生决策，决定调用某个 Tool；
调用 Tool 前/后，会经过 Guardrails 检查（比如参数是否合法、是否涉及高风险操作）；- Guardrails 可能阻止、修改或记录此次调用；
Hooks 允许你在工具调用前后插入自定义处理逻辑，比如记录一次 API 调用日志、统计耗时、捕捉异常等；
最后返回输出；

示例场景：Agent 需要调用“发放退款”Tool

Guardrail 检查金额是否超限、用户是否有权限
Hook 记录一次退款尝试日志，如果失败自动通知人工介入

Multi-agent Systems¶

该架构有如下特点：

多个专职 Agent 协同处理复杂流程
支持两种主流模式：Manager Pattern 和 Decentralized Pattern

Manager Pattern（经理-专家模式）¶

中央“经理”Agent 负责任务分解与分发，调用各专职Agent工具
适合需要统一出口、上下文管理的多步骤流程

流程：用户请求 > Manager Agent > 调用各专职Agent > 汇总结果

Decentralized Pattern（去中心化模式）¶

多个 Agent 间可相互“handoff”任务，无固定主控
- handoff（任务交接/转交）指的是： 一个 Agent 在处理任务过程中，根据任务内容或自身职责，将当前任务主动转交给另一个更合适的 Agent，让其继续处理。这类似于现实中客服转接、部门间分工协作。例如，你打客服电话时，初步筛查后发现你的问题属于技术故障，就会把你转接到技术支持专员
适合对话分流、任务分派等场景

流程：初始Agent接收请求，判断后 handoff 给对应专职 Agent，必要时可回传

如何理解 handoff¶

简单来说可概括为：

handoff = Agent 之间的任务自动转交
让系统变得像“分布式团队”一样，各司其职，高效协作
提升了复杂多领域场景下的灵活性与可维护性 |

业务流程举例说明：

假设有如下 Agent 分工：

triage_agent：初步分流
technical_support_agent：技术支持
sales_assistant_agent：销售咨询
order_management_agent：订单相关

用户进入：“我的订单什么时候发货？”

triage_agent 接收到输入，判断属于“订单相关”；
triage_agent 调用 handoff，将任务转交给order_management_agent
order_management_agent 继续与用户沟通并解决订单问题 |

handoff 的意义：

解耦：每个 Agent 只需专注本职领域，降低系统复杂度
灵活分流：可动态、自动将任务转给最合适的 Agent，提升自动化和用户体验
支持多轮、多场景协作：任务可以在多个 Agent 之间多次流转，适应复杂业务流程

如何实现 handoff¶

而在 Decentralized Pattern 中通常实现 handoff 的处理：

多个 Agent 平级，每个 Agent 负责不同领域（如：销售、客服、技术支持等）
当某个 Agent 识别到当前任务属于另一个 Agent 更擅长的领域时，就会调用 handoff，把对话和上下文转交给目标 Agent
转交后，由新 Agent 继续和用户互动，原 Agent 不再介入

具体地，我们可以通过在 OpenAI Agents SDK 里的体现来帮助理解

handoff 通常实现为一种特殊的“工具”或“函数”
当 Agent 判断需要转交时，调用该 handoff 函数，系统自动将当前对话上下文传递给目标 Agent 并切换处理权

Python

# triage_agent 识别到用户咨询订单，调用 handoff
triage_agent.handoff(order_management_agent)
# order_management_agent 接管后续对话

Pattern 对比¶

模式	handoff 机制	控制权	典型场景
Manager Pattern	Manager 统一调度	集中在 Manager	统一输出/上下文
Decentralized	Agent 间互交	分散在各 Agent	分流/多领域协同

4. 架构模式对比¶

模式	控制权	协作方式	适用场景
Single-agent	单一 Agent	循环执行	简单流程
Manager Pattern	经理 Agent	调用子 Agent	需统一上下文/输出
Decentralized	无中心	Agent 间 handoff	多分支、灵活分流

5. 架构设计实践建议¶

架构选型建议¶

选型情景	推荐模式
任务简单/流程单一	Single-agent
工具/逻辑复杂、分工明确	Multi-agent
需统一上下文与输出	Manager Pattern
需灵活分流/分派	Decentralized

拆分多 Agent 的实践触发点¶

逻辑分支复杂（多if-then-else）
工具数量多且功能重叠，Prompt难维护
各子流程可独立运行、复用

Guardrails（安全与合规护栏）¶

类型示例： 相关性判别、安全检测、PII过滤、输出校验、工具风险评级
建议： 采用多层护栏组合，结合人类兜底机制

6. 总结¶

Agent 架构是提升复杂业务自动化的关键
推荐从单 Agent 起步，逐步演进到多Agent协作
明确工具、指令和护栏，持续优化，保证安全与效果

参考¶

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