레퍼런스
Claude Managed Agents의 이벤트 유형, 자체 호스팅 워커 CLI 플래그, 지원되는 MCP 서버 유형, 속도 제한 및 브랜딩 가이드라인입니다.
이 페이지는 Claude Managed Agents에 대한 레퍼런스 자료를 모아 놓은 것입니다. 작업 중심 가이드는 각 섹션의 링크를 따라가세요. 세션 리소스에 대한 작업은 세션 작업을 참조하세요.
이벤트 유형
영구 저장되는 이벤트 유형 문자열은 {domain}.{action} 명명 규칙을 따릅니다. 스트림 전용 이벤트 델타(이벤트 델타 탭 참조)는 예외입니다. 이벤트 전송, 스트리밍 및 목록 조회에 대해서는 세션 이벤트 스트림을 참조하세요. 웹훅 이벤트 유형은 웹훅 구독에 별도로 나열되어 있으며, 일부 이름은 스트림의 이름과 다릅니다(예: session.status_idle이 아닌 session.status_idled).
| 유형 | 설명 |
|---|---|
user.message | 텍스트, 이미지 또는 문서 콘텐츠가 포함된 사용자 메시지입니다. |
user.interrupt | 실행 중인 에이전트를 중지합니다. 워크플로 실행은 종료하지 않습니다. |
user.custom_tool_result | 에이전트의 커스텀 도구 호출에 대한 응답입니다. |
user.tool_confirmation | 권한 정책에서 확인을 요구하는 경우 에이전트 또는 MCP 도구 호출을 승인하거나 거부합니다. |
user.define_outcome | 에이전트가 달성하기 위해 작업할 결과(outcome)를 정의합니다. |
user.tool_result | self_hosted 환경을 사용하는 세션에만 해당하며, 통합 측에서 agent_toolset 결과를 제공할 책임이 있습니다. SDK 헬퍼와 CLI는 이를 자동으로 수행합니다. |
| 유형 | 설명 |
|---|---|
agent.message | 에이전트 응답 콘텐츠 블록입니다. |
agent.thinking | 에이전트가 "extended thinking"(확장 사고)을 통해 작업을 진행하고 있음을 알립니다. 이는 진행 신호일 뿐이며 사고 내용은 포함하지 않습니다. |
agent.tool_use | 에이전트가 사전 구축된 에이전트 도구(bash, 파일 작업 등)를 호출합니다. evaluated_permission과 일반적으로 evaluation을 포함합니다(각 호출이 평가된 방식 참조). |
agent.tool_result | 사전 구축된 에이전트 도구의 실행 결과입니다. |
agent.mcp_tool_use | 에이전트가 MCP 서버 도구를 호출합니다. evaluated_permission과 일반적으로 evaluation을 포함합니다(각 호출이 평가된 방식 참조). |
agent.mcp_tool_result | MCP 도구의 실행 결과입니다. |
agent.custom_tool_use | 에이전트가 사용자 정의 도구 중 하나를 호출합니다. user.custom_tool_result 이벤트로 응답하세요. |
agent.thread_context_compacted | "context window"(컨텍스트 윈도우)에 맞도록 대화 기록이 압축되었습니다. |
agent.thread_message_received | 멀티에이전트 세션에서 이 이벤트를 전달하는 스트림의 스레드에 다른 스레드의 메시지가 도착했습니다. 기본 스레드에서는 에이전트가 세션이 실행하는 에이전트에게 보고나 질문을 보냈습니다. |
agent.thread_message_sent | 멀티에이전트 세션에서 이 이벤트를 전달하는 스트림의 스레드가 다른 스레드에 메시지를 보냈습니다. 기본 스레드에서는 세션이 실행하는 에이전트가 다른 에이전트에게 작업 또는 후속 메시지를 보냈습니다. |
이러한 이벤트의 메시지 콘텐츠에는 redacted 콘텐츠 블록 {"type": "redacted"}가 포함될 수 있습니다. 이는 Anthropic 모델 정책에 따라 보류된 콘텐츠의 자리표시자입니다. 이 블록에는 다른 필드가 없습니다. Redacted 블록은 플랫폼이 내보내는 콘텐츠에만 나타나며, 이를 포함하는 사용자 이벤트는 400 오류로 거부됩니다.
| 유형 | 설명 |
|---|---|
session.status_running | 에이전트가 활발히 처리 중입니다. |
session.status_idle | 에이전트가 현재 작업을 마치고 입력을 기다리고 있습니다. 에이전트가 중지된 이유를 나타내는 stop_reason을 포함합니다. |
session.status_rescheduled | 일시적인 오류가 발생하여 세션이 자동으로 재시도 중입니다. |
session.status_terminated | 복구할 수 없는 오류로 인해 또는 보관 처리되어 세션이 종료되었습니다. |
session.deleted | 세션이 삭제되었습니다. 활성 이벤트 스트림을 모두 종료하며, 이 세션에 대해 더 이상 이벤트가 발생하지 않습니다. |
session.updated | 세션 업데이트 요청으로 하나 이상의 필드가 변경되었습니다. 변경된 필드만 포함합니다. 업데이트는 다음 턴에 적용됩니다. |
session.error | 처리 중 오류가 발생했습니다. retry_status가 있는 유형화된 error 객체를 포함합니다. |
session.usage | 세션의 누적 사용량과 추적된 정가 비용의 스냅샷입니다. 세션의 사용량 합계와, 세션에 예산이 있는 경우 해당 예산을 포함합니다. |
session.thread_created | 멀티에이전트 스레드가 생성되었습니다. workflow_run_id를 포함하며, 이는 워크플로 실행의 스레드인 경우 해당 실행의 ID이고, 그 외 스레드의 경우 None입니다. |
session.thread_status_running | 세션 스레드가 실행을 시작했습니다. 모든 세션은 기본 스레드에 대해 이 이벤트를 내보내며, 멀티에이전트 세션에서는 하위 스레드의 상태 전환도 기본 스트림에 교차 게시됩니다. |
session.thread_status_idle | 세션 스레드가 턴을 마치고 입력을 기다리고 있습니다. stop_reason을 포함합니다. |
session.thread_status_rescheduled | 세션 스레드에 일시적인 오류가 발생하여 자동으로 재시도 중입니다. |
session.thread_status_terminated | 세션 스레드가 종료되어 더 이상 입력을 받지 않습니다. 예를 들어 보관 처리되었거나 복구할 수 없는 오류가 발생한 경우입니다. 어드바이저 스레드는 자문이 끝날 때도 종료됩니다. 워크플로 실행의 스레드는 서버가 직접 보관 처리합니다. |
에이전트에 동적 워크플로가 켜져 있는 세션에서는 다음 workflow_run.* 이벤트가 세션의 스트림에 도착합니다:
| 유형 | 설명 |
|---|---|
workflow_run.created | 워크플로 실행이 생성되었습니다. workflow_run_id, 실행의 name 및 description, 그리고 실행에 대해 선언된 단계인 phases를 포함합니다. 이후 상태 이벤트가 뒤따르지만, 중단 이후에는 뒤따르지 않을 수 있습니다. |
workflow_run.status_running | 워크플로 실행이 실행 중입니다. 실행이 시작될 때 전송되며, 이는 workflow_run.created 이후 시간이 꽤 지난 뒤일 수 있습니다. 또한 예산으로 인해 일시 중지되었다가 재개될 때 다시 전송됩니다. 중단 이후의 재개에서는 전송되지 않을 수 있습니다. 처음부터 유휴 상태인 실행은 workflow_run.status_idle을 먼저 받을 수 있습니다. workflow_run_id를 포함합니다. |
workflow_run.status_idle | 워크플로 실행이 유휴 상태가 되었습니다. 예를 들어 세션의 예산에 도달하여 일시 중지되었습니다. 중단 이후의 일시 중지에서는 전송되지 않을 수 있습니다. workflow_run_id를 포함합니다. |
workflow_run.status_ended | 워크플로 실행이 종료되었습니다. workflow_run_id와 result를 포함하며, 그 type은 실행이 어떻게 종료되었는지를 나타냅니다. |
workflow_run.error | 워크플로 실행의 오류 또는 서버가 거부한 시작입니다. 오류로 종료되는 실행은 workflow_run.status_ended 전에 동일한 오류와 함께 이 이벤트를 받습니다. error와 workflow_run_id를 포함하며, 실행이 생성되지 않은 경우 후자는 None입니다. |
workflow_run.phase_started | 워크플로 실행이 단계 중 하나에 진입했습니다. workflow_run_id와 workflow_run_phase_id를 포함합니다. |
workflow_run.phase_ended | 워크플로 실행이 단계를 벗어났습니다. workflow_run_id, workflow_run_phase_id, phase_started_id를 포함합니다. |
스팬 이벤트는 타이밍 및 사용량 추적을 위해 활동을 감싸는 관측 가능성 마커입니다.
| 유형 | 설명 |
|---|---|
span.model_request_start | 모델 추론 호출이 시작되었습니다. |
span.model_request_end | 모델 추론 호출이 완료되었습니다. 토큰 수가 포함된 model_usage를 포함합니다. |
span.outcome_evaluation_start | 결과(outcome) 평가가 시작되었습니다. |
span.outcome_evaluation_ongoing | 진행 중인 결과(outcome) 평가 동안의 하트비트입니다. |
span.outcome_evaluation_end | 결과(outcome) 평가 사이클이 완료되었습니다. needs_revision 결과는 다른 사이클이 이어진다는 의미이며, satisfied, max_iterations_reached, failed, interrupted는 최종 상태입니다. |
| 유형 | 설명 |
|---|---|
system.message | 함께 전달되는 턴과 이후의 모든 턴에 적용되는 권한 있는 시스템 수준 컨텍스트를 추가합니다. 이를 허용하는 모델은 지원되는 모델을 참조하세요. 지원되지 않는 기본 모델에서는 이벤트가 model_does_not_support_mid_conversation_system과 함께 거부됩니다. |
이벤트 델타는 스트림 전용 미리보기 이벤트입니다. event_deltas 매개변수로 옵트인한 스트림 연결(세션 수준 또는 스레드별)에서 발생하며, 세션의 이벤트 기록에는 절대 영구 저장되지 않습니다. 옵트인, 누적 및 조정 방법은 이벤트 델타로 응답 미리보기를 참조하세요.
| 유형 | 설명 |
|---|---|
event_start | 미리보기 이벤트의 생성이 시작되었습니다. 곧 발생할 이벤트의 type과 id를 포함합니다. 스트림 전용이며 영구 저장되지 않습니다. |
event_delta | event_id로 식별되는 미리보기 이벤트의 증분 콘텐츠입니다. 스트림 전용이며 영구 저장되지 않습니다. |
자체 호스팅 워커
self_hosted 환경을 구동하는 사전 구축된 워커의 ant beta:worker CLI 플래그, 환경 변수, 파일 시스템 경로 및 SDK 헬퍼 옵션은 자체 호스팅 워커 참조를 참조하세요.
지원되는 MCP 서버 유형
Claude Managed Agents는 HTTP 엔드포인트를 노출하는 원격 MCP 서버에 연결하거나, MCP 터널을 통해 비공개 MCP 서버에 연결합니다. 서버는 MCP 프로토콜의 스트리밍 가능한 HTTP 전송을 지원해야 하며, 지원 중단된 SSE 전송만 지원하는 서버도 자동 폴백을 통해 계속 작동합니다. 에이전트에 서버를 선언하는 방법은 MCP 커넥터를 참조하세요.
MCP 및 MCP 서버 구축에 대한 자세한 내용은 MCP 문서를 참조하세요.
속도 제한
Managed Agents 엔드포인트는 조직별로 속도 제한이 적용됩니다.
| 작업 | 제한 |
|---|---|
| 생성 엔드포인트(에이전트, 세션, 환경 등) | 분당 300개 요청 |
| 읽기 엔드포인트(조회, 목록, 스트림 등) | 분당 1,200개 요청 |
조직 수준의 지출 한도 및 사용 등급 속도 제한도 적용됩니다.
브랜딩 가이드라인
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 영업팀에 문의하세요.
Was this page helpful?