Loading...
    • 建構
    • 管理
    • 模型與定價
    • 客戶端 SDK
    • API 參考
    Search...
    ⌘K
    第一步
    Claude 簡介快速入門
    使用 Claude 建構
    功能概覽使用 Messages API處理停止原因
    模型功能
    延伸思考自適應思考效能快速模式(測試版:研究預覽)結構化輸出引用來源串流訊息批次處理搜尋結果串流拒絕多語言支援嵌入向量
    工具
    概覽工具使用方式網路搜尋工具網路擷取工具程式碼執行工具記憶體工具Bash 工具電腦使用工具文字編輯器工具
    工具基礎架構
    工具搜尋程式化工具呼叫細粒度工具串流
    上下文管理
    上下文視窗壓縮上下文編輯提示快取Token 計數
    處理檔案
    Files APIPDF 支援圖像與視覺
    技能
    概覽快速入門最佳實踐企業版技能API 中的技能
    MCP
    遠端 MCP 伺服器MCP 連接器
    提示工程
    概覽提示最佳實踐Console 提示工具
    測試與評估
    定義成功標準並建立評估在 Console 中使用評估工具降低延遲
    強化防護欄
    減少幻覺提高輸出一致性防範越獄減少提示洩漏
    資源
    詞彙表
    版本說明
    Claude Platform
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    將工作委派給代理

    工作階段事件串流

    傳送事件、串流回應,並在執行過程中中斷或重新導向您的工作階段。

    與 Claude Managed Agents 的通訊是基於事件的。您向代理程式傳送使用者事件,並接收代理程式和工作階段事件以追蹤狀態。

    所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

    事件類型

    事件以兩個方向流動。

    • 使用者事件是您傳送給代理程式以啟動工作階段並在其進行時引導它的內容。
    • 工作階段事件、span 事件和代理程式事件會傳送給您,以便觀察您的工作階段狀態和代理程式進度。

    事件類型字串遵循 {domain}.{action} 命名慣例。

    Was this page helpful?

    每個事件都包含一個 processed_at 時間戳記,指示事件在伺服器端被記錄的時間。如果 processed_at 為 null,表示事件已被 harness 排入佇列,將在前面的事件完成處理後才會被處理。

    請參閱工作階段事件 API 參考以了解每種事件類型的完整結構描述。

    整合事件

    其他情境

    處理自訂工具呼叫

    當代理程式呼叫自訂工具時:

    1. 工作階段發出包含工具名稱和輸入的 agent.custom_tool_use 事件。
    2. 工作階段暫停,並發出包含 stop_reason: requires_action 的 session.status_idle 事件。封鎖事件 ID 位於 stop_reason.requires_action.event_ids 陣列中。
    3. 在您的系統中執行工具,並為每個工具傳送 user.custom_tool_result 事件,在 custom_tool_use_id 參數中傳遞事件 ID 以及結果內容。
    4. 一旦所有封鎖事件都已解決,工作階段將轉換回 running。
    exec {fd}< <(curl -sS -N --fail-with-body \
      "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01" \
      -H "content-type: application/json" \
      -H "Accept: text/event-stream")
    
    while IFS= read -r -u "$fd" line; do
      [[ $line == data:* ]] || continue
      data="${line#data: }"
      [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
      case $(jq -r '.stop_reason.type // empty' <<<"$data") in
        requires_action)
          while IFS= read -r event_id; do
            # 查找自訂工具使用事件並執行它
            result=$(call_tool "$event_id")
            # 傳回結果
            jq -n --arg id "$event_id" --arg result "$result" \
              '{events: [{type: "user.custom_tool_result", custom_tool_use_id: $id, content: [{type: "text", text: $result}]}]}' |
              curl -sS --fail-with-body \
                "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
                -H "x-api-key: $ANTHROPIC_API_KEY" \
                -H "anthropic-version: 2023-06-01" \
                -H "anthropic-beta: managed-agents-2026-04-01" \
                -H "content-type: application/json" \
                -d @-
          done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
          ;;
        end_turn)
          break
          ;;
      esac
    done
    exec {fd}<&-

    工具確認

    當權限政策要求在工具執行前進行確認時:

    1. 會話發出 agent.tool_use 或 agent.mcp_tool_use 事件。
    2. 會話暫停,並發出包含 stop_reason: requires_action 的 session.status_idle 事件。阻塞的事件 ID 位於 stop_reason.requires_action.event_ids 陣列中。
    3. 為每個事件發送 user.tool_confirmation 事件,在 tool_use_id 參數中傳入事件 ID。將 result 設為 "allow" 或 "deny"。使用 deny_message 說明拒絕原因。
    4. 一旦所有阻塞事件都已解決,會話將轉回 running 狀態。
    exec {fd}< <(curl -sS -N --fail-with-body \
      "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01" \
      -H "content-type: application/json" \
      -H "Accept: text/event-stream")
    
    while IFS= read -r -u "$fd" line; do
      [[ $line == data:* ]] || continue
      data="${line#data: }"
      [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
      case $(jq -r '.stop_reason.type // empty' <<<"$data") in
        requires_action)
          while IFS= read -r event_id; do
            # Approve the pending tool call
            jq -n --arg id "$event_id" \
              '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |
              curl -sS --fail-with-body \
                "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
                -H "x-api-key: $ANTHROPIC_API_KEY" \
                -H "anthropic-version: 2023-06-01" \
                -H "anthropic-beta: managed-agents-2026-04-01" \
                -H "content-type: application/json" \
                -d @-
          done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
          ;;
        end_turn)
          break
          ;;
      esac
    done
    exec {fd}<&-

    追蹤使用量

    會話物件包含一個 usage 欄位,其中包含累計的 token 統計資料。在會話進入閒置狀態後獲取會話以讀取最新總計,並使用這些數據追蹤費用、執行預算或監控消耗量。

    {
      "id": "sesn_01...",
      "status": "idle",
      "usage": {
        "input_tokens": 5000,
        "output_tokens": 3200,
        "cache_creation_input_tokens": 2000,
        "cache_read_input_tokens": 20000
      }
    }

    input_tokens 報告未快取的輸入 token,output_tokens 報告會話中所有模型呼叫的總輸出 token。cache_creation_input_tokens 和 cache_read_input_tokens 欄位反映提示快取活動。快取條目使用 5 分鐘的 TTL,因此在該時間窗口內連續進行的輪次可受益於快取讀取,從而降低每個 token 的費用。