OpenAI Agents API

# Agents API | OpenAI API 来源：https://developers.openai.com/api/docs/guides/agents-api/overview Agents API 为您的应用程序提供通过 OpenAI 管理的 API 访问 Codex 运行框架的权限。 OpenAI 负责管理会话、协调、上下文压缩与恢复，而您的应用程序提供工具并选择执行环境。 智能体可在沙箱环境中操作，在其中可执行代码、编辑文件、连接 MCP 服务器并生成产出物。 模型使用费按所选模型的 API 费率计费（https://developers.openai.com/api/docs/pricing）。OpenAI 工具使用标准费率（https://developers.openai.com/api/docs/pricing#built-in-tools），OpenAI 托管的沙箱则采用标准容器费率（https://developers.openai.com/api/docs/pricing#built-in-tools）。 尝试以下完整示例： - 在 OpenAI 托管的沙箱中创建并运行目录树脚本（https://developers.openai.com/api/docs/guides/agents-api/quickstart#1-run-a-task）。 - 使用子智能体比较版本发布说明（https://developers.openai.com/api/docs/guides/agents-api/multi-agent#example-compare-release-notes），并将其发现整合为单一答案。 探索完整应用案例： - 事件响应智能体（https://developers.openai.com/showcase/agents-api-sev-bot）：调查警报并申请批准恢复操作。 - Slack 机器人（https://developers.openai.com/showcase/agents-api-slack-bot）：使用连接的办公工具调查请求。 - 数据分析师（https://developers.openai.com/showcase/agents-api-data-analyst）：使用只读 SQL 回答数据仓库问题。 - GitHub 问题调查员（https://developers.openai.com/showcase/agents-api-github-issues）：重现报告的错误并在 GitHub 上分享发现。 - 文档审核员（https://developers.openai.com/showcase/agents-api-document-review）：使用策略技能和专业智能体审核文档。 Agents API 围绕四个核心概念构建： - **智能体**：模型、指令、工具以及智能体可用的 MCP 服务器。 - **环境**：可选的沙箱或计算机，智能体在其中访问文件、加载技能并执行命令。 - **会话**：智能体的持久化实例，用于处理任务并响应输入。 - **事件与项**：发送到智能体的输入以及会话期间产生的输出。 ### 会话完整流程 从快速入门（https://developers.openai.com/api/docs/guides/agents-api/quickstart）中的 OpenAI 托管沙箱开始： 1. **创建会话**：配置智能体；OpenAI 为其分配环境。 2. **分配任务**：环境就绪后，用户输入启动一轮工作。 3. **跟踪进度**：通过流式输出或 Webhook 了解智能体何时完成或需要输入。 4. **继续或引导**：向同一会话发送新任务，或在当前回合中引导智能体。 对于 OpenAI 托管的会话，您的应用程序发送输入并接收事件，而 OpenAI 运行智能体并配置管理其沙箱。有关设置和限制，请参阅环境选项（https://developers.openai.com/api/docs/guides/agents-api/configuration#environment-settings）。 您的应用程序启动会话并从 Agents API 接收事件和输出。OpenAI 运行托管的 Codex 运行框架并配置管理其沙箱。托管的 Codex 运行框架支持： - 在沙箱中执行命令和代码。 - 应用相关技能和指令。 - 通过工具或 MCP 连接外部数据。 - 在智能体工作时进行引导。 - 总结先前工作以管理上下文窗口。 - 将工作分解为子任务并委派给子智能体。 - 恢复上次中断的会话。 请查看快速入门前提条件（https://developers.openai.com/api/docs/guides/agents-api/quickstart#prerequisites）了解 API 密钥权限和 SDK 设置。创建会话时配置这些功能： ``` from openai import OpenAI client = OpenAI() session = client.beta.agents.sessions.create( agent={ "model": "gpt-6-astra", "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.", "tools": [ {"type": "programmatic_tool_calling"}, { "type": "mcp", "server_label": "openai_docs", "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp", }, }, {"type": "web_search"}, ], "multi_agent": {"enabled": True, "max_concurrent_subagents": 4}, }, environment={ "type": "self_hosted", "workspace_directory": "/workspace", "capability_directories": ["/workspace/capabilities/skills"], }, input=[ { "role": "user", "content": [ { "type": "input_text", "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.", } ], } ], ) print(session.id) ``` 如需运行时对比，请参阅智能体概述（https://developers.openai.com/api/docs/guides/agents#compare-agent-runtimes）。 Agents API 保留会话状态，因此您可以在不重建对话上下文的情况下跨回合继续工作。当不再需要会话和已发布的产出物时，您可以将其删除。Agents API 目前仅支持美国的数据驻留，且不支持零数据留存（ZDR）。选择自托管沙箱并不能使 Agents API 符合 ZDR 资格。有关数据驻留和留存的详细信息，请参阅 OpenAI 平台中的数据控制（https://developers.openai.com/api/docs/guides/your-data#storage-requirements-and-retention-controls-per-endpoint）。