--- title: 레퍼런스 url: https://platform.claude.com/docs/ko/managed-agents/reference description: Claude Managed Agents의 이벤트 유형, 자체 호스팅 워커 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에 대한 레퍼런스 자료를 모아 놓은 것입니다. 작업 중심 가이드는 각 섹션의 링크를 따라가세요. 세션 리소스에 대한 작업은 [세션 작업](https://platform.claude.com/docs/ko/managed-agents/session-operations)을 참조하세요. ## 이벤트 유형 영구 저장되는 이벤트 유형 문자열은 `{domain}.{action}` 명명 규칙을 따릅니다. 스트림 전용 이벤트 델타(이벤트 델타 탭 참조)는 예외입니다. 이벤트 전송, 스트리밍 및 목록 조회에 대해서는 [세션 이벤트 스트림](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming)을 참조하세요. 웹훅 이벤트 유형은 [웹훅 구독](https://platform.claude.com/docs/ko/managed-agents/webhooks#supported-event-types)에 별도로 나열되어 있으며, 일부 이름은 스트림의 이름과 다릅니다(예: `session.status_idle`이 아닌 `session.status_idled`). | 유형 | 설명 | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user.message` | 텍스트, 이미지 또는 문서 콘텐츠가 포함된 사용자 메시지입니다. | | `user.interrupt` | 실행 중인 에이전트를 중지합니다. [워크플로 실행](https://platform.claude.com/docs/ko/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/ko/managed-agents/define-outcomes)를 정의합니다. | | `user.tool_result` | `self_hosted` [환경](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes)을 사용하는 세션에만 해당하며, 통합 측에서 `agent_toolset` 결과를 제공할 책임이 있습니다. SDK 헬퍼와 CLI는 이를 자동으로 수행합니다. | | 유형 | 설명 | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.message` | 에이전트 응답 콘텐츠 블록입니다. | | `agent.thinking` | 에이전트가 "extended thinking"(확장 사고)을 통해 작업을 진행하고 있음을 알립니다. 이는 진행 신호일 뿐이며 사고 내용은 포함하지 않습니다. | | `agent.tool_use` | 에이전트가 사전 구축된 에이전트 도구(bash, 파일 작업 등)를 호출합니다. `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`)과 일반적으로 `evaluation` (csharp, go: `Evaluation`)을 포함합니다([각 호출이 평가된 방식](https://platform.claude.com/docs/ko/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/ko/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` | "context window"(컨텍스트 윈도우)에 맞도록 대화 기록이 압축되었습니다. | | `agent.thread_message_received` | [멀티에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration) 세션에서 이 이벤트를 전달하는 스트림의 스레드에 다른 스레드의 메시지가 도착했습니다. 기본 스레드에서는 에이전트가 세션이 실행하는 에이전트에게 보고나 질문을 보냈습니다. | | `agent.thread_message_sent` | [멀티에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration) 세션에서 이 이벤트를 전달하는 스트림의 스레드가 다른 스레드에 메시지를 보냈습니다. 기본 스레드에서는 세션이 실행하는 에이전트가 다른 에이전트에게 작업 또는 후속 메시지를 보냈습니다. | 이러한 이벤트의 메시지 콘텐츠에는 `redacted` 콘텐츠 블록 `{"type": "redacted"}`가 포함될 수 있습니다. 이는 Anthropic 모델 정책에 따라 보류된 콘텐츠의 자리표시자입니다. 이 블록에는 다른 필드가 없습니다. Redacted 블록은 플랫폼이 내보내는 콘텐츠에만 나타나며, 이를 포함하는 사용자 이벤트는 400 오류로 거부됩니다. | 유형 | 설명 | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session.status_running` | 에이전트가 활발히 처리 중입니다. | | `session.status_idle` | 에이전트가 현재 작업을 마치고 입력을 기다리고 있습니다. 에이전트가 중지된 이유를 나타내는 `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)을 포함합니다. | | `session.status_rescheduled` | 일시적인 오류가 발생하여 세션이 자동으로 재시도 중입니다. | | `session.status_terminated` | 복구할 수 없는 오류로 인해 또는 보관 처리되어 세션이 종료되었습니다. | | `session.deleted` | 세션이 삭제되었습니다. 활성 이벤트 스트림을 모두 종료하며, 이 세션에 대해 더 이상 이벤트가 발생하지 않습니다. | | `session.updated` | 세션 업데이트 요청으로 하나 이상의 필드가 변경되었습니다. 변경된 필드만 포함합니다. 업데이트는 다음 턴에 적용됩니다. | | `session.error` | 처리 중 오류가 발생했습니다. `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`)가 있는 유형화된 `error` (csharp, go: `Error`) 객체를 포함합니다. | | `session.usage` | 세션의 누적 사용량과 추적된 정가 비용의 스냅샷입니다. 세션의 사용량 합계와, 세션에 [예산](https://platform.claude.com/docs/ko/managed-agents/budgets)이 있는 경우 해당 예산을 포함합니다. | | `session.thread_created` | [멀티에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration) 스레드가 생성되었습니다. `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`)를 포함하며, 이는 [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#a-runs-threads)의 스레드인 경우 해당 실행의 ID이고, 그 외 스레드의 경우 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`)입니다. | | `session.thread_status_running` | 세션 스레드가 실행을 시작했습니다. 모든 세션은 기본 스레드에 대해 이 이벤트를 내보내며, [멀티에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration) 세션에서는 하위 스레드의 상태 전환도 기본 스트림에 교차 게시됩니다. | | `session.thread_status_idle` | 세션 스레드가 턴을 마치고 입력을 기다리고 있습니다. `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`)을 포함합니다. | | `session.thread_status_rescheduled` | 세션 스레드에 일시적인 오류가 발생하여 자동으로 재시도 중입니다. | | `session.thread_status_terminated` | 세션 스레드가 종료되어 더 이상 입력을 받지 않습니다. 예를 들어 보관 처리되었거나 복구할 수 없는 오류가 발생한 경우입니다. 어드바이저 스레드는 자문이 끝날 때도 종료됩니다. 워크플로 실행의 스레드는 서버가 직접 보관 처리합니다. | 에이전트에 [동적 워크플로](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#dynamic-workflows)가 켜져 있는 세션에서는 다음 `workflow_run.*` 이벤트가 세션의 스트림에 도착합니다: | 유형 | 설명 | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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` | 워크플로 실행이 유휴 상태가 되었습니다. 예를 들어 세션의 예산에 도달하여 일시 중지되었습니다. 중단 이후의 일시 중지에서는 전송되지 않을 수 있습니다. `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.model_request_start` | 모델 추론 호출이 시작되었습니다. | | `span.model_request_end` | 모델 추론 호출이 완료되었습니다. 토큰 수가 포함된 `model_usage` (java, php: `modelUsage`; csharp, go: `ModelUsage`)를 포함합니다. | | `span.outcome_evaluation_start` | [결과(outcome)](https://platform.claude.com/docs/ko/managed-agents/define-outcomes) 평가가 시작되었습니다. | | `span.outcome_evaluation_ongoing` | 진행 중인 [결과(outcome)](https://platform.claude.com/docs/ko/managed-agents/define-outcomes) 평가 동안의 하트비트입니다. | | `span.outcome_evaluation_end` | [결과(outcome)](https://platform.claude.com/docs/ko/managed-agents/define-outcomes) 평가 사이클이 완료되었습니다. `needs_revision` 결과는 다른 사이클이 이어진다는 의미이며, `satisfied`, `max_iterations_reached`, `failed`, `interrupted`는 최종 상태입니다. | | 유형 | 설명 | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `system.message` | 함께 전달되는 턴과 이후의 모든 턴에 적용되는 권한 있는 시스템 수준 컨텍스트를 추가합니다. 이를 허용하는 모델은 [지원되는 모델](https://platform.claude.com/docs/ko/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`) 매개변수로 옵트인한 스트림 연결(세션 수준 또는 스레드별)에서 발생하며, 세션의 이벤트 기록에는 절대 영구 저장되지 않습니다. 옵트인, 누적 및 조정 방법은 [이벤트 델타로 응답 미리보기](https://platform.claude.com/docs/ko/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`)로 식별되는 미리보기 이벤트의 증분 콘텐츠입니다. 스트림 전용이며 영구 저장되지 않습니다. | ## 자체 호스팅 워커 `self_hosted` 환경을 구동하는 사전 구축된 워커의 `ant beta:worker` CLI 플래그, 환경 변수, 파일 시스템 경로 및 SDK 헬퍼 옵션은 [자체 호스팅 워커 참조](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference)를 참조하세요. ## 지원되는 MCP 서버 유형 Claude Managed Agents는 HTTP 엔드포인트를 노출하는 [원격 MCP 서버](https://platform.claude.com/docs/ko/agents-and-tools/remote-mcp-servers)에 연결하거나, [MCP 터널](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/overview)을 통해 비공개 MCP 서버에 연결합니다. 서버는 MCP 프로토콜의 스트리밍 가능한 HTTP 전송을 지원해야 하며, 지원 중단된 SSE 전송만 지원하는 서버도 자동 폴백을 통해 계속 작동합니다. 에이전트에 서버를 선언하는 방법은 [MCP 커넥터](https://platform.claude.com/docs/ko/managed-agents/mcp-connector)를 참조하세요. MCP 및 MCP 서버 구축에 대한 자세한 내용은 [MCP 문서](https://modelcontextprotocol.io)를 참조하세요. ## 속도 제한 Managed Agents 엔드포인트는 조직별로 속도 제한이 적용됩니다. | 작업 | 제한 | | ------------------------ | ------------ | | 생성 엔드포인트(에이전트, 세션, 환경 등) | 분당 300개 요청 | | 읽기 엔드포인트(조회, 목록, 스트림 등) | 분당 1,200개 요청 | 조직 수준의 [지출 한도 및 사용 등급 속도 제한](https://platform.claude.com/docs/ko/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)에 문의하세요.