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

Agents API 快速入门

创建一个智能体,让它在 OpenAI 托管的沙盒中编写并运行脚本。

构建一个编程助手,让它编写并运行 tree.py,然后展示目录树。OpenAI 负责管理智能体、智能体的对话以及它执行任务时使用的沙盒。

准备工作

在您的 OpenAI 平台项目中创建一个应用程序 API 密钥。为该密钥授予 api.agents.read 和 api.agents.write 权限,以便执行会话操作,并授予 api.responses.write 权限,以便进行模型推理。然后将密钥导出为环境变量:

export OPENAI_API_KEY="your-api-key"

请将此密钥保存在智能体的沙盒之外。有关沙盒配置和使用限制,请参阅 OpenAI 托管的沙盒。

请求必须包含 OpenAI-Beta: agents=v1 请求头。OpenAI SDK 会自动添加此请求头。使用 cURL 时,请显式添加。

1. 运行任务

选择一种语言,安装 OpenAI SDK 并运行示例。SDK 示例使用 beta.agents 命名空间。该请求会创建会话、提交任务,并以流式方式返回进度。

安装或更新 Python SDK:

pip install --upgrade openai

将示例保存为 quickstart.py:

创建并运行 tree.py
from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ).with_result_collection() as stream:
        for event in stream:
            print(event.to_json(indent=None), flush=True)
        result = stream.get_final_result()
    print(result.output_text)
    session_id = result.session_id

在终端中运行示例:

python quickstart.py

无需使用沙盒? 如果智能体只需回答问题或调用外部工具,无需运行命令或处理本地文件,请将 environment.type 设为 none。了解详情。

2. 查看任务进度

终端会逐条显示事件。SDK 示例以 JSON 格式输出事件,cURL 则显示原始事件流。运行成功时,智能体会创建并执行 tree.py,然后展示包含该文件的目录树。其他文件和输出取决于沙盒环境。

看到 agent.session.turn.completed 事件后,请检查智能体报告的执行结果。一轮交互已完成,并不代表每次工具调用都成功了。以 turn.failed、turn.cancelled 或 session.failed 结尾的事件表示操作失败或已取消。仅凭 agent.session.idle 事件无法判断任务是否成功。如果事件流提前断开,请先检索会话及其中已保存的条目,再重试。

3. 继续会话

保存事件中的 session_id。使用该 ID 发送后续消息,例如:“请为 tree.py 添加一个设置最大深度的选项,然后运行脚本并展示输出。”请先打开事件流,再发送后续消息,以免错过最早返回的事件。

4. 清理会话

您可以保留会话以执行更多任务,也可以在使用完毕后删除会话。删除前,请先保存所需文件。

将示例中的 sess_123 替换为您保存的会话 ID。

删除会话
# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI


def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)


if __name__ == "__main__":
    result = delete_session(OpenAI(), "sess_123")
    print(result.to_json())

后续步骤