SDK 概览与快速上手

OpenAI Agents SDK 是 OpenAI 官方推出的 Agent 开发框架，与 Assistants API 互补，更侧重可编程、可扩展的 Agent 构建。通过 Python 或 TypeScript SDK，开发者可以定义工具、配置模型、实现多 Agent 协作与安全护栏。

环境搭建

pip install openai-agents
或
npm install @openai/agents

配置 OPENAI_API_KEY 后，即可创建第一个 Agent：

from openai_agents import Agent
agent = Agent(
    name="assistant",
    model="gpt-4o",
    instructions="你是一个有帮助的助手",
    tools=[search_tool, calculator_tool]
)

工具（Tools）注册

工具是 Agent 与外部世界交互的桥梁。支持两种定义方式：

函数式：直接传入 Python 函数或 JS 函数，SDK 自动生成 OpenAPI schema

Schema 式：手动定义 name、description、parameters（JSON Schema）

工具描述要清晰，便于模型正确选择。建议包含输入示例和典型使用场景。

Handoff（移交）机制

Handoff 用于多 Agent 协作：当当前 Agent 判断任务超出其能力范围时，可将控制权移交给更专业的 Agent。

• 触发方式：在 Agent 的 instructions 中约定，当满足某条件时返回特定格式（如 handoff_to: tech_support）
• 配置：在父级或编排层注册多个 Agent，并定义 handoff 目标映射
• 上下文传递：移交时可携带当前对话历史与中间结果，确保新 Agent 无缝接手

Guardrails（护栏）

Guardrails 在 Agent 输出到达用户前进行校验与修正：

• 输出格式：强制 JSON、Markdown 或特定模板
• 内容过滤：敏感词、PII 脱敏、合规检查
• 长度与结构：限制回复长度、禁止某些类型的输出

实现方式通常为：在 Agent 的 post_process 或中间件中插入校验逻辑，不通过则重试或返回安全兜底回复。

最佳实践

• 工具命名与描述要具体，避免模型误选
• Handoff 时明确传递上下文，减少重复询问
• Guardrails 采用「白名单」思维，明确允许的内容比单纯禁止更可控
• 结合 LangSmith 等工具做 trace 与调试，追踪 Agent 决策路径

小结

OpenAI Agents SDK 通过工具、Handoff 和 Guardrails 三大机制，支持构建安全、可协作的 Agent 应用。掌握这些能力，可快速落地客服、助手、自动化工作流等场景。