230 lines
7.4 KiB
Markdown
230 lines
7.4 KiB
Markdown
# 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을 호스트 프로세스로 파이핑.
|
|
|
|
```bash
|
|
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)
|
|
|
|
```json
|
|
{
|
|
"type": "control_request",
|
|
"request_id": "<고유-문자열>",
|
|
"request": { "subtype": "...", ...페이로드 }
|
|
}
|
|
```
|
|
|
|
### `SDKControlResponse` (CLI → 호스트)
|
|
|
|
```json
|
|
{
|
|
"type": "control_response",
|
|
"response": {
|
|
"subtype": "success",
|
|
"request_id": "<에코된-id>",
|
|
"response": { ...페이로드 }
|
|
}
|
|
}
|
|
```
|
|
|
|
오류 시 `subtype`은 `"error"`이고 `error` 필드에 메시지가 포함됩니다.
|
|
|
|
## 초기화 요청
|
|
|
|
`initialize` 요청은 반드시 먼저 보내야 합니다. 세션을 설정하고 사용 가능한 기능을 반환합니다.
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 초기화 응답
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 사용자 메시지
|
|
|
|
```json
|
|
{
|
|
"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 예시:**
|
|
```json
|
|
{
|
|
"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/`에 저장된 세션 트랜스크립트를 조작하는 함수를 내보냅니다:
|
|
|
|
```typescript
|
|
import {
|
|
query,
|
|
listSessions,
|
|
getSessionInfo,
|
|
getSessionMessages,
|
|
forkSession,
|
|
renameSession,
|
|
tagSession,
|
|
} from '@anthropic-ai/claude-code'
|
|
```
|
|
|
|
**`query` — 프롬프트 실행 (주요 SDK 진입점):**
|
|
```typescript
|
|
for await (const message of query({
|
|
prompt: '이 디렉토리에 어떤 파일이 있나요?',
|
|
options: { cwd: '/my/project' }
|
|
})) {
|
|
if (message.type === 'result') {
|
|
console.log(message.result)
|
|
}
|
|
}
|
|
```
|
|
|
|
**`listSessions` — 저장된 세션 목록:**
|
|
```typescript
|
|
const sessions = await listSessions({ dir: '/my/project', limit: 50 })
|
|
```
|
|
|
|
**`getSessionMessages` — 트랜스크립트 읽기:**
|
|
```typescript
|
|
const messages = await getSessionMessages(sessionId, {
|
|
dir: '/my/project',
|
|
includeSystemMessages: false,
|
|
})
|
|
```
|
|
|
|
**`forkSession` — 대화 분기:**
|
|
```typescript
|
|
const { sessionId: newId } = await forkSession(originalSessionId, {
|
|
upToMessageId: 'msg-uuid',
|
|
title: '실험적 분기',
|
|
})
|
|
```
|
|
|
|
## 사용 사례
|
|
|
|
**IDE 통합:** IDE가 영속 Claude Code 프로세스를 스폰하고 제어 프로토콜을 통해 메시지를 라우팅합니다. `PreToolUse` 훅 콜백으로 파일 편집을 가로채 적용 전에 IDE 네이티브 UI에 diff를 표시합니다.
|
|
|
|
**CI/CD 자동화:**
|
|
```bash
|
|
result=$(echo "diff를 검토하고 pass/fail을 출력해줘" | \
|
|
claude --output-format json --print \
|
|
--permission-mode bypassPermissions)
|
|
```
|
|
|
|
**헤드리스 에이전트:** TypeScript SDK에서 스트리밍 출력 형식으로 `query()`를 사용합니다. 지속 데몬 프로세스를 유지하면서 크론 스케줄로 작업을 실행합니다.
|