用 OpenAI Agents…

适用于用 Python `openai-agents`/`agents` 包开发 AI 智能体，包括通过 LiteLLM 接入 Azure OpenAI，需要安装、配置模型、运行 Runner、使用工具/交接/会话/流式/追踪及查实时文档的场景。

适用场景

解决思路

1. 安装 SDK：在 uv 项目中运行 `uv add openai-agents`；不在 uv 项目时运行 `pip install openai-agents`。
2. 运行示例前在进程环境中设置 `export OPENAI_API_KEY="sk-..."` 和 `export OPENAI_MODEL="your-verified-model-id"`，并替换占位符。
3. 如果使用 Azure 或其他提供商，阅读 `references/agents.md#other-providers-litellm`；不要在此处硬编码提供商环境变量，因为它们会变化且容易过时。
4. 创建基础 Agent：`import os`、`from agents import Agent, Runner`，然后 `agent = Agent(name="Assistant", instructions="You are a helpful assistant.", model=os.environ["OPENAI_MODEL"])`，并配置已验证的模型 ID。
5. 同步运行：`result = Runner.run_sync(agent, "Tell me a joke")`，再 `print(result.final_output)`。
6. 异步运行：`result = await Runner.run(agent, "Tell me a joke")`。
7. 如果省略 `model=`，会使用已安装 SDK 的默认模型；生产环境必须显式配置，并根据提供商模型目录验证可用 ID。
8. 使用 Basic Agent 模式：通过 instructions 实现简单 Q&A。
9. 使用 Azure/LiteLLM 模式：接入 Azure OpenAI。
10. 使用 AgentOutputSchema 模式：用 Pydantic 做严格 JSON 验证。
11. 使用 Function Tools 模式：通过 `@function_tool` 执行外部动作。
12. 使用 Streaming 模式：通过 `Runner.run_streamed` 实现实时 UI。
13. 使用 Handoffs 模式：让专用智能体之间委派任务。
14. 使用 Agents as Tools 模式：通过 `agent.as_tool` 做编排。
15. 使用 LLM as Judge 模式：做迭代改进循环。
16. 使用 Guardrails 模式：做输入/输出验证。
17. 使用 Sessions 模式：自动保存对话历史。
18. 使用 Multi-Agent Pipeline 模式：构建多步骤工作流。
19. 使用 Sandboxing 模式：用 `SandboxAgent` 在本地/Docker 沙箱中提供文件系统、shell 和技能（beta）。
20. 使用 Tracing 模式：为 runs、tools、handoffs 和 guardrails 生成内置 spans，并接入可插拔 processors。
21. SDK 没有单独的 `Subagent` 类：用 handoffs 或 `agent.as_tool()` 表达委派。
22. 需要模型编写的工具编排时，使用 `ProgrammaticToolCallingTool`，并验证其仅限 Responses 的约束。
23. 在可用时，优先通过 OpenAI Developer Docs MCP server（`openaiDeveloperDocs`）查询实时文档，再依赖静态参考。
24. Codex CLI 设置 MCP：运行 `codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp`。
25. Claude Code 设置 MCP：运行 `claude mcp add --transport http openaiDeveloperDocs https://developers.openai.com/mcp`。
26. Codex 配置 MCP：在 `~/.codex/config.toml` 中添加 `[mcp_servers.openaiDeveloperDocs]` 和 `url = "https://developers.openai.com/mcp"`；VS Code 和 Cursor 使用不同的 JSON schema。
27. 使用 MCP 关键工具：`mcp__openaiDeveloperDocs__search_openai_docs`、`fetch_openai_doc`、`list_api_endpoints`、`get_openapi_spec`。
28. 遵守文档规则：引用获取到的文档；不要猜测字段名、默认值或当前模型 ID——先获取；引用保持在 125 字符以内。
29. MCP 不可用时回退到 `https://developers.openai.com/api/docs/llms.txt`：这是所有 API 文档的纯文本索引，每个条目在 `/api/docs/<slug>.md` 有对应的 `.md` 文件。
30. 按任务读取参考文档：`references/agents.md` 用于选择或连接模型（默认模型注意事项、LiteLLM、原生 Azure 客户端）。
31. 按任务读取参考文档：`references/tools.md` 用于添加 function tools、hosted tools 或 agents-as-tools。
32. 按任务读取参考文档：`references/structured-output.md` 用于输出必须是 Pydantic/dataclass 形状时（`AgentOutputSchema`，strict vs non-strict）。
33. 按任务读取参考文档：`references/streaming.md` 用于流式输出到 UI（事件类型、FastAPI SSE）。
34. 按任务读取参考文档：`references/handoffs.md` 用于一个 agent 委派给另一个 agent（handoff vs `as_tool`、输入过滤器）。
35. 按任务读取参考文档：`references/guardrails.md` 用于验证输入/输出或门控工具调用。
36. 按任务读取参考文档：`references/sessions.md` 用于跨请求持久化对话历史（SQLite、SQLAlchemy、Redis、OpenAI Conversations）。
37. 按任务读取参考文档：`references/patterns.md` 用于多智能体流水线、LLM-as-judge 循环、追踪控制、`max_turns`、并行化。
38. 按任务读取参考文档：`references/sandbox.md` 用于 agent 必须在隔离工作区编辑文件或运行命令时（`SandboxAgent`，beta）。
39. 查阅官方文档：Docs `https://openai.github.io/openai-agents-python/`；Examples `https://github.com/openai/openai-agents-python/tree/main/examples`；Major update `https://openai.com/index/the-next-evolution-of-the-agents-sdk/`；Docs MCP setup `https://developers.openai.com/learn/docs-mcp`；Docs index (llms.txt) `https://developers.openai.com/api/docs/llms.txt`；Current model IDs `https://platform.openai.com/docs/models`。
40. 将离线/快速查找片段用于快速查询；当准确性重要时，对照 MCP 或 docs 验证模型名和 API 签名。

适用边界 · 注意事项

• 不适用于 TypeScript `@openai/agents` SDK；本技能仅针对 Python 的 `openai-agents`/`agents` 包。
• 不要在未先获取实时文档时猜测字段名、默认值或当前模型 ID。
• 不要为 Azure 或其他提供商硬编码提供商环境变量；这些变量会变化且容易过时。