Agent 构建 实战指南

一、什么是 Agent

Agent 是能够独立替你完成任务的系统。

工作流（workflow）是为达成用户目标而需执行的一系列步骤，例如处理客服问题、预订餐厅、提交代码变更或生成报告。仅集成 LLM 但不用它控制工作流执行的应用（简单聊天机器人、单轮 LLM、情感分类器）不属于 Agent。

Agent 的核心特征：

1. 用 LLM 管理工作流执行与决策——能识别工作流何时完成，必要时主动纠错；失败时可暂停并交还控制权给用户。
2. 可访问各类工具——与外部系统交互以获取上下文或采取行动，根据当前状态动态选择工具，始终在明确的护栏内运行。

二、何时该构建 Agent

传统规则引擎像清单，按预设条件标记；LLM Agent 像资深调查员，能评估上下文、识别规则未覆盖的可疑模式。Agent 适合传统确定性方案失效的场景，优先考虑以下曾难以自动化的工作流：

• 复杂决策：需细腻判断、例外处理或上下文敏感的决策，如客服退款审批。
• 难维护的规则：规则集过于庞杂、更新成本高且易出错，如供应商安全审查。
• 重度依赖非结构化数据：需解读自然语言、从文档提取含义或对话式交互，如家庭保险理赔处理。

构建前务必验证用例是否清晰满足上述条件，否则确定性方案即可。

三、Agent 设计基础

Agent 由三个核心组件构成：模型、工具、指令。

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

1. 选择模型

不同模型在任务复杂度、延迟、成本上各有取舍，工作流中不同任务可选用不同模型。简单检索或意图分类可用更小更快的模型，退款审批等难任务则用更强模型。

推荐做法：

• 先用最强模型搭原型建性能基线；
• 再尝试换小模型看是否仍达标，从而定位小模型的成败边界。

原则总结：

1. 建立 evals 设性能基线；
2. 用最强模型达成准确率目标；
3. 在可能处用小模型优化成本与延迟。

2. 定义工具

工具通过底层应用或系统的 API 扩展 Agent 能力。无 API 的遗留系统可用计算机使用模型，像人一样直接操作 UI。每个工具应有标准化定义，便于工具与 Agent 间灵活多对多关系；文档完善、充分测试、可复用的工具能提升可发现性、简化版本管理、避免重复定义。

三类工具：

from agents import Agent, WebSearchTool, function_toolimport datetime@function_tooldef save_results(output):db.insert({"output": output,"timestamp": datetime.datetime.now(),})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],)

3. 配置指令

高质量指令对 Agent 至关重要，能减少歧义、改善决策、让工作流更顺畅。

最佳实践：

• 复用现有文档：把操作流程、支持话术、政策文档转化为 LLM 友好的 routine。客服场景下 routine 大致对应知识库中的单篇文章。
• 引导拆解任务：把密集资源拆成更小更清晰的步骤，减少歧义。
• 明确动作：每一步对应具体动作或输出（如让用户提供订单号、调 API 取账户详情），连用户可见消息的措辞都要明确，减少解释误差。
• 覆盖边缘情况：预判常见变体（信息不全、意外提问），用条件步骤或分支处理。

可用 o1/o3-mini 等模型自动从现有文档生成指令：

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

四、编排（Orchestration）

不要一上来就建全自主复杂架构，客户通常用增量方式更易成功。编排分两类：单 Agent 系统、多 Agent 系统。

1. 单 Agent 系统

单 Agent 通过逐步增加工具即可承担许多任务，复杂度可控、评估与维护更简单。每个新工具扩展能力，而非过早引入多 Agent。

任何编排都需要「run」概念——通常是一个循环，让 Agent 运行直到满足退出条件：工具调用、特定结构化输出、错误、或达到最大轮数。

在 Agents SDK 中，Agent 通过 Runner.run 启动，循环直到：

• 调用了定义特定输出类型的 final-output 工具；
• 模型返回不带工具调用的响应（如直接回复用户）。

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

这个 while 循环是 Agent 运行的核心。多 Agent 系统中也允许模型跑多步直到满足退出条件。

管理复杂度的有效策略是提示词模板：用单个灵活基础提示词接受策略变量，而非为各场景维护多个提示词。新场景只需更新变量而非重写整个工作流。

""" You are a call center agent. You are interacting with{{user_first_name}} who has been a member for {{user_tenure}}. The user'smost common complains are about {{user_complaint_categories}}. Greet theuser, thank them for being a loyal customer, and answer any questions theuser may have!

何时考虑拆分多 Agent：先最大化单 Agent 能力。多 Agent 能直观分隔概念，但带来额外复杂度与开销，往往单 Agent + 工具已足够。当 Agent 跟不住复杂指令或持续选错工具时，再拆分。

拆分指引：

• 复杂逻辑：提示词含大量条件分支（if-then-else）、模板难扩展时，按逻辑段拆分。
• 工具过载：问题不在工具数量而在相似/重叠。有人能管理 15+ 个清晰独立的工具，有人不到 10 个重叠工具就失效。若改进命名、参数、描述仍不行，再用多 Agent。

2. 多 Agent 系统

两类常见模式：

• Manager（Agent 作为工具）：中心「manager」Agent 通过工具调用协调多个专门 Agent，每个处理特定任务/领域。
• Decentralized（Agent 间 handoff）：多个 Agent 对等协作，按专长把任务转交给彼此。

多 Agent 系统可建模为图：Manager 模式中边是工具调用，Decentralized 模式中边是 handoff（转交执行权）。无论哪种模式，都应保持组件灵活、可组合、由清晰结构化提示词驱动。

Manager 模式

中心 LLM（manager）通过工具调用编排专门 Agent 网络，按需委派任务并综合结果，提供统一用户体验。适合只需一个 Agent 控制工作流执行并面向用户的场景。

from agents import Agent, Runnermanager_agent = Agent(name="manager_agent",instructions=("You are a translation agent. You use 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)for message in orchestrator_output.new_messages:print(f"- Translation step: {message.content}")

声明式 vs 非声明式图：声明式框架要求预先显式定义每个分支、循环、条件，可视化清晰但随工作流变复杂会变得繁琐、需学 DSL。Agents SDK 采用代码优先方式，直接用熟悉的编程结构表达工作流逻辑，无需预定义整张图，更动态灵活。

Decentralized 模式

Agent 间可相互 handoff 执行权。Handoff 是单向转交，调用 handoff 函数即立即在目标 Agent 上开始执行并传递最新会话状态。适合无需单一 Agent 维持中央控制或综合的场景，让每个 Agent 接管执行并按需与用户交互。

from agents import Agent, Runnertechnical_support_agent = Agent(name="Technical Support Agent",instructions=("You provide expert assistance with resolving technical issues, ""system outages, or product troubleshooting."),tools=[search_knowledge_base],)sales_assistant_agent = Agent(name="Sales Assistant Agent",instructions=("You help enterprise clients browse the product catalog, ""recommend suitable solutions, and facilitate purchase transactions."),tools=[initiate_purchase_order],)order_management_agent = Agent(name="Order Management Agent",instructions=("You assist clients with inquiries regarding order tracking, ""delivery schedules, and processing returns or refunds."),tools=[track_order_status, initiate_refund_process],)triage_agent = Agent(name="Triage Agent",instructions=("You act as the first point of contact, assessing customer queries ""and directing them promptly to the correct specialized agent."),handoffs=[technical_support_agent,sales_assistant_agent,order_management_agent,],)result = await Runner.run(triage_agent,input("Could you please provide an update on the delivery timeline for our recent purchase?"))

初始消息发给 triage_agent，识别到与近期采购相关后 handoff 给 order_management_agent 转交控制权。此模式特别适合会话分流，或希望专门 Agent 完全接管某些任务而原 Agent 无需继续参与。可给第二个 Agent 配置 handoff 回原 Agent，必要时再次转交。

五、护栏（Guardrails）

设计良好的护栏帮助管理数据隐私风险（如防止系统提示泄露）或声誉风险（如强制品牌一致行为）。先针对已识别风险建护栏，发现新漏洞再加层。护栏是任何 LLM 部署的关键组件，但应与强认证授权、严格访问控制、标准软件安全措施配合。

护栏是分层防御——单个护栏通常不足以提供充分保护，多个专门护栏组合才能更坚韧。

1. 护栏类型

• 相关性分类（Relevance classifier）：标记越界查询，确保响应在预期范围内。如「帝国大厦多高」属越界。
• 安全分类（Safety classifier）：检测越狱或提示注入等不安全输入。如试图套出系统指令的消息会被标记为不安全。
• PII 过滤：审查模型输出，避免不必要暴露个人身份信息。
• 内容审核（Moderation）：标记仇恨、骚扰、暴力等有害或不当输入。
• 工具风险分级（Tool safeguards）：按只读/写、可逆性、所需权限、财务影响给每个工具评低/中/高风险，据此触发自动动作——如高风险函数执行前暂停做护栏检查或升级人工。
• 规则防护（Rules-based）：黑名单、输入长度限制、正则过滤等确定性措施，防已知威胁如禁用词或 SQL 注入。
• 输出校验（Output validation）：通过提示工程与内容检查确保响符合品牌价值观，防止损害品牌。

2. 构建护栏

有效经验法则：

1. 聚焦数据隐私与内容安全；
2. 按真实边缘案例与失败新增护栏；
3. 兼顾安全与体验，随 Agent 演进调整护栏。

from agents import (Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered,RunContextWrapper, Runner, TResponseInputItem, input_guardrail,Guardrail, GuardrailTripwireTriggered,)from pydantic import BaseModelclass ChurnDetectionOutput(BaseModel):is_churn_risk: boolreasoning: strchurn_detection_agent = Agent(name="Churn Detection Agent",instructions="Identify if the user message indicates a potential customer churn risk.",output_type=ChurnDetectionOutput,)@input_guardrailasync def churn_detection_tripwire(ctx: RunContextWrapper[None],agent: Agent,input: str | list[TResponseInputItem],) -> GuardrailFunctionOutput:result = await Runner.run(churn_detection_agent, input, context=ctx.context)return GuardrailFunctionOutput(output_info=result.final_output,tripwire_triggered=result.final_output.is_churn_risk,)customer_support_agent = Agent(name="Customer Support Agent",instructions="You are a customer support agent. You help customers with their questions.",input_guardrails=[Guardrail(guardrail_function=churn_detection_tripwire)],)async def main():await Runner.run(customer_support_agent, "Hello!")print("Hello message passed")try:await Runner.run(customer_support_agent, "I think I might cancel my subscription")print("Guardrail didn't trip - this is unexpected")except GuardrailTripwireTriggered:print("Churn detection guardrail tripped")

Agents SDK 把护栏作为一等概念，默认乐观执行：主 Agent 主动产出，护栏并发运行，违规即抛异常。护栏可是函数或 Agent，强制防越狱、相关性校验、关键词过滤、黑名单、安全分类等策略。

3. 人工干预

人工干预是关键保障，尤其部署早期，帮助识别失败、发现边缘案例、建立稳健评估周期。它让 Agent 无法完成任务时优雅转交控制权——客服场景升级给人工，编码场景交回用户。两类常见触发：

• 超失败阈值：限制 Agent 重试或动作次数，超限（如多次未能理解用户意图）即升级人工。
• 高风险动作：敏感、不可逆或高 stakes 动作在 Agent 可靠性建立前应触发人工监督，如取消用户订单、授权大额退款、付款。

六、结论

Agent 标志着工作流自动化的新时代——系统能在歧义中推理、跨工具行动、以高度自主性处理多步任务，适合复杂决策、非结构化数据或脆弱规则系统。

构建可靠 Agent 的要点：

• 打好基础——强模型 + 定义良好的工具 + 清晰结构化指令；
• 编排匹配复杂度——从单 Agent 起步，仅在需要时演进到多 Agent；
• 全程护栏——从输入过滤、工具使用到人工干预，确保安全可预测。

部署路径非全有或全无：从小处起步、用真实用户验证、逐步扩展能力。