AX-Copilot/docs/claude-code-docs-main/20_SDK개요.md

SDK 개요

stdin/stdout 제어 프로토콜을 사용해 자체 도구에 Claude Code를 임베드하는 방법. SDK 세션 API, 메시지 타입, 출력 형식에 대한 레퍼런스.

Claude Code SDK는 다른 애플리케이션에 Claude Code를 임베드하기 위한 제어 프로토콜입니다 — IDE, 자동화 스크립트, CI/CD 파이프라인, 또는 서브프로세스를 스폰하고 stdin/stdout으로 통신할 수 있는 모든 호스트.

라이브러리 API를 직접 노출하는 대신, 구조화된 JSON 메시지 스트림을 통해 실행 중인 claude 프로세스와 통신합니다. 호스트 프로세스가 사용자 메시지와 제어 요청을 전송하면 CLI 프로세스가 어시스턴트 메시지, 도구 진행 이벤트, 결과 페이로드를 스트리밍합니다.

작동 방식

1. Claude Code 프로세스 스폰 — --output-format stream-json과 --print로 시작 (비대화형 모드). stdin과 stdout을 호스트 프로세스로 파이핑.

claude --output-format stream-json --print --verbose

여러 프롬프트를 받는 영속 세션은 --print를 생략하고 세션 초기화 후 stdin에 SDKUserMessage 객체를 전송합니다.

2. 초기화 요청 전송 — stdin에 control_request (subtype: "initialize") 작성. CLI가 SDKControlInitializeResponse로 응답합니다.

3. stdout에서 메시지 스트리밍 — stdout에서 줄바꿈으로 구분된 JSON 읽기. 각 줄이 SDKMessage 유니온 타입 중 하나입니다.

4. 사용자 메시지 전송 — 대화를 계속하려면 stdin에 SDKUserMessage 객체 작성.

출력 형식

형식	설명
text	일반 텍스트 응답만. 대화형 모드의 기본값
json	완료 시 작성되는 단일 JSON 객체. 일회성 스크립트에 적합
stream-json	줄바꿈으로 구분된 JSON 스트림. 이벤트 발생 시 줄당 하나의 메시지. SDK 사용에 필수

제어 프로토콜 메시지

제어 프로토콜은 stdin/stdout에서 양방향으로 흐르는 두 가지 최상위 봉투 타입을 사용합니다.

SDKControlRequest (호스트 → CLI)

{
  "type": "control_request",
  "request_id": "<고유-문자열>",
  "request": { "subtype": "...", ...페이로드 }
}

SDKControlResponse (CLI → 호스트)

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "<에코된-id>",
    "response": { ...페이로드 }
  }
}

오류 시 subtype은 "error"이고 error 필드에 메시지가 포함됩니다.

초기화 요청

initialize 요청은 반드시 먼저 보내야 합니다. 세션을 설정하고 사용 가능한 기능을 반환합니다.

{
  "type": "control_request",
  "request_id": "init-1",
  "request": {
    "subtype": "initialize",
    "systemPrompt": "당신은 CI 자동화 에이전트입니다.",
    "appendSystemPrompt": "항상 테스트 커버리지를 추가하세요.",
    "hooks": {
      "PreToolUse": [
        {
          "matcher": "Bash",
          "hookCallbackIds": ["my-hook-id"]
        }
      ]
    },
    "agents": {
      "CodeReviewer": {
        "description": "코드 품질과 보안을 검토합니다.",
        "prompt": "당신은 전문 코드 리뷰어입니다...",
        "model": "opus"
      }
    }
  }
}

초기화 응답

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "init-1",
    "response": {
      "commands": [...],
      "agents": [...],
      "output_style": "stream-json",
      "models": [...],
      "account": {
        "email": "user@example.com",
        "organization": "Acme Corp",
        "apiProvider": "firstParty"
      }
    }
  }
}

사용자 메시지

{
  "type": "user",
  "message": {
    "role": "user",
    "content": "이 함수를 async/await으로 리팩터링해줘."
  },
  "parent_tool_use_id": null
}

• parent_tool_use_id: 이 메시지가 응답하는 도구 사용 ID, 최상위 사용자 메시지는 null
• priority: 'now' | 'next' | 'later' — 비동기 메시지 큐잉 스케줄링 힌트

SDK 메시지 스트림 타입

타입	설명
system (subtype: "init")	세션 시작 시 한 번 출력. 활성 모델, 도구 목록, MCP 서버 상태, 권한 모드, 세션 ID 포함
assistant	모델이 턴을 생성할 때 출력. tool_use 블록 포함 가능
stream_event	스트리밍 중 부분 토큰 출력. 점진적 렌더링에 사용
tool_progress	몇 초 이상 걸리는 도구의 주기적 상태 업데이트
result	각 턴 종료 시 출력. subtype은 "success" 또는 오류 서브타입

result 예시:

{
  "type": "result",
  "subtype": "success",
  "result": "함수가 리팩터링되었습니다.",
  "duration_ms": 4200,
  "total_cost_usd": 0.0042,
  "num_turns": 3,
  "is_error": false,
  "session_id": "abc123"
}

기타 제어 요청

subtype	방향	설명
interrupt	호스트 → CLI	현재 턴 중단
set_permission_mode	호스트 → CLI	활성 권한 모드 변경
set_model	호스트 → CLI	세션 중간에 모델 전환
can_use_tool	CLI → 호스트	도구 호출 권한 요청
mcp_status	호스트 → CLI	MCP 서버 연결 상태 가져오기
get_context_usage	호스트 → CLI	컨텍스트 윈도우 사용량 가져오기
rewind_files	호스트 → CLI	특정 메시지 이후 파일 변경 사항 되돌리기
hook_callback	CLI → 호스트	SDK에 등록된 훅 이벤트 전달

세션 관리 API

스크립팅 시나리오를 위해 SDK가 ~/.claude/에 저장된 세션 트랜스크립트를 조작하는 함수를 내보냅니다:

import {
  query,
  listSessions,
  getSessionInfo,
  getSessionMessages,
  forkSession,
  renameSession,
  tagSession,
} from '@anthropic-ai/claude-code'

query — 프롬프트 실행 (주요 SDK 진입점):

for await (const message of query({
  prompt: '이 디렉토리에 어떤 파일이 있나요?',
  options: { cwd: '/my/project' }
})) {
  if (message.type === 'result') {
    console.log(message.result)
  }
}

listSessions — 저장된 세션 목록:

const sessions = await listSessions({ dir: '/my/project', limit: 50 })

getSessionMessages — 트랜스크립트 읽기:

const messages = await getSessionMessages(sessionId, {
  dir: '/my/project',
  includeSystemMessages: false,
})

forkSession — 대화 분기:

const { sessionId: newId } = await forkSession(originalSessionId, {
  upToMessageId: 'msg-uuid',
  title: '실험적 분기',
})

사용 사례

IDE 통합: IDE가 영속 Claude Code 프로세스를 스폰하고 제어 프로토콜을 통해 메시지를 라우팅합니다. PreToolUse 훅 콜백으로 파일 편집을 가로채 적용 전에 IDE 네이티브 UI에 diff를 표시합니다.

CI/CD 자동화:

result=$(echo "diff를 검토하고 pass/fail을 출력해줘" | \
  claude --output-format json --print \
         --permission-mode bypassPermissions)

헤드리스 에이전트: TypeScript SDK에서 스트리밍 출력 형식으로 query()를 사용합니다. 지속 데몬 프로세스를 유지하면서 크론 스케줄로 작업을 실행합니다.