适合已经会运行 Python 脚本、想第一次使用 OpenAI 托管 Agent 的开发者。完成后，你会通过一次 Session 请求让云端 Agent 在隔离环境创建并运行 hello_agent.py，在事件流中辨认回合完成，并人工核对真实输出。准备 Python 3.10+、OpenAI Platform 项目和 API key、Agents API 可用权限与模型；模型及工具调用产生费用，账户资格和价格以官方页面为准。预计 20–30 分钟。本文核验日期为 2026-09-30，示例输出是预期，不是作者使用读者账号完成的实测。
OpenAI 在 2026 年 9 月 10 日推出 Agents API 公测，可把 Agent 定义、运行环境、任务输入放在一次 Session 创建调用中。它是托管 Codex harness 的 Agents API，不要与本地运行的 Agents SDK 或旧 Assistants API 混为一谈。站内已有进阶教程讨论较多架构能力；本文专注第一次调用和验证。
一、先看清这次创建的是什么
你提交 agent.model、agent.instructions、environment.type 和 input。服务端创建 Session，启动 Agent 的第一个回合；选择 openai_hosted 让 Agent 在托管沙箱中工作。流式响应里有过程事件和终态事件。agent.session.turn.completed 是必要的终态信号，但不能独立证明文件内容或工具执行符合要求；必须再核对报告与产物。
| 组件 | 本例值 | 核对点 |
|---|---|---|
| Agent | 模型与指令 | 项目可用模型、只处理合成任务 |
| Environment | openai_hosted | 文件和命令运行于托管沙箱 |
| Input | 创建并运行 hello_agent.py | 输出应为 HELLO_AGENT_2026 |
| Stream | True | 保存 Session ID，区分完成与失败 |
二、准备项目权限和密钥
在 OpenAI Platform 自己的项目创建应用 API key。官方 Quickstart 要求 Session 操作具有 api.agents.read、api.agents.write，模型推理具有 api.responses.write。只在本地终端或服务端环境变量设置 OPENAI_API_KEY；不要将真实密钥放进 Python、截图、ZIP、Git 仓库或前端网页。SDK 自动处理 Agents API 所需的 OpenAI-Beta: agents=v1 请求头；直接用 cURL 时须显式添加。
- 建立独立目录与虚拟环境：
python -m venv .venv，激活后运行python -m pip install --upgrade openai。 - 下载本文免费包，解压，阅读
使用说明.md。参考.env.example在自己的终端设置环境变量，但不要把真实值写入文件交付。 - 若
gpt-6-astra对你的项目不可用，按实际模型权限设置OPENAI_AGENT_MODEL，不要假设 ChatGPT 订阅包含 API 额度。
三、运行最小 Demo
免费包的 first_agent.py 使用官方 Quickstart 中的 Python SDK 调用形态。核心如下（完整可编辑文件在 ZIP 中）：
from openai import OpenAI
with OpenAI() as client:
with client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra", "instructions": "Write a small script, run it, and report actual output."},
environment={"type": "openai_hosted"},
input="Create hello_agent.py that prints HELLO_AGENT_2026. Run it and report the exact output.",
stream=True,
) as events:
for event in events:
print(event.to_json(indent=None), flush=True)在虚拟环境中运行 python first_agent.py。程序把事件打印到终端，不会把密钥显示出来。任务要求 Agent 创建一个简单文件并运行它。不要把真实客户数据或生产仓库放进第一个练习。下载包中的模型默认值可以用环境变量调整。
四、从事件与输出判断是否成功
- 记录事件中出现的 Session ID。查找
agent.session.turn.completed；如果只看见agent.session.idle，不能判为成功。 - 人工核对 Agent 报告的运行结果，预期出现
HELLO_AGENT_2026。如有产物路径，核对文件名、内容及实际执行证据；回合完成并不等于每个工具都成功。 - 若出现
turn.failed、turn.cancelled或session.failed，记录脱敏错误与 Session ID。流式连接提前断开时，先按官方 Session/Items 文档查询已有结果，再决定是否重试，以免重复调用产生费用。
免费包中的 API参数速查表.csv 可以直接编辑；预期结果与验收.md 提供填写样例，但明确标记为未实测预期。你可将自己实际事件类型、运行结果和费用记在本地验收记录里。
五、常见错误、安全与回滚
| 现象 | 可能原因 | 定位与处理 |
|---|---|---|
| 401 | 未设置或失效的 API key | 检查项目与环境变量，疑似泄露时轮换 |
| 403 | Agents/Responses 权限不足 | 核对项目权限与账户可用性 |
| 模型错误 | 项目无该模型访问权 | 在项目中选可用模型并重试一次 |
| 流断开 | 网络或长任务 | 用 Session ID 查已有状态，避免盲目新建 |
| completed 但输出不符 | 指令或执行失败 | 查事件、报告和文件，记录失败，不宣称通过 |
停止或回滚时先停止调用与任何定时触发，检查用量，撤销疑似泄露的密钥；按需保留脱敏日志与产物，然后按官方会话管理清理。给 Agent 接入外部 MCP、代码库或生产服务时另行配置最小权限、隔离和人工审批。本例没有授予外部写入能力。
六、免费版和付费包如何选择
免费版是一个独立可运行的首次调用练习，包含 Python Demo、参数速查表、说明和预期样例。付费的“OpenAI Agents API 开发完整项目包”面向准备做单项目原型的开发者：提供 CLI、事件终态解析、最小证据日志、五项离线测试、配置模板、部署验收与回滚文档。资料包售价 ¥29.90，OpenAI API 用量另计。它没有企业级 MCP/审批平台、自动下载 Artifact 或真实账号运行保证；要扩展到企业控制面可读站内既有的企业云端 Agent 资料包。
常见问题
Agents API 和 Agents SDK 是同一产品吗？
不是。本文的 Agents API 使用托管 Session 与可选托管沙箱；Agents SDK 是另一种以开发者代码编排 Agent 的路径。
ChatGPT Plus 账号能直接代替 API 额度吗？
本文需要 OpenAI Platform 项目与适用的 API key，账单和权限以该项目为准。
需要自己部署服务器吗？
本例 Agent 运行在 OpenAI 托管沙箱；你的脚本仍在本地终端发起请求和读取事件。
为什么不能只看 turn.completed？
终态代表回合完成，不保证任务中的每个文件和工具都按要求成功。
断线后可以直接重新运行吗？
先按 Session ID 检索已有状态与条目，再决定是否新建任务，以免重复执行和计费。
公测期间 API 会变吗？
可能。发布前和部署前都应再检查官方 Quickstart、SDK 与 API 参考。
下载与来源
免费下载最小 Demo 与参数速查表；购买完整项目包（¥29.90）。官方资料（2026-09-30 核验）：Agents API 发布公告、Agents API Quickstart、Agents API Reference、官方价格页。上面的接口、权限和事件说明来自官方；示例任务、安全边界与验收表是编辑建议，未宣称真实账户运行。
工具选型与提示词资料
适合阅读工具评测、工具推荐、对比测评类文章后继续转化。
0 回复