--- title: 參考資料 url: https://platform.claude.com/docs/zh-TW/managed-agents/reference description: Claude Managed Agents 的事件類型、自行託管 worker CLI 旗標、支援的 MCP 伺服器類型、速率限制及品牌使用準則。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 本頁彙整了 Claude Managed Agents 的參考資料。如需以任務為導向的指南，請依循各節中的連結。關於 session 資源的操作，請參閱 [Session 操作](https://platform.claude.com/docs/zh-TW/managed-agents/session-operations)。 ## 事件類型 持久化的事件類型字串遵循 `{domain}.{action}` 命名慣例；僅限串流的事件增量（event deltas，請參閱「事件增量」分頁）則是例外。關於傳送、串流及列出事件，請參閱 [Session 事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming)。Webhook 事件類型另行列於[訂閱 webhook](https://platform.claude.com/docs/zh-TW/managed-agents/webhooks#supported-event-types)，其中部分名稱與串流中的名稱不同（例如 `session.status_idled` 而非 `session.status_idle`）。 | 類型 | 說明 | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user.message` | 包含文字、圖片或文件內容的使用者訊息。 | | `user.interrupt` | 在執行途中停止代理。它不會結束任何[工作流程執行](https://platform.claude.com/docs/zh-TW/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)。 | | `user.custom_tool_result` | 對代理發出之自訂工具呼叫的回應。 | | `user.tool_confirmation` | 當權限政策要求確認時，核准或拒絕代理或 MCP 工具呼叫。 | | `user.define_outcome` | 定義一個供代理努力達成的[成果（outcome）](https://platform.claude.com/docs/zh-TW/managed-agents/define-outcomes)。 | | `user.tool_result` | 僅適用於使用 `self_hosted` [環境](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes)的 session，您的整合需負責提供 `agent_toolset` 結果。SDK 輔助工具與 CLI 會自動處理此事。 | | 類型 | 說明 | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.message` | 代理回應的內容區塊。 | | `agent.thinking` | 表示代理正透過擴展思考持續推進。這僅是進度訊號，不包含思考內容。 | | `agent.tool_use` | 代理呼叫預建的代理工具（bash、檔案操作等）。帶有 `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`)，且通常帶有 `evaluation` (csharp, go: `Evaluation`)（請參閱[每次呼叫的評估方式](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#see-how-each-call-was-evaluated)）。 | | `agent.tool_result` | 預建代理工具執行的結果。 | | `agent.mcp_tool_use` | 代理呼叫 MCP 伺服器工具。帶有 `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`)，且通常帶有 `evaluation` (csharp, go: `Evaluation`)（請參閱[每次呼叫的評估方式](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#see-how-each-call-was-evaluated)）。 | | `agent.mcp_tool_result` | MCP 工具執行的結果。 | | `agent.custom_tool_use` | 代理呼叫您的其中一個自訂工具。請以 `user.custom_tool_result` 事件回應。 | | `agent.thread_context_compacted` | 對話歷史已被壓縮以符合上下文視窗。 | | `agent.thread_message_received` | 在[多代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration) session 中，來自另一個執行緒的訊息抵達了其串流帶有此事件的執行緒；在主要執行緒上，則表示某個代理向該 session 所執行的代理傳送了報告或問題。 | | `agent.thread_message_sent` | 在[多代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration) session 中，其串流帶有此事件的執行緒向另一個執行緒傳送了訊息；在主要執行緒上，則表示該 session 所執行的代理向另一個代理傳送了任務或後續訊息。 | 這些事件中的訊息內容可能包含 `redacted` 內容區塊 `{"type": "redacted"}`：這是依 Anthropic 模型政策被保留不公開之內容的佔位符。該區塊不帶有其他欄位。Redacted 區塊僅出現在平台發出的內容中；包含此類區塊的使用者事件會以 400 錯誤被拒絕。 | 類型 | 說明 | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session.status_running` | 代理正在積極處理中。 | | `session.status_idle` | 代理已完成目前的任務，正在等待輸入。包含一個 `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)，說明代理停止的原因。 | | `session.status_rescheduled` | 發生暫時性錯誤，session 正在自動重試。 | | `session.status_terminated` | Session 已結束，原因可能是發生無法復原的錯誤，或是已被封存。 | | `session.deleted` | Session 已被刪除。會終止任何進行中的事件串流；此 session 不會再發出任何事件。 | | `session.updated` | Session 更新請求變更了至少一個欄位。僅包含已變更的欄位。更新會在下一個回合套用。 | | `session.error` | 處理期間發生錯誤。包含一個具型別的 `error` (csharp, go: `Error`) 物件，其中帶有 `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`)。 | | `session.usage` | Session 累計用量與追蹤之定價成本的快照。帶有 session 的用量總計，以及（若 session 有設定）其[預算](https://platform.claude.com/docs/zh-TW/managed-agents/budgets)。 | | `session.thread_created` | 已建立一個[多代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration)執行緒。它包含 `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`)：對於[工作流程執行](https://platform.claude.com/docs/zh-TW/managed-agents/workflow-runs#a-runs-threads)的執行緒，此值為該執行的 ID；對於其他任何執行緒，此值為 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`)。 | | `session.thread_status_running` | 某個 session 執行緒開始執行。每個 session 都會為其主要執行緒發出此事件；在[多代理](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration) session 中，子執行緒的狀態轉換也會交叉發布到主要串流。 | | `session.thread_status_idle` | 某個 session 執行緒已完成其回合，正在等待輸入。包含 `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)。 | | `session.thread_status_rescheduled` | 某個 session 執行緒遇到暫時性錯誤，正在自動重試。 | | `session.thread_status_terminated` | 某個 session 執行緒已終止且不再接受任何輸入，例如因為它已被封存或遇到無法復原的錯誤。顧問執行緒也會在其諮詢結束時終止。伺服器會自行封存工作流程執行的執行緒。 | 在代理已開啟[動態工作流程](https://platform.claude.com/docs/zh-TW/managed-agents/multiagent-orchestration#dynamic-workflows)的 session 中，以下 `workflow_run.*` 事件會出現在 session 的串流上： | 類型 | 說明 | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workflow_run.created` | 已建立一個工作流程執行。包含 `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`)、該執行的 `name` (csharp, go: `Name`) 和 `description` (csharp, go: `Description`)，以及 `phases` (csharp, go: `Phases`)，即為該執行宣告的階段。之後會接著一個狀態事件，但在中斷之後可能不會。 | | `workflow_run.status_running` | 某個工作流程執行正在執行中。在執行開始運作時傳送（可能在 `workflow_run.created` 之後一段時間），並在其因預算暫停後恢復時再次傳送。中斷後的恢復可能不會傳送此事件。從一開始就處於閒置狀態的執行可能會先收到 `workflow_run.status_idle`。包含 `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`)。 | | `workflow_run.status_idle` | 某個工作流程執行進入閒置狀態：它已被暫停，例如因達到 session 的預算。中斷後的暫停可能不會傳送此事件。包含 `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`)。 | | `workflow_run.status_ended` | 某個工作流程執行已結束。包含 `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) 和 `result` (csharp, go: `Result`)，其 `type` (csharp, go: `Type`) 說明該執行如何結束。 | | `workflow_run.error` | 某個工作流程執行的錯誤，或伺服器拒絕的啟動。以錯誤結束的執行會在其 `workflow_run.status_ended` 之前收到此事件，並帶有相同的錯誤。包含 `error` (csharp, go: `Error`) 和 `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`)，當未建立任何執行時，後者為 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`)。 | | `workflow_run.phase_started` | 某個工作流程執行進入了其中一個階段。包含 `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) 和 `workflow_run_phase_id` (java: `workflowRunPhaseId`; php: `workflowRunPhaseID`; csharp, go: `WorkflowRunPhaseID`)。 | | `workflow_run.phase_ended` | 某個工作流程執行離開了一個階段。包含 `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`)、`workflow_run_phase_id` (java: `workflowRunPhaseId`; php: `workflowRunPhaseID`; csharp, go: `WorkflowRunPhaseID`) 和 `phase_started_id` (java: `phaseStartedId`; php: `phaseStartedID`; csharp, go: `PhaseStartedID`)。 | Span 事件是可觀測性標記，用於包裹活動以進行計時與用量追蹤。 | 類型 | 說明 | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `span.model_request_start` | 模型推論呼叫已開始。 | | `span.model_request_end` | 模型推論呼叫已完成。包含帶有 token 計數的 `model_usage` (java, php: `modelUsage`; csharp, go: `ModelUsage`)。 | | `span.outcome_evaluation_start` | [成果](https://platform.claude.com/docs/zh-TW/managed-agents/define-outcomes)評估已開始。 | | `span.outcome_evaluation_ongoing` | 進行中的[成果](https://platform.claude.com/docs/zh-TW/managed-agents/define-outcomes)評估期間的心跳訊號。 | | `span.outcome_evaluation_end` | 一個[成果](https://platform.claude.com/docs/zh-TW/managed-agents/define-outcomes)評估週期已完成。`needs_revision` 結果表示後續還有另一個週期；`satisfied`、`max_iterations_reached`、`failed` 與 `interrupted` 則為終止狀態。 | | 類型 | 說明 | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `system.message` | 附加具特權的系統層級上下文，適用於隨附的回合及所有後續回合。關於接受此事件的模型，請參閱[支援的模型](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#supported-models)。若主要模型不支援，此事件會以 `model_does_not_support_mid_conversation_system` 被拒絕。 | 事件增量是僅限串流的預覽事件。它們會在透過 `event_deltas` (curl: `event_deltas[]`; cli: `--event-delta`; java, php: `eventDeltas`; csharp, go: `EventDeltas`) 參數選擇啟用的串流連線（session 層級或個別執行緒）上發出，且永遠不會持久化到 session 的事件歷史中。關於選擇啟用、累積和調和這些事件，請參閱[使用事件增量預覽回應](https://platform.claude.com/docs/zh-TW/managed-agents/event-deltas)。 | 類型 | 說明 | | ------------- | ------------------------------------------------------------------------------------------------ | | `event_start` | 某個預覽事件已開始生成。帶有即將到來之事件的 `type` (csharp, go: `Type`) 和 `id` (csharp, go: `ID`)。僅限串流，永遠不會持久化。 | | `event_delta` | 預覽事件的增量內容，以 `event_id` (java: `eventId`; php: `eventID`; csharp, go: `EventID`) 識別。僅限串流，永遠不會持久化。 | ## 自行託管 worker 關於驅動 `self_hosted` 環境之預建 worker 的 `ant beta:worker` CLI 旗標、環境變數、檔案系統路徑和 SDK 輔助工具選項，請參閱[自行託管 worker 參考](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference)。 ## 支援的 MCP 伺服器類型 Claude Managed Agents 可連線至公開 HTTP 端點的[遠端 MCP 伺服器](https://platform.claude.com/docs/zh-TW/agents-and-tools/remote-mcp-servers)，或透過 [MCP 通道](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/overview)連線至私有 MCP 伺服器。伺服器應支援 MCP 協定的 streamable HTTP 傳輸；僅支援已棄用之 SSE 傳輸的伺服器仍可透過自動回退機制運作。關於在代理上宣告伺服器，請參閱 [MCP 連接器](https://platform.claude.com/docs/zh-TW/managed-agents/mcp-connector)。 如需更多關於 MCP 及建置 MCP 伺服器的資訊，請參閱 [MCP 文件](https://modelcontextprotocol.io)。 ## 速率限制 Managed Agents 端點依組織進行「rate limit」（速率限制）： | 操作 | 限制 | | ----------------------- | ------------- | | 建立類端點（例如代理、session 與環境） | 每分鐘 300 個請求 | | 讀取類端點（例如擷取、列出與串流） | 每分鐘 1,200 個請求 | 組織層級的[支出限制與用量層級速率限制](https://platform.claude.com/docs/zh-TW/api/rate-limits)同樣適用。 ## 品牌使用準則 對於整合 Claude Managed Agents 的合作夥伴，使用 Claude 品牌為選擇性的。在您的產品中提及 Claude 時： **允許：** * 「Claude Agent」（下拉式選單的首選） * 「Claude」（當位於已標示為「Agents」的選單內時） * 「\{YourAgentName} Powered by Claude」（若您已有現成的代理名稱） **不允許：** * 「Claude Code」或「Claude Code Agent」 * 「Claude Cowork」或「Claude Cowork Agent」 * Claude Code 品牌的 ASCII 藝術或模仿 Claude Code 的視覺元素 您的產品應維持自身的品牌，且不應看起來像是 Claude Code、Claude Cowork 或任何其他 Anthropic 產品。如有品牌合規方面的問題，請聯繫 Anthropic [銷售團隊](https://www.anthropic.com/contact-sales)。