OpenAI 正式在开发者文档中上线了 Agents API，把 Codex 使用的 agent harness 通过托管 REST API 暴露给应用开发者。开发者不必从零实现会话编排、上下文压缩和恢复，而是通过一个核心端点创建托管会话；应用自身仍然负责工具提供、权限控制和实际执行环境。
这项变化的重点不是多了一个普通的模型调用接口，而是把“如何持续运行一个编码代理”拆成了清晰的职责边界：OpenAI 管理会话生命周期与编排，业务系统决定代理能访问什么、在哪里运行，以及哪些动作需要人工确认。
一个核心端点
文档给出的核心接口是：
POST https://api.openai.com/v1/agents/sessions
Authorization: Bearer $OPENAI_API_KEY
OpenAI-Beta: agents=v1
Content-Type: application/json
最小请求可以这样发送。示例中的字段用于表达会话启动意图；具体请求体字段应以当前开发者文档和账号可用版本为准。
export OPENAI_API_KEY="your-api-key"
curl https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"input": "Inspect the repository and propose a fix for the failing tests."
}'
如果应用要把这个能力接入自己的后端，建议把 API 密钥保留在服务端，并把用户请求转换成受控的 agent 输入，而不是让浏览器直接调用 OpenAI API。一个最小的 Python 调用示例如下：
import os
import requests
endpoint = "https://api.openai.com/v1/agents/sessions"
headers = {
"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}",
"OpenAI-Beta": "agents=v1",
"Content-Type": "application/json",
}
payload = {
"input": "Review the current project and list the smallest safe change needed."
}
response = requests.post(endpoint, headers=headers, json=payload, timeout=60)
response.raise_for_status()
print(response.json())
运行前安装依赖并设置密钥：
python -m pip install requests
export OPENAI_API_KEY="your-api-key"
python call_agent.py
OpenAI 管什么，应用管什么
Agents API 的价值在于职责划分，而不是替应用做完所有基础设施工作。
OpenAI 托管的部分包括：
- 会话状态与生命周期。
- Agent 的编排过程。
- 长上下文场景下的上下文压缩。
- 会话恢复所需的持续上下文。
应用需要负责的部分包括：
- 向 Agent 暴露哪些工具。
- 工具调用对应的权限和审计策略。
- 代码、文件或命令实际运行在哪个环境。
- 沙箱的网络、文件系统、CPU、内存和超时限制。
- 哪些高风险操作必须经过人工确认。
这意味着“托管会话”不等于“托管了你的生产环境”。Agent 可以拥有持续的工作上下文，但它能否读取仓库、运行测试、修改文件，仍然取决于应用提供的工具和执行器。
沙箱边界仍是工程重点
对于 Codex 类工作流，模型输出只是控制面的一部分。真正有风险的是工具执行：读取凭据、访问网络、修改生产配置或运行未经审查的命令，都需要在应用侧建立边界。
可以把执行器设计成一个窄接口，而不是向 Agent 直接暴露完整 shell：
from pathlib import Path
import subprocess
WORKSPACE = Path("/srv/workspace").resolve()
def run_tests() -> dict:
result = subprocess.run(
["pytest", "-q"],
cwd=WORKSPACE,
capture_output=True,
text=True,
timeout=120,
check=False,
)
return {
"exit_code": result.returncode,
"stdout": result.stdout[-12000:],
"stderr": result.stderr[-12000:],
}
这个例子只提供一个固定的测试动作，并设置了工作目录、输出截断和超时。生产实现还应补充容器或虚拟机隔离、只读挂载、网络白名单、资源配额、调用日志和用户确认流程。不要因为会话由 OpenAI 管理，就把宿主机 shell 或云凭据直接交给代理。
适合哪些系统
Agents API 更适合需要持续工作的代理任务，例如代码检查、测试失败分析、仓库变更建议和多轮开发协作。托管上下文可以减少应用自己维护完整会话状态的工作，也让恢复中断任务更容易纳入统一流程。
但它不一定适合所有请求。一次性的分类、摘要或结构化抽取，普通的模型 API 往往更简单；需要严格可重复性的批处理任务，也应该优先考虑显式工作流。Agent 会话带来的便利，通常伴随着更复杂的权限、成本、延迟和观测要求。
落地前检查清单
- 在服务端保存
OPENAI_API_KEY，不要下发到浏览器。 - 明确每个工具允许读取和修改的资源范围。
- 把代码执行放进隔离沙箱，并限制网络、资源和执行时间。
- 为高风险动作增加人工确认，而不是默认自动批准。
- 为会话、工具调用和执行结果建立关联日志。
- 先用只读检查和测试运行验证流程，再开放写入能力。
- 根据任务类型比较托管 Agent 会话与普通模型调用的成本和复杂度。
Agents API 把 Codex harness 的一部分基础能力变成了可调用服务，但系统安全边界仍然在应用手里。更稳妥的采用方式是从窄工具集、隔离执行环境和可审计的恢复流程开始，再逐步扩大代理权限。