4. 에이전트 출력 이벤트 (agent.*)
4.1. 텍스트 스트리밍
에이전트의 자연어 응답을 실시간으로 전달한다.
4.1.1. agent.text.delta (Client → Master)
{
"type": "agent.text.delta",
"payload": {
"content_index": "Number (필수, 0-based, 현재 Content Block 순번)",
"text": "String (필수, 텍스트 조각)"
}
}4.1.2. agent.text.done (Client → Master)
텍스트 스트리밍이 완료되었음을 알린다. 하나의 Content Block이 종료될 때마다 발송한다.
{
"type": "agent.text.done",
"payload": {
"content_index": "Number (필수)",
"full_text": "String (선택, 전체 텍스트. 수신 측 검증용)"
}
}4.2. 추론/사고 스트리밍 (Thinking)
에이전트의 내부 추론 과정을 전달한다. Extended Thinking, Chain-of-Thought 등에 사용.
4.2.1. agent.thinking.delta (Client → Master)
{
"type": "agent.thinking.delta",
"payload": {
"content_index": "Number (필수)",
"text": "String (필수, 사고 조각)",
"redacted": "Boolean (선택, 기본값 false. 보안상 수정된 내용 여부)"
}
}4.2.2. agent.thinking.done (Client → Master)
{
"type": "agent.thinking.done",
"payload": {
"content_index": "Number (필수)"
}
}4.3. 상호작용 요청 (Interaction Request)
에이전트가 사용자의 승인 또는 선택을 요구할 때 발송한다.
4.3.1. agent.interaction.request (Client → Master)
{
"type": "agent.interaction.request",
"payload": {
"interaction_id": "String (필수, UUID v4)",
"interaction_type": "String (필수, 아래 열거 값)",
"question_text": "String (필수, 사용자에게 표시할 질문)",
"timeout_sec": "Number (필수, 응답 대기 한계 시간)",
"options": [
{
"value": "String (필수, 시스템 전달용 식별자)",
"label": "String (필수, 사용자 노출용 텍스트)",
"description": "String (선택, 부가 설명)",
"risk_level": "String (선택, 'safe' | 'moderate' | 'dangerous')"
}
],
"context": {
"tool_name": "String (선택, 승인이 필요한 도구명)",
"tool_input": "Object (선택, 도구 입력 요약)",
"affected_paths": ["String (선택, 영향받는 파일 경로 목록)"]
},
"default_value": "String (선택, 타임아웃 시 자동 선택될 값)"
}
}interaction_type 열거 값:
| 값 | 설명 |
|---|---|
YN |
예/아니오 이진 선택 |
SELECT |
다중 옵션 중 단일 선택 |
MULTI_SELECT |
다중 옵션 중 복수 선택 |
TEXT_INPUT |
사용자 자유 텍스트 입력 |
PERMISSION |
도구 실행 권한 승인 (Claude Code의 도구 승인 흐름) |
4.4. 에러 보고
4.4.1. agent.error (Client → Master)
{
"type": "agent.error",
"payload": {
"error_code": "String (필수)",
"message": "String (필수, 휴먼 리더블 에러)",
"severity": "String (필수, 'fatal' | 'error' | 'warning')",
"recoverable": "Boolean (필수, 에이전트가 자체 복구 가능한지 여부)",
"details": {
"module": "String (선택)",
"trace": "String (선택, 스택 트레이스)",
"related_tool": "String (선택, 에러 유발 도구명)",
"related_invocation_id": "String (선택, 에러 유발 도구 호출 ID)"
}
}
}severity가 fatal이면 클라이언트는 프로세스를 정리해야 한다 (MUST). warning이면 세션을 유지한다.
4.5. 파일 전송
4.5.1. agent.file.transfer (양방향)
바이너리는 WSS를 태우지 않고 HTTP 스토리지 URL로 교환한다.
{
"type": "agent.file.transfer",
"payload": {
"transfer_id": "String (필수, UUID v4)",
"direction": "String (필수, 'upload' | 'download')",
"file_url": "String (필수, 스토리지 URI)",
"file_name": "String (필수)",
"mime_type": "String (필수, IANA MIME 타입)",
"size_bytes": "Number (필수)",
"checksum": "String (선택, SHA-256 해시)",
"context": {
"workspace_relative_path": "String (선택, 워크스페이스 기준 상대 경로)",
"related_tool_invocation_id": "String (선택)"
}
}
}4.6. 에이전트 상태 변경
4.6.1. agent.state.changed (Client → Master)
에이전트의 내부 상태 전이를 마스터에 통보한다.
{
"type": "agent.state.changed",
"payload": {
"previous_state": "String (필수)",
"current_state": "String (필수)",
"reason": "String (선택, 전이 사유)"
}
}예약된 상태 값: idle, thinking, tool_calling, awaiting_input, error
확장 상태는 x-{vendor}.{state_name} 형식을 따른다.
4.7. 시스템 상태 알림
에이전트의 내부 시스템 이벤트(API 재시도, 레이트 리밋 대기 등)를 마스터에 전달한다. agent.state.changed(§4.6)와 달리, 상태 전이가 아닌 일시적 상태 알림에 사용된다.
4.7.1. agent.status (Client → Master)
{
"type": "agent.status",
"payload": {
"status_type": "String (필수, 아래 열거 값)",
"message": "String (필수, 휴먼 리더블 상태 메시지)",
"details": "Object (선택, status_type별 상세 정보)"
}
}status_type 열거 값:
| 값 | 설명 | details 구조 |
|---|---|---|
api_retry |
API 호출 재시도 중 | { attempt, max_attempts, delay_ms, error_code, error_message } |
rate_limited |
API 레이트 리밋에 도달하여 대기 중 | { retry_after_ms } |
info |
기타 정보성 상태 알림 | 자유 형식 |
4.7.2. api_retry details 스키마
{
"details": {
"attempt": "Number (필수, 현재 재시도 횟수, 1-based)",
"max_attempts": "Number (필수, 최대 재시도 횟수)",
"delay_ms": "Number (필수, 다음 재시도까지 대기 시간 밀리초)",
"error_code": "String (선택, 재시도 원인 에러 코드. 예: 'overloaded', '529')",
"error_message": "String (선택, 원인 에러 메시지)"
}
}4.7.3. rate_limited details 스키마
{
"details": {
"retry_after_ms": "Number (필수, 레이트 리밋 해제까지 대기 시간 밀리초)"
}
}4.7.4. 규칙
agent.status는 발송 즉시 유효한 일시적 알림이며, 상태 전이를 발생시키지 않는다. 에이전트의current_state(§4.6)는 변경되지 않는다.- 마스터는 이 이벤트를 사용자에게 표시해야 한다 (SHOULD). 예: "API 재시도 중 (2/5, 3초 후)".
api_retry의attempt가max_attempts에 도달한 후에도 실패하면agent.error(§4.4)를 발송해야 한다 (MUST).rate_limited수신 시 마스터는 사용자에게 대기 상태를 시각적으로 표시해야 한다 (SHOULD).