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

启动和继续会话

开始工作、跟踪进度并继续对话。

会话会持续保留智能体的配置、对话和已保存的工作成果。您可以在同一会话中发送后续消息,继续之前的工作。

会话与轮次

一个轮次是会话中的一个工作周期。向空闲会话发送消息会启动新轮次。在轮次进行期间发送消息,可以引导智能体调整当前轮次的工作方向。

轮次以异步方式运行。您的应用可以通过事件流跟踪进度,也可以通过 Webhook 接收会话状态变更通知。

使用定时自动化任务可以在未来的指定时间或按固定周期启动工作。自动化任务可以在每次运行时创建新会话,也可以继续现有对话。

开始工作

提供智能体配置和初始 input 来创建会话。将 stream 设为 true,即可在同一请求中接收首轮事件。

配置好 API 密钥和 SDK 后,运行以下示例来创建并执行脚本。脚本的运行环境由 OpenAI 管理。

创建会话并流式接收首轮事件
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

将 session_id 与应用的对话状态一同保存。使用该 ID 可以向这段对话发送后续消息,并获取已保存的工作成果。

如果项目已启用自动审核,您可以在创建符合条件的会话时,将 review 设为 "auto_review",为该会话启用自动审核模式,以自动审核智能体的操作。主任务处于空闲状态且所有输入提交均已处理完毕时,您可以更改此设置。有关审核模式、环境要求和审批行为,请参阅自动审核。

有关可复用的智能体设置,请参阅配置智能体。有关可选环境,请参阅架构。使用 environment.type: "none" 的会话必须提供初始输入。创建会话 API 参考列出了请求字段。

如果会话使用 Files API 附件,检查文件时可能会收到 HTTP 429 响应,错误代码为 files_api_rate_limit_exceeded。有关恢复步骤,请参阅 Files API 速率限制。

输入大小

智能体运行时接受的请求最大为 4 MiB(4,194,304 字节)。请确保 input 和输出模式(agent.text.format.schema)的总大小低于此限制,并为 Agents API 添加的元数据预留一些空间。上传到环境中的文件受单独的文件限制约束。

跟踪进度并处理结果

智能体工作期间,事件会报告输出和变化。请检查轮次是已完成、失败还是已取消。仅凭会话处于空闲状态,无法判断该轮次是否成功。

请留意 agent.session.turn.completed、agent.session.turn.failed 或 agent.session.turn.cancelled 事件。还要检查智能体的输出,因为即使轮次已完成,个别工具调用仍可能失败。

如果会话需要函数结果或环境连接,请获取该会话并检查 required_actions。您的代码必须处理函数调用或连接环境,工作才能继续。

有关事件类型和载荷,请参阅事件与条目。

继续工作或调整方向

向同一会话再发送一条 agent.session.input.message 消息。如果智能体正在工作,这条消息会引导当前轮次的后续工作。如果会话处于空闲状态,这条消息会基于现有对话启动新轮次。

后续消息也受相同的输入大小限制约束。

对已保存智能体的更新仅适用于新会话。要更改此会话后续轮次使用的模型、推理强度或服务层级,请更新会话设置。

使用该对话的会话 ID 发送输入。请先订阅会话的事件流,再发送消息,以便应用接收到轮次开始时的事件。

为每一次逻辑上独立的消息提交创建一个幂等键。发送输入前,将幂等键与消息一同保存。提交消息时,使用已保存的幂等键。

发送后续消息
from uuid import uuid4


# Reuse the same submission key when retrying this message.
def send_message(
    client: OpenAI, session_id: str, text: str, submission_key: str
) -> None:
    client.beta.agents.sessions.events.create(
        session_id,
        idempotency_key=submission_key,
        events=[
            {
                "type": "agent.session.input.message",
                "input": [
                    {
                        "role": "user",
                        "content": [
                            {
                                "type": "input_text",
                                "text": text,
                            }
                        ],
                    }
                ],
            }
        ],
    )


submission_key = str(uuid4())
# Save this key with the message before submitting it.

在 Idempotency-Key 请求头中传递幂等键,自动重试时复用该键。如果应用因超时或响应丢失而重试,请使用相同的幂等键、会话 ID 和消息。每次独立提交都要生成不同的幂等键,即使消息文本完全相同。

有关发送消息并流式接收事件的完整示例,请参阅事件与条目。

获取已保存的工作成果

事件反映实时进度。会话条目记录已保存的消息和工具调用,包括已完成的响应。您可以获取这些条目来展示之前的工作,或在轮次结束后检查结果。

获取会话条目
# Pass your saved session ID to this helper.
def list_items(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)

要检查会话状态和轮次结果,请参阅管理会话。要获取文件,请参阅文件与产物。

事件流不会重放错过的事件。连接断开后,请获取会话及其已保存的条目,以恢复工作成果。有关重新连接的步骤,请参阅恢复已断开的事件流。

取消正在进行的轮次

要让智能体停止工作,请取消当前轮次。取消后,您仍可以访问会话及之前的工作成果。

取消正在进行的轮次
# Pass your saved session ID to this helper.
def cancel_turn(client: OpenAI, session_id: str) -> None:
    client.beta.agents.sessions.events.create(
        session_id, events=[{"type": "agent.session.input.cancel"}]
    )