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

会话 webhook

响应智能体生命周期中的状态变化。

使用 webhook 即可响应会话状态变化,无需持续保持事件流连接。webhook 处理程序可以启动或重新连接沙盒计算资源、更新您的应用或触发工作流。

支持的事件

事件 触发时机
agent.session.created 会话创建时。
agent.session.action_required 会话需要函数调用结果、环境连接或计算机使用审批时。
agent.session.in_progress 会话开始处理一轮交互时。
agent.session.idle 会话进入空闲状态,可以接收更多输入时。
agent.session.failed 会话进入失败状态时。

agent.session.action_required 事件包含会话 ID 和 required_action.type 字段。该字段的值为 function_call、environment_connection 或 computer_use_approval_request。

{
  "type": "agent.session.action_required",
  "data": {
    "id": "sess_abc123",
    "required_action": { "type": "function_call" }
  }
}

获取会话并查看 required_actions,从中读取调用 ID、参数、环境 ID 或计算机使用审批详情。webhook 不包含这些信息。对于计算机使用,嵌套字段 request.type 表明请求涉及浏览器来源访问还是身份验证。向用户展示当前请求,然后通过会话事件端点返回用户的答复。有关请求和响应的数据结构,请参阅计算机使用。

设置 webhook

按照通用的 webhook 设置指南创建端点,并选择 Agents API 事件。保存端点的签名密钥,用于验证签名。

接收事件

每当您订阅的事件发生时,OpenAI 都会发送带签名的 HTTP POST 请求:

{
  "id": "evt_123",
  "object": "event",
  "created_at": 1750287018,
  "type": "agent.session.created",
  "data": {
    "id": "sess_abc123",
    "environment_id": "ccarenv_abc123",
    "environment_type": "self_hosted",
    "connect": {
      "remote_url": "https://api.openai.com/v1/agents/api"
    }
  }
}

在为会话分配沙盒之前,先获取会话的当前状态。请参阅沙盒生命周期。

启动执行器

对于自托管会话,agent.session.created 包含启动执行器所需的环境 ID 和连接 URL。将 ENVIRONMENT_ID 设为 data.environment_id 的值,将 REMOTE_URL 设为 data.connect.remote_url 的值。该 URL 与会话的 environment.remote_url 字段返回的 URL 相同。保存这两个值,以便重新连接时使用:

CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
  --remote "$REMOTE_URL" \
  --environment-id "$ENVIRONMENT_ID"

使用环境密钥作为 CODEX_API_KEY。请将应用的 API 密钥保存在该环境之外。

验证并处理事件

设置 OPENAI_API_KEY 和 OPENAI_WEBHOOK_SECRET。如果使用 Python,请安装 fastapi、uvicorn 和 openai。如果使用 JavaScript,请安装 express 和 openai。

这些处理程序会验证签名,并监听 8000 端口。您可以设置 PORT 来更改端口。在生产环境中,请将耗时较长的任务放入队列。

Webhook 处理程序
import json
import os

import uvicorn
from fastapi import FastAPI, Request, Response
from openai import AsyncOpenAI, InvalidWebhookSignatureError

app = FastAPI()
webhooks = AsyncOpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])


@app.post("/webhooks/openai")
async def handle_webhook(request: Request):
    payload = await request.body()
    try:
        webhooks.webhooks.verify_signature(payload=payload, headers=request.headers)
    except (InvalidWebhookSignatureError, ValueError):
        return Response("Invalid signature", status_code=400)

    event = json.loads(payload)
    if event["type"] == "agent.session.idle":
        session_id = event["data"]["id"]
        session = await webhooks.beta.agents.sessions.retrieve(session_id, timeout=10)
        print("session idle event:", session.id)
    else:
        print("session event:", event["type"], event["data"]["id"])
    return Response(status_code=200)


if __name__ == "__main__":
    uvicorn.run(app, port=int(os.environ.get("PORT", "8000")))

环境连接事件

如果处理初始输入或后续输入需要用到当前未连接的自托管执行器,API 会添加一项类型为 environment_connection 的必需操作。API 会发出 agent.session.action_required 事件,然后才开始等待连接。

获取会话,确认 required_actions 仍要求建立连接。使用 session.environment.id 和 session.environment.remote_url 启动执行器。此 webhook 不包含 connect.remote_url。如果执行器在等待超时前建立连接,API 会清除这项必需操作,继续处理已提交的输入,无需客户端重新提交。

API 最多等待五分钟。在此期间,后续输入请求可能会一直保持打开状态。请据此配置客户端和代理的超时时间。agent.session.in_progress 表示执行已经开始,并不表示 API 正在等待连接。

如果等待超时,本次提交就会失败。初始输入可能会异步失败,使会话处于 failed 状态。等待连接的机制不提供持久化输入队列。如果进程崩溃或客户端断开连接,可能需要重试。

会话和交互轮次的结果

agent.session.idle 表示会话可以接收更多输入,但不能据此判断上一轮交互是否成功。请检查该轮交互的状态,或在会话事件流中观察 agent.session.turn.completed、agent.session.turn.failed 或 agent.session.turn.cancelled 事件。即使一轮交互已完成,其中仍可能有失败的工具调用。请检查工具结果和智能体的最终回复。

agent.session.failed 表示会话失败,单轮交互失败不一定会触发此事件。删除会话没有对应的 webhook,也不会停止提供商侧计算资源的运行。