OpenAI Agents SDK TS：用小型原语组织工具、交接与追踪

核验日期：2026-07-16。本文依据官方 TypeScript SDK 文档当前能力：Agent、Tools、Runner、Handoffs/agents-as-tools、Guardrails、Sessions、Human-in-the-loop 与 Tracing。具体导出、模型名和配置会变化，编码前核对 Release/API Reference。

OpenAI Agents SDK for TypeScript 提供一组相对小的 Agent 编排原语。Agent 组合 instructions、model、tools、handoffs 等配置；Runner 推进循环；function tool 用 Zod v4 或 JSON Schema 描述输入；sessions 管会话历史；guardrails 和 tracing 提供运行期控制与证据。SDK 减少样板代码，但应用仍拥有身份、授权、幂等、持久业务任务和质量门禁。

最小结构

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

const searchTechnologies = tool({
  name: "search_technologies",
  description: "按关键词查询技术目录，只读取当前租户可见条目",
  parameters: z.object({ query: z.string().min(1).max(100) }),
  execute: async ({ query }) => technologyService.search(query),
});

const agent = new Agent({
  name: "技术目录助手",
  instructions: "依据工具结果回答；事实必须引用来源标识。",
  tools: [searchTechnologies],
});

const result = await run(agent, "比较 Node.js 与 Edge Runtime");
console.log(result.finalOutput);

运行环境需当前 SDK 支持的 Node.js/TypeScript、@openai/agents、Zod v4 和模型凭证；上例是手工集成片段，CI 不执行真实请求。模型由部署配置选择当前已评测且允许的 ID，不把文档示例里的易变模型名写死在领域代码。

Agent 与 Runner 的职责

Agent 配置描述一个角色当前可见的模型、指令、工具、输出类型、handoff 和 guardrail。Runner 保存运行状态，向模型请求下一 turn，执行被允许的工具/交接，直到最终输出或达到运行限制。应用在 Runner 外围设置 deadline、tenant/principal、费用、持久任务和错误映射。

RunContext 适合传入依赖和当前请求上下文，但不要把 secret 暴露给模型消息。工具闭包从服务端 context 取得 principal；模型参数不能指定身份。Run result 包含最终输出及运行项等信息，应用只持久化必要、脱敏且版本化的数据。

Function Tools

SDK tool helper 根据 Zod/JSON Schema 向模型声明参数并在执行路径提供类型。严格 Schema 是第一层；execute 内仍做业务验证与授权。工具异常策略需要明确：哪些转为模型可见的安全错误，哪些终止运行，哪些允许重试。设置 timeout、是否需要 approval、启用条件与 tool guardrails，避免默认行为意外扩大代理权。

工具可按当前身份/状态动态启用，但授权必须在 execute 时再检查，以防 time-of-check/time-of-use。模型可能请求不存在或参数无效的工具；配置相应错误处理时，限制修正次数。并发工具调用要遵守共享资源上限。

Manager、Agents as Tools 与 Handoffs

Manager 模式把专业 Agent 包装成 tools：中心 Agent 保持会话控制，选择并汇总子 Agent 结果，适合统一策略和最终措辞。Handoff 把会话控制移交给另一个 Agent，后续由被交接者继续，适合分诊后由专业角色直接负责。

模式	谁保有控制	优点	风险/成本
单 Agent + tools	一个 Agent	路径简单、证据集中	工具/指令过多会变杂
Agents as tools	Manager	统一输出与策略	上下文复制、额外模型调用
Handoff	被交接 Agent	专业角色直接接管	策略/历史传递和终止更难

不要用“多 Agent”替代普通函数分层。每新增 Agent 都增加 Prompt、模型、trace、评测和安全面。交接输入用 Schema 限制，过滤传递历史时不能丢掉用户约束或安全状态；接收方重新验证当前权限。

Guardrails 的实际范围

Input guardrail 通常围绕初始输入，output guardrail 围绕最终 Agent 输出；handoff 中间内容和工具结果不能假设自动受同一规则覆盖。Function tool guardrails 只作用于 SDK function tools，不自动覆盖所有 hosted/MCP/agent-as-tool 路径。每个边界按官方文档确认并加应用层验证。

并行 input guardrail 可能在 tripwire 触发前已经消耗模型 token，甚至开始其他工作；高风险输入使用阻塞式前置检查，或在应用进入 Runner 前完成确定性策略。Guardrail 模型本身也有误判，安全关键授权不能由另一个 LLM 单独决定。

Sessions 与业务状态

Sessions 帮助在多次 run 间取得/保存对话历史。它不应成为订单、审批或远程任务的唯一数据库。会话消息、业务 task、工具幂等和用户长期记忆分别建模；需要压缩历史时保存摘要来源/版本。多实例生产 session store 需要持久、一致、加密、保留和 tenant 隔离。

并发向同一 session 写入要定义乐观版本或串行队列，避免两次运行互相覆盖。删除用户数据时同时处理 session、trace、评测样本和工具派生数据。

Human-in-the-loop

需要 approval 的工具使 run 暂停，应用向授权用户展示精确工具名、规范化参数、影响、费用和有效期。批准/拒绝绑定当前 run item，恢复时重新检查权限和资源版本。审批等待可能跨进程重启，因此生产要持久化状态，不把一个 Promise 保持数小时。

审批是产品/API 状态：waiting_approval、审批人、决定、时间、理由、参数哈希和恢复结果进入审计。SDK 提供控制流能力，应用决定谁能批、何时过期和如何通知。

Tracing 与敏感数据

SDK tracing 可生成 run、generation、tool、handoff、guardrail 等 span，便于定位轨迹。官方文档说明 server runtime 默认行为、浏览器/测试差异以及敏感数据开关；零数据保留等政策下某些 tracing 能力可能不可用。部署前根据供应商政策、地区与合规验证。

trace 默认不应包含 secret、完整 PII、私有文档或任意工具结果。记录 ID、版本、大小、类别、耗时和哈希；受控样本脱敏并限时。将 SDK trace 与应用 OpenTelemetry trace 通过 request/task id 关联，不把供应商 trace 当唯一审计日志。

离线测试

领域工具先独立单测。Runner 控制流通过 SDK 提供的 model/provider 抽象或薄适配器注入确定性结果；若某版本接口变化，测试端口而非在业务中复制 SDK 内部类型。覆盖最终输出、单/多工具、无效参数、tool error、max turns、handoff、guardrail tripwire、approval pause/resume、cancel 和 trace 脱敏。

真实模型数据集测工具选择/参数、handoff 正确、最终引用、拒绝与成本。SDK 升级、模型切换、工具描述或 guardrail 改动均触发同一套回归。不能只测试 finalOutput，轨迹错误可能偶然得到正确答案却带来高成本或危险调用。

生产封装

将 SDK 放在 application adapter 内：领域层定义 TechnologyAssistantPort 与结构化结果；adapter 构造 Agent/Runner；工具调用已有服务；session/trace 走组织基础设施。这样可替换 SDK/模型，也能用假实现测试 API。不要让 SDK message 类型扩散到数据库和所有控制器。

服务入口限制请求/并发，Runner 有总 deadline/max turns，工具有 bulkhead，写动作审批/幂等，错误映射稳定；部署记录 SDK/model/prompt/tool 版本，canary 后可回滚。浏览器不直接持模型密钥和高权限工具。

何时采用

需要 OpenAI 模型生态、函数工具、交接、护栏、会话、审批和 tracing 的轻量组合时，SDK 能减少自建循环。若流程是固定 DAG/长任务并需要显式 checkpoint、复杂分支与恢复，LangGraph/通用工作流可能更贴合；若重点是 Web 多供应商流式 UI，AI SDK 的接口更直接；简单单次调用保持原生 API。

验收要证明以下内容，不能只看“能聊天”：Agent/Runner 边界、工具二次授权、guardrail 覆盖范围、handoff 状态、session 与业务状态分离、approval 恢复、trace 脱敏以及离线假模型回归。

参考资料

上一节：A2A · 下一节：LangGraph.js

本页目录