OpenAI 新发布的 Agents API 把 Agent 的会话管理、上下文维护、工具调用和沙箱执行能力放进了统一 API。本文使用 Python 从零跑通一个真实示例，让 Agent 自动创建 Python 脚本、执行代码并返回结果，同时说明它与普通模型 API、Agents SDK 的区别。

---

OpenAI 在 2026 年 9 月 10 日把 Agents API 推向 public beta。

这次更新真正值得开发者关注的地方，不是又多了一个“调用大模型”的接口，而是 OpenAI 开始直接提供一整套托管 Agent 运行环境。

以前我们自己做 Agent，经常要处理这些东西：

• 保存上下文
• 管理多轮任务
• 判断什么时候调用工具
• 执行代码
• 保存文件
• 管理任务状态
• 失败后恢复
• 长任务续跑
• Agent 和子 Agent 调度

Agents API 的思路，是把其中相当一部分交给 OpenAI 管理。

官方目前把它定义为基于 Codex harness 的托管 Agent API，可负责 session orchestration、context compaction 和恢复，并支持持久会话、工具、MCP 和沙箱环境。

这篇不讨论概念，我们直接跑一个。

目标很简单：

让 Agent 自己创建一个 Python 文件，然后实际运行它，把结果返回给我们。

这和普通的“让模型给我生成一段 Python 代码”不是一回事。

---

一、Agents API 到底解决了什么问题？

先看传统模型 API。

以前调用模型，大概是：

用户输入
   ↓
模型推理
   ↓
返回文本

哪怕模型生成了：

print("Hello World")

本质上也只是给了你一段文本。

代码到底能不能运行，要由你自己的程序解决。

而 Agent 的典型流程更接近：

用户给出目标
   ↓
Agent 理解任务
   ↓
决定下一步动作
   ↓
创建文件
   ↓
运行命令
   ↓
读取运行结果
   ↓
发现问题继续修改
   ↓
输出最终结果

所以我认为 Agents API 最重要的变化并不是：

AI 更会聊天了。

而是：

API 开始直接管理“任务执行过程”。

官方 API 目前围绕几个核心对象工作：

Agent
Environment
Session
Events / Items

其中 Session 是关键。

一个 Session 可以保存 Agent 的配置、对话以及执行过程中的工作状态，从而让任务跨多轮继续，而不是每调用一次 API 就重新开始。

---

二、开发环境准备

这篇使用 Python。

建议环境：

Python 3.10+
openai 最新版

创建项目：

mkdir openai-agent-demo
cd openai-agent-demo

创建虚拟环境：

python -m venv .venv

Windows：

.venv\Scripts\activate

macOS / Linux：

source .venv/bin/activate

安装最新版 OpenAI SDK：

pip install --upgrade openai

然后配置环境变量。

Windows PowerShell：

$env:OPENAI_API_KEY="你的_API_KEY"

macOS / Linux：

export OPENAI_API_KEY="你的_API_KEY"

不要把 API Key 直接写死在 GitHub 项目的 Python 文件里。

—

三、跑通第一个 Agents API

新建：

agent_demo.py

代码如下：

from openai import OpenAI

client = OpenAI()

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "你是一名 Python 开发助手。"
            "收到编程任务后，请真正创建文件、执行代码并检查运行结果。"
            "如果程序报错，请分析错误并修复。"
        ),
    },
    environment={
        "type": "openai_hosted"
    },
    input=(
        "创建一个 hello.py 文件，"
        "程序运行后输出：Hello from Agents API。"
        "创建完成后实际执行这个 Python 文件，并告诉我执行结果。"
    ),
    stream=True,
) as events:

    for event in events:
        print(event.to_json(indent=None), flush=True)

运行：

python agent_demo.py

这里最值得注意的是：

client.beta.agents.sessions.create()

Agents API 的 Session 创建接口支持在创建会话时同时提交第一条任务，并且当：

stream=True

时可以持续接收 Agent 执行过程中的事件。

官方 Python API Reference 当前确认 beta.agents.sessions.create() 对应：

POST /agents/sessions

可以创建托管 Agent Session，并提交初始输入或者流式返回 Session Events。

---

四、这段代码里真正重要的三个参数

很多人第一次看 Agents API，会把注意力全部放到 model。

实际上我认为下面三个对象更重要。

1. agent

agent={
    "model": "gpt-6-astra",
    "instructions": "..."
}

这里定义 Agent 本身。

你可以把它理解成：

Agent =
模型
+ 指令
+ 工具
+ 行为规则

如果后面接 MCP、Function Tool 或其他工具，也属于 Agent 能力的一部分。

---

2. environment

这里用了：

environment={
    "type": "openai_hosted"
}

这意味着 Agent 使用 OpenAI 托管执行环境。

这一步很关键。

因为如果任务要求：

创建文件
执行 Python
运行 Shell
修改代码
检查运行结果

模型需要一个真正能工作的环境，而不是只生成文本。

这也是普通对话模型和 Coding Agent 最大的区别之一。

OpenAI 当前提供的 Agents API 支持托管环境，同时官方说明也允许连接自己的基础设施或支持的 Sandbox Provider。

---

3. input

input="创建 hello.py，并实际运行"

这里最好不要只写：

帮我写一个 Python 程序

因为 Agent 最擅长的是完成“目标”。

例如：

分析这个项目为什么启动失败，
找到问题以后修改代码，
重新运行测试，
最后总结修改了哪些文件。

这种任务，比：

解释一下这段代码

更适合 Agent。

---

五、为什么用了 stream=True？

Agent 执行任务的时候，过程可能比较长。

例如：

理解需求
↓
检查文件
↓
创建文件
↓
运行命令
↓
发现报错
↓
修改代码
↓
重新运行
↓
完成任务

如果只等最终结果，用户看不到中间发生了什么。

因此可以开启：

stream=True

然后循环读取：

for event in events:
    print(event.to_json(indent=None))

Agents API 的事件流不只是模型输出文字。

目前官方定义的 Session Event 还包括：

Session 创建
Environment 准备
Turn 创建
文本增量输出
命令执行输出
Turn Item 完成
错误事件
Subagent 事件

官方也提供了单独的 Session Events Streaming 接口：

client.beta.agents.sessions.events.stream(...)

用于持续读取某个 Session 的实时事件。

---

六、真实项目里不要直接打印全部 JSON

上面的代码是为了第一次学习 API。

正式项目里：

print(event.to_json())

显然不够友好。

通常需要根据：

event.type

分类处理。

思路类似：

for event in events:

    event_type = getattr(event, "type", "")

    if "output_text_delta" in event_type:
        # 显示 Agent 输出
        pass

    elif "command" in event_type:
        # 显示命令执行状态
        pass

    elif "error" in event_type:
        # 处理错误
        pass

这里我建议第一遍不要急着封装。

先打印完整 Event：

print(event.to_json(indent=2))

观察你实际收到的数据结构。

等确认事件字段以后，再做自己的：

WebSocket 推送
SSE
前端任务进度
数据库日志
任务状态机

这样更稳。

---

七、Session 才是 Agents API 很值得关注的地方

如果只是执行一次：

生成 hello.py

其实还看不出 Agents API 的真正价值。

真正有意思的是：

第一次：

检查这个项目的代码结构，
告诉我有哪些明显的问题。

过一会继续：

刚才你发现的第二个问题，
直接修改代码解决。

然后再发：

现在跑一下测试，
如果失败就继续修。

如果一直使用同一个 Session，Agent 能在之前工作的基础上继续。

这对于下面几种任务非常适合：

代码 Review

Bug 排查

老项目分析

日志分析

自动测试

文档整理

数据分析

多步骤自动化任务

这就是 durable session 的意义。

OpenAI 在发布说明中也明确把“跨轮次继续任务”和长时间运行作为 Agents API 的重点能力之一。

---

八、继续给同一个 Session 发任务

官方现在还提供 Session Event API。

例如已有：

session_id = "..."

可以往这个 Session 继续发消息：

from openai import OpenAI

client = OpenAI()

client.beta.agents.sessions.events.create(
    session_id=session_id,
    events=[
        {
            "type": "agent.session.input.message",
            "input": [
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "input_text",
                            "text": "把刚才的 hello.py 改成循环输出 3 次，然后重新运行。"
                        }
                    ],
                }
            ],
        }
    ],
)

这个接口对应的是：

POST /agents/sessions/{session_id}/events

官方 Python API Reference 已经提供了相同结构的调用方式。

所以你可以把 Session ID 保存到数据库：

用户 ID
↓
任务 ID
↓
Agent Session ID

下次用户回来时继续使用原来的任务上下文。

---

九、Agents API 和 Agents SDK 不要混为一谈

这个地方最近非常容易搞混。

OpenAI 现在至少有：

Responses API
Agents SDK
Agents API

简单理解：

Responses API

更偏底层模型调用。

你自己管理：

模型调用
工具执行
上下文
Agent Loop

---

Agents SDK

它是一个 SDK 层的 Agent 开发框架。

Python 中常见写法是：

from agents import Agent, Runner

例如：

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="你是一个开发助手"
)

result = Runner.run_sync(
    agent,
    "解释一下 Python 装饰器"
)

print(result.final_output)

Agents SDK 当前还提供 Handoff、Function Tool、Session、Tracing、MCP 等能力。

---

Agents API

则更接近：

OpenAI 提供托管的 Agent Runtime。

代码形态是：

client.beta.agents.sessions.create(...)

OpenAI 管理很多 Agent 执行层的问题。

所以这三者不是“新 API 把老 API 完全替代了”。

它们解决的问题层级不同。

---

十、什么项目适合 Agents API？

我认为下面这些任务非常适合：

1. 自动 Bug 排查

用户提交：

项目启动时报错，
请自己检查日志、找到问题、修改代码并运行测试。

Agent 可以连续完成多个步骤。

---

2. GitHub Issue 自动分析

收到 Issue 后：

读取项目
↓
理解 Issue
↓
寻找相关代码
↓
复现问题
↓
给出修改建议

比单次 Prompt 更符合 Agent 的使用方式。

---

3. 文档整理

例如：

读取一批 Markdown
↓
分析结构
↓
找重复内容
↓
重新分类
↓
生成总结

---

4. 数据分析

例如：

读取 CSV
↓
检查字段
↓
写 Python
↓
运行分析
↓
生成结果
↓
发现异常重新计算

---

5. 自动化代码维护

例如：

升级依赖
↓
修改代码
↓
运行测试
↓
处理报错
↓
生成变更说明

这种任务才是真正能体现 Agent 价值的地方。

---

十一、开发时需要注意的几个坑

1. Agents API 目前仍是 Beta

现在是 public beta。

意味着：

接口
字段
默认行为
沙箱能力
SDK 写法

以后都有可能继续调整。

所以生产项目不要把 API 细节写死在大量业务代码里。

建议自己封装一层：

class AgentService:
    pass

以后 API 变化，只改这一层。

---

2. 不要让 Agent 拿到不必要的权限

如果 Agent 只需要读取数据：

不要给写权限。

如果只需要操作某个目录：

不要直接开放全部文件系统。

如果接数据库：

分析场景优先只读账号。

Agent 能执行动作以后，权限设计的重要性会明显高于普通聊天机器人。

---

3. 长任务必须考虑失败

任何 Agent 系统都不能假设：

任务一定成功。

生产环境至少要考虑：

超时
API 错误
模型失败
工具失败
Sandbox 失败
任务中断
权限不足
用户取消

Agents API 提供 Session 状态和错误相关事件，但业务系统本身仍然要做异常处理。

---

4. Agent 不是所有任务都需要

如果只是：

翻译一句话
写标题
改文案
总结一段文字

直接用普通模型 API 往往更简单。

Agent 更适合：

需要连续做多个动作才能完成的任务。

这是我认为判断要不要使用 Agent 最简单的标准。

---

十二、一个简单判断方法

以后遇到需求，可以先问自己：

这个任务是不是：

输入
↓
模型
↓
输出

如果是，Responses API 往往就够了。

如果任务是：

输入目标
↓
分析
↓
查资料
↓
调用工具
↓
修改东西
↓
运行
↓
检查结果
↓
继续修改
↓
完成

这时候 Agent 的价值就开始体现出来了。

---

写在最后

Agents API 值得关注的并不是又多了一个 AI API。

真正重要的是开发方式正在变化。

以前我们思考的是：

怎么调用一个模型？

现在开始变成：

怎么把一个任务交给 Agent，
让它自己连续完成多个步骤？

这会直接影响以后 AI 应用的架构设计。

至少从目前的 Agents API 来看，Session、Sandbox、Tool、MCP、Subagent 这些东西，已经逐渐从“开发者自己搭”变成 AI 平台的基础设施能力。

---