OpenAI Agents SDK 白板拆解：三原语与追踪机制

OpenAI Agents SDK 被官方文档描述为一个“轻量级、易用、抽象极少”的包，是早期实验项目 Swarm 的生产级升级。但很少有一篇文章把它的内部结构讲清楚。本文基于一段白板讲解视频，梳理 SDK 的三类核心原语，并重点拆解此前较少被讨论的追踪（Tracing）机制。

三原语：Agent、编排与护栏

SDK 的文档只列出三个原语，设计上刻意保持精简。

Agent 是配备指令和工具的语言模型，每个 Agent 运行一个内置循环，直到任务完成。这个循环是 SDK 的默认行为，开发者不需要手动编写 while 循环。

Agent 即工具与移交（handoffs） 解决的是多 Agent 协作问题。两种模式有明确分工：把 Agent 当作工具，是让主 Agent 调用另一个 Agent 完成子任务；而移交则是把控制权完全交给另一个 Agent。白板讲解中提到，在移交场景下，一个分流（triage）Agent 会把对话路由给专家 Agent，后者成为当前活跃的 Agent。这种“先分类、再定向”的模式被称为路由（routing）。

护栏（Guardrails） 负责校验 Agent 的输入和输出。当校验不通过时，护栏会触发一个“绊线”（tripwire），直接中止本次运行。这是一个硬性中断机制，而不是软性提示。

原语之外的主要特性

除了三个原语，SDK 还包含人类介入（human in the loop）、会话（Sessions）和追踪（Tracing）。会话是一个持久化的记忆层，用于保存工作上下文；人类介入则提供了在运行过程中引入人工判断的内置方式。而追踪，正是此前系列视频没有覆盖的部分。

Swarm 是 OpenAI 于 2024 年 10 月开源的一个实验性多 Agent 编排框架，以极简的 Python 代码演示“Agent 即工具”和“移交”两种协作范式，旨在帮助开发者快速验证多 Agent 工作流。它不提供持久化、追踪、护栏等生产级能力，官方明确标注为实验性项目。Agents SDK 正是在 Swarm 的核心理念基础上重写而成，增加了内置循环、追踪、护栏、会话等能力，并承诺向后兼容 Swarm 的主要抽象。理解这一传承关系，有助于把握 SDK 为何刻意保持“抽象极少”——它延续了 Swarm 的哲学，只是补齐了生产环境所需的可观测性与控制机制。

追踪默认开启：Trace 与 Span 的嵌套结构

追踪在 SDK 中是默认开启的，这一点值得注意——开发者如果不主动配置，事件就已经在被记录。它记录的内容包括模型生成、工具调用、移交、护栏以及自定义事件。

理解追踪需要区分两个概念。Trace 是一次工作流的端到端操作，代表一个完整的运行过程。Span 是其中一次带起止时间的操作，并且可以指向父 Span，从而形成嵌套结构。

白板上的示例很直观：默认情况下，整个运行被包裹在一个 Trace 中；每次 Agent 运行，会被包裹在一个 Agent Span 中。在 Agent Span 内部，模型调用对应 generation span，工具调用对应 function span，移交对应 handoff span。此外，runner 调用和模型轮次默认也会生成 Span，护栏同样如此——白板图中为了简洁省略了这些。

敏感数据的默认记录风险

讲解中专门提醒了一个安全细节：generation span 和 function span 会存储输入与输出，而这些内容可能包含敏感数据，并且是默认被包含的。这意味着追踪开箱即用的便利性，同时带来了数据暴露的默认面。对于生产环境，这需要在可观测性和数据安全之间做权衡。

OpenTelemetry（OTel） 是云原生计算基金会（CNCF）主导的开源可观测性标准，统一了追踪（traces）、指标（metrics）和日志（logs）的数据模型与采集协议。在 OTel 的语义中，Trace 表示一次分布式请求的完整调用链，由多个 Span 组成；每个 Span 记录一个操作的名字、起止时间、属性（attributes）和事件，并可通过 parent span ID 形成树状嵌套。Agents SDK 的追踪模型直接借鉴了这一套概念，因此其 Trace/Span 结构可以无缝导出到支持 OTel 的后端（如 Jaeger、Zipkin 或商业 APM）。这意味着团队若已有基于 OTel 的观测体系，接入 SDK 追踪时无需重建数据管道，只需配置导出器即可复用现有的存储与查询能力。

PII（个人身份信息） 指可识别特定自然人的数据，如姓名、邮箱、电话号码、身份证号、支付信息等。在 LLM 应用中，用户输入和模型输出极易包含此类信息，而 generation span 与 function span 默认会将其完整记录。一旦追踪数据被导出到第三方观测平台或长期留存，就可能构成合规风险（如违反 GDPR、CCPA 或国内个人信息保护法）。常见的缓解手段包括：在 SDK 配置中关闭敏感字段的记录、使用脱敏处理器对 span 属性做正则替换、或将追踪数据导出到受控的自托管后端。团队应在接入初期就明确数据保留策略与访问控制，而不是等到审计时再补救。

定位与取舍

从设计看，这个 SDK 的取向非常明确：用极少的抽象降低学习成本，把编排能力收敛到 Agent、移交、护栏三个概念上，再用追踪补上可观测性。与追求大而全的 Agent 框架相比，它更像一套约定清晰的基础件。代价是抽象少意味着很多能力需要开发者自行组合，而追踪默认记录敏感数据这一点，也要求团队在接入时就把数据策略想清楚。

对于想理解 Agent 工作流模式的读者，路由只是其中一种；白板讲解提到后续内容会覆盖更多工作流模式，可作为延伸阅读方向。