For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主要導覽

建議

智慧體 API

智慧體 SDK

ChatKit

API Dashboard
試用 ChatGPT

事件與項目

接收即時更新並擷取已儲存的工作成果。

事件會回報智慧體執行工作時發生的情況。項目則是已儲存的訊息和工具呼叫，可供日後擷取。使用事件即時更新應用程式，並使用項目顯示已儲存的歷史紀錄。

應用程式會傳送輸入事件，以提交訊息、取消回合或傳回工具結果。智慧體則會傳送事件，回報輸出和工作階段的變更。如需瞭解如何傳送輸入，請參閱執行與接續工作階段。

接收串流

請先訂閱再傳送工作，讓應用程式能收到回合初期的事件。傳入 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 用來識別已儲存的項目，其中包含訊息的內容、狀態和階段。請參閱擷取已儲存的工作成果。

如需所有事件類型和欄位，請參閱串流事件參考資料。這些串流事件與 Webhooks 不同。如需瞭解子代理程式的活動及指令歸屬，請參閱觀察委派情況。

擷取項目與回合

使用應用程式對話狀態中的工作階段 ID，擷取已儲存的工作成果：

  • 工作階段項目： 列出項目，以擷取根智慧體在各回合中的訊息和工具呼叫。
  • 回合： 列出回合以瀏覽工作階段中的工作。根據 ID 擷取回合，以檢查其狀態、時間戳記、用量和錯誤。
  • 單一回合的項目： 針對根智慧體的回合，可依 turn_id 篩選工作階段項目。每個子代理程式都有自己的項目歷史紀錄，以及依回合擷取項目的端點。

列表端點每次傳回一頁結果。使用 SDK 的分頁輔助函式或 after 游標擷取更多結果。單一頁面可能不包含某個回合的所有項目。使用 order: "asc"，依時間由舊到新讀取項目。

如何復原中斷的串流

串流不會重播錯過的事件。若要還原應用程式的畫面：

  1. 開啟新的串流，並將收到的事件存入緩衝區。
  2. 保持串流連線，同時擷取工作階段及其已儲存的項目。
  3. 以項目 ID 為索引鍵，根據這些項目還原本機狀態。
  4. 使用 item_id 套用緩衝區中的項目更新。如果擷取的歷史紀錄顯示某個項目已達最終狀態，則捨棄該項目的更新。
  5. 恢復處理即時事件。

output_text.done 事件可用完整文字取代暫存文字緩衝區的內容。已儲存的項目可讓你復原已完成的工作成果，但無法復原所有錯過的中間事件。