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} 형식을 따른다.