事件类型详解

1. 输出项相关事件

1.1 response.output_item.added

用途: 当新的输出项被添加时触发

触发时机:

• 开始网页搜索时
• 开始网页爬取时
• 开始生成最终答案时

数据结构:

{
  "type": "response.output_item.added",
  "sequence_number": 1,
  "output_index": 0,
  "item": {
    "id": "ws_1234567890",
    "type": "web_search_call",
    "status": "in_progress"
  }
}

1.2 response.output_item.done

用途: 当输出项完成时触发

触发时机:

• 网页搜索完成时
• 网页爬取完成时
• 最终答案生成完成时

数据结构:

{
  "type": "response.output_item.done",
  "sequence_number": 5,
  "output_index": 0,
  "item": {
    "id": "ws_1234567890",
    "type": "web_search_call",
    "status": "completed",
    "action": {
      "type": "search",
      "query": "AI technology trends",
      "results": [
        {
          "title": "Latest AI Developments",
          "link": "https://example.com/ai-news",
          "snippet": "Recent advances in artificial intelligence...",
          "position": 1
        }
      ]
    }
  }
}

2. 网页搜索相关事件

2.1 response.web_search_call.in_progress

用途: 表示网页搜索正在进行中

数据结构:

{
  "type": "response.web_search_call.in_progress",
  "sequence_number": 2,
  "output_index": 0,
  "item_id": "ws_1234567890"
}

2.2 response.web_search_call.searching

用途: 表示正在执行搜索阶段

数据结构:

{
  "type": "response.web_search_call.searching",
  "sequence_number": 3,
  "output_index": 0,
  "item_id": "ws_1234567890"
}

2.3 response.web_search_call.completed

用途: 表示网页搜索已完成

数据结构:

{
  "type": "response.web_search_call.completed",
  "sequence_number": 4,
  "output_index": 0,
  "item_id": "ws_1234567890"
}

3. 内容生成事件

3.1 response.content_part.added

用途: 表示内容生成开始

数据结构:

{
  "type": "response.content_part.added",
  "sequence_number": 6,
  "output_index": 1,
  "item": {
    "id": "content_1234567890",
    "type": "text",
    "status": "in_progress"
  }
}

3.2 response.output_text.delta

用途: 流式文本内容更新

数据结构:

{
  "type": "response.output_text.delta",
  "sequence_number": 7,
  "output_index": 1,
  "item_id": "content_1234567890",
  "item": {
    "delta": "Based on the search results, "
  }
}

3.3 response.output_text.done

用途: 表示文本生成已完成

数据结构:

{
  "type": "response.output_text.done",
  "sequence_number": 20,
  "output_index": 1,
  "item_id": "content_1234567890",
  "item": {
    "text": "Complete generated text content..."
  }
}

4. 成本相关事件

4.1 response.cost.final

用途: 最终成本汇总

数据结构:

{
    "type": "response.cost.final",
    "sequence_number": 886,
    "output_index": 279,
    "item": {
        "output_index": 279,
        "sequence_number": 886,
        "total_cost": 0.05522360760000001,
        "type": "response.cost.final"
    }
}

5. 错误事件

5.1 error

用途: 错误信息

数据结构:

{
  "type": "error",
  "sequence_number": 99,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded, please try again later",
    "details": {
      "retry_after": 60
    }
  }
}

事件处理最佳实践

1. 顺序处理: 根据sequence_number顺序处理事件
2. 错误处理: 始终实现错误事件处理
3. 状态管理: 使用item_id跟踪输出项状态
4. 内容缓冲: 缓冲 delta 事件以组装完整内容
5. 成本监控: 监控成本事件以追踪使用情况