如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

Agents API

使用托管的 Codex 执行框架构建可持续运行的云端智能体。

您的应用可以通过 OpenAI 托管的 Agents API 访问 Codex 执行框架。

OpenAI 负责会话管理、任务编排、上下文压缩和恢复。您的应用负责提供工具,并为智能体选择执行环境。

智能体可以在沙盒中执行代码、编辑文件、连接 MCP 服务器并生成产物。

有关端点、请求参数和响应字段,请参阅 API 参考。

定价

模型用量按所选模型的 API 费率计费。OpenAI 工具按其标准费率计费,OpenAI 托管的沙盒按标准容器费率计费。

试用示例

您可以尝试以下完整示例:

您还可以探索以下完整应用:

核心概念

Agents API 有四个核心概念:

  • 智能体: 包括智能体可用的模型、指令、工具和 MCP 服务器。
  • 环境: 可选的沙盒或计算机,智能体可以在其中访问文件、加载技能和运行命令。
  • 会话: 可持久保存状态的智能体实例,用于处理任务并响应输入。
  • 事件和条目: 发送给智能体的输入以及会话期间产生的输出。

会话的完整流程

按照快速入门指南,从 OpenAI 托管的沙盒开始:

  1. 创建会话。 您负责配置智能体,OpenAI 负责为其准备环境。
  2. 分配任务。 环境就绪后,用户输入会启动一轮任务处理。
  3. 跟踪进度。 您可以通过流式输出或 webhook 了解智能体何时完成任务或需要输入。
  4. 继续分配任务或提供指导。 您可以向同一会话发送新任务,也可以在当前轮次中引导智能体。

使用 OpenAI 托管的会话时,您的应用负责发送输入和接收事件,OpenAI 负责运行智能体,并为其创建和管理沙盒。有关配置方法和限制,请参阅环境选项。

您的应用启动会话,并接收来自 Agents API 的事件和输出。OpenAI 运行托管的 Codex 执行框架,并为其创建和管理沙盒。

托管执行框架提供的功能

托管的 Codex 执行框架支持以下操作:

  • 在沙盒中运行命令和代码。
  • 应用相关技能和指令。
  • 通过工具或 MCP 连接外部数据源。
  • 在智能体执行任务时对其进行引导。
  • 总结之前的工作,以管理上下文窗口。
  • 将任务拆分为子任务,并委派给子智能体。
  • 从上次停下的位置继续会话。

请查看快速入门的前提条件,了解 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)

有关运行时的比较,请参阅智能体概览。

有关基于 Agents API 构建的 AWS 服务,请参阅 Bedrock Managed Agents。

Agents API 会保留会话状态,因此您可以在后续轮次中继续处理任务,无需重新构建对话上下文。您可以删除不再需要的会话和已发布的产物。 Agents API 目前仅支持美国境内的数据驻留,且不支持零数据保留(ZDR)。即使选择自托管沙盒,Agents API 也不符合 ZDR 的适用条件。有关数据驻留和保留的详细信息,请参阅 OpenAI 平台的数据控制。