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

스펙

RAWP-DPS

Data processing specification for RAWP integrations.

변경 이력 전체 Markdown 목차 Markdown

17. 에이전트 어댑터 프로토콜 (Agent Adapter Protocol)

에이전트의 실행 방식에 따라 DPS 이벤트의 생성 및 전달 방식이 달라진다. 본 절은 어댑터 유형별로 DPS 프레임과의 계약을 정의한다. 어댑터의 내부 동작 방식은 규정하지 않으며, DPS 프레임 수준의 프로토콜 계약만을 정의한다.

17.1. 어댑터 유형 분류

에이전트 메타데이터(RAWP 1.0.2 §4.3)의 adapter_type 필드로 어댑터 유형을 구분한다:

유형 adapter_type 설명
프로세스 기반 process 별도 자식 프로세스(child process)로 에이전트를 실행. stdio를 통해 통신.
SDK 기반 sdk 클라이언트와 동일 프로세스 내에서 SDK API를 통해 에이전트를 실행.

17.2. 프로세스 어댑터 프로토콜 계약

17.2.1. 환경 변수

프로세스 기반 에이전트 생성 시 다음 환경 변수를 주입해야 한다 (MUST):

환경 변수 값 설명
RAWP_SESSION_ID 세션 식별자 (UUID v4) 에이전트가 자신의 세션을 식별하기 위한 값
RAWP_WORKSPACE_PATH 작업 디렉토리 절대 경로 에이전트의 파일 시스템 작업 기준 경로
RAWP_DPS_VERSION rawp-dps-1.0 사용 중인 DPS 프로토콜 버전

17.2.2. Exit Code → DPS 이벤트 매핑

에이전트 프로세스 종료 시 exit code에 따라 다음 DPS 이벤트를 발송해야 한다 (MUST):

Exit Code 해석 DPS 이벤트
0 정상 종료 session.turn.end (stop_reason: "end_turn")
1–127 에러 종료 agent.error (severity: "fatal") → session.turn.end (stop_reason: "error")
128+N 시그널 N에 의한 종료 agent.error (severity: "fatal", error_code: "SIGNAL_EXIT") → session.turn.end (stop_reason: "error")

예외: single_turn_process: true(§18) 어댑터의 exit code 0은 Turn 완료이며 세션 종료가 아니다. §18.2 참조.

17.2.3. 종료 시그널 순서

RAWP 1.0.2 §5.2의 세션 명시적 종료 시, 프로세스 기반 에이전트에 대한 종료 시그널 순서:

  1. SIGTERM 전송.
  2. 유예 시간(5초) 내 프로세스가 종료되지 않으면 SIGKILL 전송.
  3. 프로세스 종료 확인 후 WSS 정리 프레임 발송(§7.5.3).

17.3. SDK 어댑터 프로토콜 계약

17.3.1. 도구 승인 콜백 브릿지

SDK가 도구 실행 전 사용자 승인을 요구하는 경우, 다음의 DPS 이벤트 시퀀스를 따른다:

SDK 콜백 발생
  → Client: agent.interaction.request (interaction_type: "PERMISSION") 발송
  → Master: control.interaction.response 또는 control.interaction.timeout 발송
  → Client: SDK 콜백에 승인/거부 결과 전달
  • control.interaction.timeout 수신 시 SDK 콜백에 거부를 전달해야 한다 (MUST).
  • agent.interaction.request의 context.tool_name에 승인 대상 도구명을 포함해야 한다 (MUST).

17.3.2. 동시 프롬프트 방지

하나의 세션에서 동시에 진행할 수 있는 에이전트 쿼리(프롬프트 처리)는 최대 1개이다 (MUST). 에이전트가 현재 Turn을 처리 중인 상태(session.turn.start 발송 후 session.turn.end 발송 전)에서 새 control.prompt.request를 수신하면, 클라이언트는 session.error (error_code: "PROMPT_IN_PROGRESS", fatal: false)를 반환하고 해당 프롬프트를 거부해야 한다 (MUST).

17.4. 공통 규칙

  • session.capabilities 교환 시 클라이언트는 현재 세션의 에이전트 어댑터 유형을 마스터에 보고해야 한다 (SHOULD). features 객체에 adapter_type 필드("process" 또는 "sdk")를 포함한다.
  • context_compaction 미지원 어댑터가 control.session.compact를 수신하면 §6.3.1의 미지원 규칙을 따른다.
  • plan_mode 미지원 어댑터가 control.mode.switch를 수신하면 §6.3.2의 미지원 규칙을 따른다.

참조