Agents are applications that plan, call tools, collaborate across specialists, and keep enough state to complete multi-step work. Use the Responses API when one model call plus tools and application-owned logic is enough. Use the Agents SDK when your application owns orchestration, tool execution, approvals, and state.
OpenAI 给"智能体"下的定义很干脆：Agent 是能规划、调用工具、跨专家协作，并保留足够状态以完成多步工作的应用。这里有一条关键的架构分界线——当一次模型调用 + 工具 + 由应用掌控的逻辑就足够时，用 Responses API；当你的应用需要自己掌控编排、工具执行、审批和状态时，用 Agents SDK。
这段话值得反复读：它定义了"什么时候才需要上 Agent 框架"。OpenAI 的潜台词是——不要为了用 Agent 而用 Agent。如果你的任务是一次模型调用就能解决的（哪怕带几个工具函数），Responses API 就够了，更简单、更可控。只有当任务变成"多步、多专家、需要状态和人工审批"时，才值得引入 Agents SDK 这套更重的编排框架。这与 Anthropic"从最简单可行的方案开始"的理念完全一致。
Get your first agent running: start with the Agents SDK quickstart to install the SDK, define one agent, and run it. Once that works, return here to choose the next capability your application needs. Use the GitHub repositories (TypeScript and Python SDKs) for more examples, issues, and language-specific reference.
让第一个 Agent 跑起来：从 Agents SDK 快速开始（Quickstart）入手——安装 SDK、定义一个 Agent、运行它。一旦跑通，再回到这里，按应用需要选择下一个能力。更多示例、issue 和语言特定的参考细节，可查阅 GitHub 上的 TypeScript SDK 和 Python SDK 仓库。
Choose your starting point based on what you want to do. The SDK pages are organized so each capability maps to a concrete need — from defining a single specialist, to choosing models, to the runtime loop, sandboxes, orchestration, guardrails, results, tools, observability, and voice.
根据"你想做什么"来选择起点。SDK 的文档按能力组织，每个能力都对应一个具体需求——从定义单个专家、选模型，到运行时循环、沙箱、编排、护栏、结果、工具、可观测性，再到语音。下面是官方给出的"需求 → 去哪里"对照：
Quickstart — 这是最短的可运行集成路径Agent definitions — 还在塑造单个 Agent 契约时从这里开始Models and providers — 当模型选择、provider 配置或传输策略影响工作流时Running agents — Agent 循环、流式、续跑策略都在这里Sandbox agents — 当 Agent 需要文件、命令、包、快照、挂载或 provider 链接时Orchestration and handoffs — 当需要多个 Agent 且必须决定谁来回复时Guardrails and human review — 当流程在进入风险工作前应阻断或暂停时Results and state — 最终输出、可恢复状态、下一轮接口Using tools 与 Integrations and observabilityIntegrations and observability 与 Evaluate agent workflows — 先用 trace 调试，再做评估循环Voice agents — 用 SDK 的语音管线和实时 Agent 模式这张"能力地图"本身就是一份Agent 工程能力清单。把每一行翻译成"工程问题"，你会得到构建生产级 Agent 必须面对的 11 件事：定义专家 → 选模型 → 运行时循环 → 沙箱隔离 → 多专家编排 → 人工审批护栏 → 状态管理 → 工具集成 → 可观测性 → 评估 → 语音。任何一个缺失都会在生产中暴露问题。尤其注意 Sandbox agents（安全执行不可信代码）和 Guardrails + human review（人工兜底）——这两项是把"能跑的 demo"变成"敢上生产的系统"的关键。
Use the SDK track when your server owns orchestration, tool execution, state, and approvals. That path is the best fit when you want: typed application code in TypeScript or Python; direct control over tools, MCP servers, and runtime behavior; custom storage or server-managed conversation strategies; tight integration with existing product logic or infrastructure.
当你的服务端掌控编排、工具执行、状态和审批时，走 SDK 路线。这条路径最适合以下诉求：① 用 TypeScript 或 Python 写带类型的应用代码；② 对工具、MCP server 和运行时行为有直接控制；③ 需要自定义存储或由服务端管理的对话策略；④ 与现有产品逻辑或基础设施紧密集成。
这四个"最适诉求"其实是 SDK 路线的选型标准。翻译过来就是：你需要把 Agent 嵌进自己的后端、要接自己的数据库和 MCP 服务、要写类型安全的业务代码、要把 Agent 行为和产品逻辑深度耦合。如果你的情况相反（只想快速跑、不在意控制权），那托管方案更省心。本质上是"控制力 vs 便利性"的权衡——和所有框架选型一样。
A typical SDK reading order: start with Quickstart to get one working run on screen. Use Agent definitions and Models and providers to shape one specialist cleanly. Continue to Running agents, Orchestration and handoffs, and Guardrails and human review as the workflow grows more complex. Use Results and state and Integrations and observability when application logic depends on the run object or needs deeper visibility into behavior.
官方推荐的 SDK 阅读顺序如下：① 先从 Quickstart 起步，让一次可运行的 run 出现在屏幕上；② 用 Agent definitions 和 Models and providers 干净地塑造一个专家；③ 随工作流变复杂，继续到 Running agents、Orchestration and handoffs、Guardrails and human review；④ 当应用逻辑依赖 run 对象或需要更深入的行为可见性时，用 Results and state 和 Integrations and observability。
这个阅读顺序就是一条渐进式构建路径，本质上分四步走：跑通 → 塑形 → 扩展复杂度 → 接入工程化。它隐含的工程哲学是"先让它工作，再让它复杂，最后让它可观测可恢复"。其中第④步（results/state + observability）往往被新手跳过，但这恰恰是把 Agent 推向生产的必经之路——没有状态恢复和可观测性，一个长程 Agent 出错就只能从头再来。把它和 Anthropic 的上下文工程（压缩/笔记/子智能体）放一起看，你会得到一个完整的"生产级 Agent 工程全景"。