스펙들 3
탐색 1.0.1 문서
버전
문서 변경 이력
섹션 20
현재 페이지 9
1.0.1 ko public

스펙

RAWP-DPS

Data processing specification for RAWP integrations.

변경 이력 전체 Markdown 목차 Markdown

5. 도구 호출 이벤트 (tool.*)

에이전트가 도구(Tool)를 호출하고 그 결과를 보고하는 이벤트 군이다. Claude Code의 Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS, WebFetch, WebSearch, NotebookRead, NotebookEdit, TodoRead, TodoWrite, Task(Subagent) 등 모든 도구 호출을 통일된 구조로 표현한다.

5.1. 설계 원칙

도구 호출 이벤트는 도구 비종속(Tool-Agnostic) 설계를 따른다. 즉, 프로토콜은 도구의 이름, 입력 스키마, 출력 형태를 사전에 정의하지 않으며, 임의의 도구를 동일한 Envelope으로 수용한다. 도구별 의미론은 tool_name과 input/output 필드의 내용으로 결정된다.

5.2. 도구 호출 요청

5.2.1. tool.invoke.request (Client → Master)

에이전트가 도구를 호출하려 함을 마스터에 통보한다. 승인이 필요한 도구의 경우 agent.interaction.request가 선행한다.

{
  "type": "tool.invoke.request",
  "payload": {
    "invocation_id": "String (필수, UUID v4, 이 호출의 고유 식별자)",
    "tool_name": "String (필수, 도구명. 예: 'Bash', 'Read', 'Edit', 'TodoWrite')",
    "tool_version": "String (선택, 도구 버전)",
    "input": "Object (필수, 도구별 입력 파라미터)",
    "parallel_group_id": "String (선택, 병렬 호출 그룹 ID. 동시에 발송되는 도구 호출을 그룹화)"
  }
}

5.3. 도구 실행 결과

5.3.1. tool.invoke.result (Client → Master)

도구 실행이 완료된 후 결과를 보고한다.

{
  "type": "tool.invoke.result",
  "payload": {
    "invocation_id": "String (필수, 대응하는 tool.invoke.request의 invocation_id)",
    "tool_name": "String (필수)",
    "status": "String (필수, 'success' | 'error' | 'timeout' | 'cancelled')",
    "output": "Any (필수, 도구별 출력. 구조는 도구 의존적)",
    "output_type": "String (필수, 출력 해석 힌트. 아래 열거 값)",
    "duration_ms": "Number (선택, 실행 소요 시간 밀리초)",
    "truncated": "Boolean (선택, 출력이 잘렸는지 여부)"
  }
}

output_type 열거 값:

값 설명 대표 도구
text 평문 텍스트 Bash stdout, Grep 결과
structured JSON 구조체 TodoRead, Agent Discovery
file_content 파일 본문 (라인 번호 포함 가능) Read, NotebookRead
file_list 파일 경로 목록 Glob, LS
diff 변경사항 차분 (unified diff 또는 구조화 diff) Edit, MultiEdit 결과
web_content 웹 페이지/검색 결과 WebFetch, WebSearch
empty 출력 없음 (부수효과만 발생) Write, NotebookEdit
binary_ref 바이너리 참조 (agent.file.transfer 연계) 이미지 생성 등
agent_result 서브에이전트 실행 결과 Task(Subagent)

5.3.2. tool.invoke.stream (Client → Master)

장시간 실행 도구의 중간 출력을 스트리밍한다 (예: Bash 명령의 실시간 stdout).

{
  "type": "tool.invoke.stream",
  "payload": {
    "invocation_id": "String (필수)",
    "tool_name": "String (필수)",
    "stream_type": "String (필수, 'stdout' | 'stderr' | 'progress')",
    "chunk": "String (필수, 출력 조각)",
    "sequence": "Number (필수, 0-based 순번, 순서 재구성용)"
  }
}

5.3.3. output_type 결정 규칙

tool.invoke.result의 output_type 값은 다음 우선순위에 따라 결정해야 한다 (MUST):

  1. 도구 카탈로그 사전 선언: tool.catalog.publish(§5.4.1)에서 해당 도구의 output_type이 사전 선언된 경우, 해당 값을 사용한다. 이것이 최우선이다.
  2. 도구 카테고리 기반 기본값: 사전 선언이 없으면, tool.catalog.publish의 category 필드에 따른 기본값을 적용한다:
category 도구 동작 기본 output_type
filesystem 파일 쓰기/수정 (Write, Edit, MultiEdit) diff (변경 발생 시) 또는 empty
filesystem 파일 읽기 (Read, NotebookRead) file_content
filesystem 파일 탐색 (Glob, LS) file_list
shell 셸 명령 실행 (Bash) text
search 검색 (Grep, WebSearch) text 또는 file_list
web 웹 콘텐츠 접근 (WebFetch) web_content
task_management 태스크 관리 (TodoRead, TodoWrite) structured
agent 서브에이전트 위임 (Task) agent_result
  1. 폴백: 위 규칙으로 결정할 수 없으면 text로 설정한다 (MUST).

output_type은 수신 측(마스터, 엣지 노드)이 결과를 적절한 뷰어로 렌더링하기 위한 힌트이다. 각 output_type의 렌더링 규칙은 RAWP-CRS 1.0.1 §4.5를 참조한다.

5.4. 도구 사용 가능 목록 고지 (Tool Catalog)

5.4.1. tool.catalog.publish (Client → Master)

에이전트가 현재 세션에서 사용 가능한 도구 목록을 마스터에 고지한다. 세션 시작 직후 또는 도구 구성 변경 시 발송한다.

{
  "type": "tool.catalog.publish",
  "payload": {
    "tools": [
      {
        "name": "String (필수, 도구명)",
        "version": "String (선택)",
        "description": "String (필수, 도구 설명)",
        "input_schema": "Object (선택, JSON Schema)",
        "output_type": "String (선택, 기본 output_type)",
        "requires_approval": "Boolean (선택, 실행 전 승인 필요 여부)",
        "category": "String (선택, 도구 분류. 아래 열거 값)",
        "status": "String (선택, 기본값 'available'. 아래 열거 값)",
        "status_description": "String (선택, 현재 상태에 대한 사유 설명. 없으면 UI에 상태 사유를 표시하지 않는다)"
      }
    ],
    "diagnostics": [
      {
        "severity": "String (필수, 'info' | 'warning' | 'error' | 'fatal')",
        "tool_name": "String (선택, 특정 도구에 관한 진단이면 해당 도구명)",
        "code": "String (필수, 진단 코드. 예: 'TOOL_UNAVAILABLE', 'VERSION_MISMATCH', 'DEPENDENCY_MISSING')",
        "message": "String (필수, 휴먼 리더블 진단 메시지)"
      }
    ]
  }
}

category 열거 값:

값 설명 예시
filesystem 파일 시스템 조작 Read, Write, Edit, MultiEdit, Glob, LS
shell 셸 명령 실행 Bash
search 검색 Grep, WebSearch
web 웹 콘텐츠 접근 WebFetch
notebook 노트북 조작 NotebookRead, NotebookEdit
task_management 태스크/TODO 관리 TodoRead, TodoWrite
agent 서브에이전트 위임 Task
planning 계획 모드 EnterPlanMode, ExitPlanMode
mcp MCP 서버 도구 동적 MCP 도구
custom 사용자 정의 도구 커스텀 도구

status 열거 값:

값 설명
available 도구가 정상 동작 가능. 기본값. status 필드가 생략되면 available로 간주한다.
unavailable 도구를 사용할 수 없음. 의존성 누락, 권한 부족, 실행 파일 미설치 등. 마스터는 이 도구에 대한 tool.invoke.request 발송을 차단해야 한다 (MUST).
degraded 도구가 동작하지만 일부 기능이 제한됨. 사용은 허용되나 사용자에게 제한 사항을 고지해야 한다 (SHOULD).

status가 unavailable 또는 degraded인 도구는 status_description에 사유를 명시하는 것을 권장한다 (SHOULD). 예: "실행 파일을 찾을 수 없음", "API 키 미설정". status_description이 없으면 UI에 상태 사유를 표시하지 않는다.

도구 구성이 변경되어 status가 전이되면(예: 의존성 설치로 unavailable → available) 클라이언트는 tool.catalog.publish를 재발송해야 한다 (MUST).

diagnostics 필드 규칙:

  • diagnostics 배열은 선택적이다 (OPTIONAL). 진단 사항이 없으면 생략하거나 빈 배열을 전송할 수 있다.
  • severity: "fatal" 진단이 포함된 도구는 마스터가 해당 도구의 사용을 차단해야 한다 (MUST). 해당 도구에 대한 tool.invoke.request가 수신되면 session.error를 반환한다.
  • severity: "error" 진단이 포함된 도구는 마스터가 사용자에게 경고를 표시해야 한다 (SHOULD). 도구 사용 자체는 허용된다.
  • severity: "warning" 또는 "info" 진단은 로그 기록 또는 UI 표시용이며, 도구 사용에 제한을 두지 않는다.
  • tool_name이 생략된 진단은 도구 카탈로그 전체에 대한 진단이다 (예: 에이전트 초기화 경고).

참조