如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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 事件時,可以用完整文字取代緩衝區中暫存的文字。已儲存的項目可用來還原已完成的工作,但無法找回錯過的每一個中間事件。