A Practical Guide to Building Agents

• 来源: sources/openai_official/practical-guide-building-agents.md
• URL: https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/
• 作者: OpenAI

概述

OpenAI 面向产品和工程团队的 agent 构建指南。涵盖用例识别、agent 设计基础（model + tools + instructions）、编排模式（单 agent vs 多 agent）、guardrails。

Agent 设计基础

三个核心组件：

1. Model：选择策略——先用最强模型建立基线，再用小模型替换可行的部分
2. Tools：三类——Data（检索）、Action（执行）、Orchestration（agent 作为工具）
3. Instructions：从现有文档生成、分解为小步骤、定义明确操作、捕获边缘场景

编排模式

单 Agent

一个 model + tools + instructions 在循环中运行。通过 prompt templates（变量化基础 prompt）管理复杂度。核心建议：先最大化单个 agent 能力，再考虑多 agent。

多 Agent

两种模式：

• Manager（agent 作为工具）：中央 manager 通过 tool call 调度专业 agent，保持统一上下文
• Decentralized（agent 间 handoff）：peer agent 之间直接移交控制权

选择信号：当单 agent 的复杂条件分支或工具重叠导致性能下降时，拆分为多 agent。

声明式 vs 非声明式

声明式框架（LangGraph 风格）要求预定义分支和条件图；OpenAI Agents SDK 采用 code-first 方式，用编程构造表达工作流逻辑。

Guardrails

分层防御机制：

• Relevance classifier：过滤离题输入
• Safety classifier：检测 jailbreak/prompt injection
• PII filter：防止个人信息泄露
• Moderation：有害内容过滤
• Tool safeguards：按风险等级（低/中/高）给工具分级
• Rules-based：blocklist、长度限制、regex
• Output validation：品牌一致性检查

Agents SDK 将 guardrails 作为一等概念，使用 optimistic execution：agent 正常运行，guardrails 并发检查，违规时触发异常。

Human intervention

两个触发条件：

1. 超过失败阈值（重试上限）
2. 高风险操作（不可逆、高金额、敏感）

与 Anthropic 指南的对比

与 Building Effective Agents 的核心共识：

• 从简单开始，证据驱动升级
• 单 agent 优先
• 工具设计是关键

差异：OpenAI 更强调 guardrails 的工程化和 handoff 机制；Anthropic 更强调 ACI 和 workflow 模式的分类学。

References

• sources/openai_official/practical-guide-building-agents.md