OpenAI Agents SDK 怎么用？

官方资料（2026-11-02 核对）：Agents SDK 总览 · Quickstart · Running agents · Orchestration · Guardrails 与审批 · Tracing 与集成

先选对运行方式

Agents SDK 建立在平台 API 之上，但不是“更高级套餐”，也不会自动代替业务授权。想保留 Typed JavaScript/Python 代码、连接现有后端并自行决定存储与审批时选 SDK；只需要一次模型请求时，直接使用 Responses API 往往更简单。

安装 JavaScript 或 Python SDK

# JavaScript / TypeScript
npm install @openai/agents zod

# Python
pip install openai-agents

export OPENAI_API_KEY=sk-...

API Key 只放在服务端环境变量或密钥系统，不要写进浏览器代码、仓库、日志或提示词。先在测试 Project 中运行最小示例，再连接真实业务工具。

最小 JavaScript Agent

import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "Support assistant",
  instructions: "Answer support questions clearly and concisely.",
  model: process.env.OPENAI_MODEL
});

const result = await run(agent, "如何查询订单状态？");
console.log(result.finalOutput);

Agent 定义名称、指令、模型、工具和输出约束；run 启动一次应用级 turn。不要把模型名硬编码为永久默认值：用配置项管理，并在发布时核对当前模型可用性、价格和限制。

Python 的同一流程

import asyncio
import os
from agents import Agent, Runner

agent = Agent(
    name="Support assistant",
    instructions="Answer support questions clearly and concisely.",
    model=os.environ["OPENAI_MODEL"],
)

async def main():
    result = await Runner.run(agent, "如何查询订单状态？")
    print(result.final_output)

asyncio.run(main())

JavaScript 的 result.finalOutput 与 Python 的 result.final_output 命名不同；复制跨语言示例时不要混用属性。

Runner 的 Agent 循环做了什么

1. 把当前输入发送给当前 Agent 的模型。
2. 检查模型输出；如有函数工具调用，就执行已注册工具并继续。
3. 如发生 handoff，切换到指定专家并继续。
4. 如工具需要审批，返回 interruption 和可恢复 state，等待批准或拒绝。
5. 当没有更多工具工作并得到最终回答时，返回 result。

Runner 只是编排器。工具实现仍在你的服务中运行；网络请求、数据库写入、付款、删除和发布都必须在工具边界重新检查身份、资源、参数、幂等和权限。

给 Agent 添加函数工具

import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const getOrder = tool({
  name: "get_order",
  description: "Read one order that belongs to the current user.",
  parameters: z.object({ orderId: z.string() }),
  async execute({ orderId }) {
    return await loadAuthorizedOrder(orderId);
  }
});

const agent = new Agent({
  name: "Order assistant",
  instructions: "Use get_order only for order-status questions.",
  tools: [getOrder]
});

const result = await run(agent, "查询订单 A-123", {
  context: { userId: "user_456" }
});

Schema 负责约束参数形状，不等于授权。execute 仍要根据当前用户验证订单归属，限制返回字段并记录审计。需要托管工具时，可进一步接入 Web Search、File Search 或 Remote MCP；大型工具目录可参考 Tool Search。

多轮状态：四种策略选一种为主

同一会话通常只选一种主要策略。若同时重放本地 history 又使用服务端 continuation，可能重复上下文、增加 Token 或改变行为。审批暂停则保存 result.state 与 interruptions，批准或拒绝后恢复同一个 run。

Handoff 还是 Agent as Tool

先从一个 Agent 开始；只有当分支确实需要不同指令、工具或政策时再拆分。给每个专家窄职责与清晰描述，限制可达路径，并测试错误路由、来回 handoff 和无限循环。

Guardrail、工具校验与人工审批

• Input guardrail：在主模型前阻止不允许的输入。
• Output guardrail：在最终输出离开系统前验证或脱敏。
• Tool guardrail：围绕具体函数工具检查参数与结果。
• Human review：在取消、编辑、Shell、付款、删除、发布或敏感 MCP 动作前暂停。

Agent 级 guardrail 不会自动覆盖所有嵌套工具：输入 guardrail 只在链路第一个 Agent 上运行，输出 guardrail 只在最终输出 Agent 上运行。对每个有副作用的工具，把校验和审批放在实际执行边界，而不是只依赖顶层提示词。

Tracing、日志与评测

正常服务端 SDK 路径中 tracing 默认启用，可记录模型调用、工具调用、handoff、guardrail 和自定义 span。Trace 用于定位工作流行为，不等于完整生产监控；日志需脱敏，并补充以下指标：

• 任务完成率、人工接管率、错误路由率和 guardrail 命中率。
• 每次成功任务的模型 Token、工具调用数、延迟和费用。
• 工具失败、超时、重试、幂等冲突与审批等待时间。
• 固定评测集上的正确性、安全性、引用质量和回归结果。

常见错误与排查

1. 401 / Missing API key：确认服务端进程读取正确 Project 的 OPENAI_API_KEY，不要在前端补发密钥。
2. 工具没有调用：检查名称、描述、参数 Schema、Agent instructions 与测试输入，避免工具职责重叠。
3. 工具执行两次：在写操作使用业务幂等键；网络重试前先查询真实状态。
4. 上下文越来越大：确认只使用一种主要会话策略，限制工具输出并建立归档/压缩策略。
5. handoff 到错误专家：缩窄专家职责，改进 handoffDescription，并加入路由评测。
6. 审批后无法恢复：保存 interruptions 和 result.state，恢复同一个 run，不要重新提交成新的用户请求。
7. Trace 有记录但用户失败：对照真实业务状态、工具结果和最终 UI；模型流程完成不代表外部动作成功。

生产上线检查清单

• 从一个聚焦 Agent 和最小工具集开始，模型与 SDK 版本通过锁文件管理。
• API Key、OAuth Token 与第三方凭据只在服务端保存并可轮换。
• 每个工具都有输入校验、业务授权、幂等、超时、错误语义和审计。
• 敏感副作用会返回 interruption，并可在审批后恢复同一 state。
• 会话状态策略唯一且清楚，删除、保留与用户隔离规则已测试。
• handoff / agent-as-tool 的所有权、最大轮次、失败和循环路径经过评测。
• Tracing、业务监控、费用告警、脱敏和真实任务评测都已启用。
• 发布前验证不同模型、工具故障、拒绝、超时和人工接管路径。

常见问题

本文核对日期为 2026-11-02。Agents SDK、Agents API、模型、工具、会话与 tracing 接口可能变化；上线前请重新读取 SDK 总览、Quickstart、Running agents、Orchestration、Guardrails 与 Integrations 文档。