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

事件与条目

接收实时更新并检索已保存的工作记录。

事件反映智能体工作时发生的情况。消息和工具调用会保存为条目,供您日后检索。您可以通过事件实时更新应用,通过条目展示已保存的会话历史。

您的应用通过发送输入事件来提交消息、取消轮次或返回工具结果。智能体则通过事件报告输出和会话变化。有关如何发送输入,请参阅运行和继续会话。

接收事件流

请先订阅事件流,再提交任务,以便应用收到轮次开始时的事件。传入 API 客户端、当前对话的会话 ID 和事件处理函数:

以流式方式接收会话事件
# Pass your saved session ID to this helper.
def stream_session(client: OpenAI, session_id: str, handle_event):
    with client.beta.agents.sessions.events.stream(session_id) as events:
        for event in events:
            handle_event(event)
            match event.type:
                case "agent.session.idle":
                    continue
                case "error":
                    raise RuntimeError(event.error.message)
                case "agent.session.failed" | "agent.session.environment.failed":
                    raise RuntimeError(f"Agent lifecycle failure: {event.type}")
                case "agent.session.turn.failed":
                    if event.turn.subagent_id is None:
                        detail = event.turn.error.message if event.turn.error else ""
                        raise RuntimeError(f"{event.type}: {detail}")
                case "agent.session.turn.cancelled":
                    if event.turn.subagent_id is None:
                        raise RuntimeError("The agent turn was cancelled")
                case "agent.session.turn.completed":
                    if event.turn.subagent_id is None:
                        return
    raise RuntimeError("Stream closed before a turn ended. Retrieve the saved state.")

辅助函数先将每个事件传给您的处理函数,再检查事件是否属于常见类型。收到 agent.session.idle 时,辅助函数会继续接收事件。根智能体的轮次完成时,辅助函数会返回。如果根智能体的轮次失败或被取消、会话或环境发生故障,或收到 error 事件,辅助函数会抛出错误。子智能体的轮次事件不会终止事件流。您的事件处理函数决定如何展示输出,调用方负责处理辅助函数抛出的错误。如果事件流在轮次结束前关闭,辅助函数会抛出错误。请参阅如何恢复断开的事件流。

订阅后发送消息

此版本接收一条消息,并在打开事件流后提交该消息:

发送消息并接收事件流
# Pass your saved session ID and message to this helper.
def send_and_stream(client: OpenAI, session_id: str, text, handle_event):
    with client.beta.agents.sessions.events.stream(session_id) as events:
        client.beta.agents.sessions.events.create(
            session_id,
            events=[
                {
                    "type": "agent.session.input.message",
                    "input": [
                        {
                            "role": "user",
                            "content": [{"type": "input_text", "text": text}],
                        }
                    ],
                }
            ],
        )
        for event in events:
            handle_event(event)
            match event.type:
                case "agent.session.idle":
                    continue
                case "error":
                    raise RuntimeError(event.error.message)
                case "agent.session.failed" | "agent.session.environment.failed":
                    raise RuntimeError(f"Agent lifecycle failure: {event.type}")
                case "agent.session.turn.failed":
                    if event.turn.subagent_id is None:
                        detail = event.turn.error.message if event.turn.error else ""
                        raise RuntimeError(f"{event.type}: {detail}")
                case "agent.session.turn.cancelled":
                    if event.turn.subagent_id is None:
                        raise RuntimeError("The agent turn was cancelled")
                case "agent.session.turn.completed":
                    if event.turn.subagent_id is None:
                        return
    raise RuntimeError("Stream closed before a turn ended. Retrieve the saved state.")

处理更新

根据事件的 type 确定应用应执行的操作:

  • 显示文本: 将 agent.session.turn.output_text.delta 事件中的增量文本追加到对应的内容片段。收到 agent.session.turn.output_text.done 时,用事件中的完整文本替换该片段。有时不会收到增量事件。
  • 跟踪进度: 会话、轮次和条目事件会报告进度。检查是否收到 agent.session.turn.completed、agent.session.turn.failed 或 agent.session.turn.cancelled,以确定轮次的结果。
  • 提供所需输入: 收到 agent.session.requires_action 时,检索会话并检查 required_actions。您的代码可能需要返回函数结果、连接环境,或处理浏览器的源访问请求或登录。

仅凭会话空闲或事件流关闭,无法判定轮次成功。即使轮次已完成,也不能保证每次工具调用都成功。请检查智能体的输出。

使用 item_id、output_index 和 content_index 将文本更新关联到同一内容片段。例如,以下两个简化的事件更新的是同一片段:

{
  "type": "agent.session.turn.output_text.delta",
  "item_id": "msg_789",
  "output_index": 0,
  "content_index": 0,
  "delta": "Acme competes"
}
{
  "type": "agent.session.turn.output_text.done",
  "item_id": "msg_789",
  "output_index": 0,
  "content_index": 0,
  "text": "Acme competes on price and distribution."
}

每个事件都有自己的 event_id。两个事件的 item_id 相同,指向同一个已保存的条目,其中包含消息的内容、状态和阶段。请参阅检索已保存的工作记录。

有关所有事件类型及其字段,请参阅流式事件参考。这些流式事件与 Webhook 不同。要查看子智能体的活动并了解各条命令由哪个智能体执行,请参阅观察任务委派。

获取条目和轮次

使用应用对话状态中的会话 ID 检索已保存的工作记录:

列表端点每次返回一页结果。使用 SDK 的分页辅助函数或 after 游标获取更多结果。单页结果可能未包含某个轮次的全部条目。使用 order: "asc" 可按从早到晚的顺序读取条目。

如何恢复断开的事件流

您可以从已保存的条目中找回错过的输出。请按以下步骤恢复应用视图:

  1. 打开新的事件流,并缓冲收到的事件。
  2. 保持事件流连接,同时检索会话及其已保存的条目。
  3. 以条目 ID 为键,根据这些条目恢复本地状态。
  4. 根据 item_id 应用已缓冲的条目更新。如果检索到的历史记录显示某个条目已达到最终状态,请丢弃该条目的更新。
  5. 继续处理实时事件。

重新连接到失败的会话时,事件流会报告已保存的失败信息,然后关闭。如果检索到的会话为 status: "failed",或您收到 agent.session.failed,请停止重连,并按照会话恢复指南操作。

根据检索到的会话中的 required_actions 恢复等待输入的表单。历史条目无法说明哪些请求仍需响应。对于浏览器审批,请按 request_id 匹配表单,并移除已无需审批的表单。重新连接后,您无需重新发送任务或此前的审批结果。

收到 output_text.done 事件后,可以用事件中的完整文本替换临时缓冲区中的文本。已保存的条目可用于恢复已完成的工作,但无法还原您错过的每一个中间事件。