Claude Code SDK

Claude Code SDK로 맞춤형 AI 에이전트 구축하기

Claude Code SDK를 사용하는 이유는?

Claude Code SDK는 프로덕션 준비 에이전트를 구축하는 데 필요한 모든 구성 요소를 제공합니다:

• 최적화된 Claude 통합: 자동 프롬프트 캐싱 및 성능 최적화
• 풍부한 도구 생태계: 파일 작업, 코드 실행, 웹 검색 및 MCP 확장성
• 고급 권한: 에이전트 기능에 대한 세밀한 제어
• 프로덕션 필수 요소: 내장된 오류 처리, 세션 관리 및 모니터링

SDK로 무엇을 구축할 수 있나요?

다음은 생성할 수 있는 에이전트 유형의 예시입니다:

코딩 에이전트:

• 프로덕션 문제를 진단하고 수정하는 SRE 에이전트
• 코드의 취약점을 감사하는 보안 검토 봇
• 인시던트를 분류하는 온콜 엔지니어링 어시스턴트
• 스타일과 모범 사례를 적용하는 코드 검토 에이전트

비즈니스 에이전트:

• 계약서와 규정 준수를 검토하는 법무 어시스턴트
• 보고서와 예측을 분석하는 재무 어드바이저
• 기술적 문제를 해결하는 고객 지원 에이전트
• 마케팅 팀을 위한 콘텐츠 제작 어시스턴트

SDK는 현재 TypeScript와 Python에서 사용할 수 있으며, 빠른 프로토타이핑을 위한 명령줄 인터페이스(CLI)를 제공합니다.

빠른 시작

5분 안에 첫 번째 에이전트를 실행해보세요:

1. SDK 설치

   명령줄

   NPM에서 @anthropic-ai/claude-code를 설치하세요:

   npm install -g @anthropic-ai/claude-code
   

2. API 키 설정

   Anthropic Console에서 API 키를 받고 ANTHROPIC_API_KEY 환경 변수를 설정하세요:

   export ANTHROPIC_API_KEY="your-api-key-here"
   

3. 첫 번째 에이전트 생성

   다음 예시 에이전트 중 하나를 생성하세요:

   명령줄

   # 간단한 법무 어시스턴트 생성
   claude -p "이 계약 조항의 잠재적 문제점을 검토하세요: '당사자는 무제한 책임에 동의합니다...'" \
     --append-system-prompt "당신은 법무 어시스턴트입니다. 위험을 식별하고 개선 사항을 제안하세요."
   

4. 에이전트 실행

   명령줄

   위의 명령을 터미널에 직접 복사하여 붙여넣으세요.

위의 각 예시는 다음과 같은 작업을 수행하는 작동하는 에이전트를 생성합니다:

• Claude의 추론 능력을 사용하여 프롬프트 분석
• 문제를 해결하기 위한 다단계 접근법 계획
• 파일 작업, bash 명령, 웹 검색과 같은 도구를 사용하여 작업 실행
• 분석을 바탕으로 실행 가능한 권장 사항 제공

핵심 사용법

개요

Claude Code SDK를 사용하면 애플리케이션에서 비대화형 모드로 Claude Code와 인터페이스할 수 있습니다.

명령줄

전제 조건

• Node.js 18+
• NPM의 @anthropic-ai/claude-code

기본 사용법

Claude Code의 주요 명령줄 인터페이스는 claude 명령입니다. --print(또는 -p) 플래그를 사용하여 비대화형 모드로 실행하고 최종 결과를 출력하세요:

claude -p "시스템 성능 분석" \
  --append-system-prompt "당신은 성능 엔지니어입니다" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

구성

SDK는 Claude Code에서 사용할 수 있는 모든 CLI 옵션을 활용합니다. SDK 사용을 위한 주요 옵션은 다음과 같습니다:

플래그	설명	예시
--print, -p	비대화형 모드로 실행	claude -p "쿼리"
--output-format	출력 형식 지정 (text, json, stream-json)	claude -p --output-format json
--resume, -r	세션 ID로 대화 재개	claude --resume abc123
--continue, -c	가장 최근 대화 계속	claude --continue
--verbose	자세한 로깅 활성화	claude --verbose
--append-system-prompt	시스템 프롬프트에 추가 (--print와 함께만 사용)	claude --append-system-prompt "사용자 지정 지침"
--allowedTools	허용된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 허용된 도구의 문자열 목록	claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedTools	거부된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 거부된 도구의 문자열 목록	claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-config	JSON 파일에서 MCP 서버 로드	claude --mcp-config servers.json
--permission-prompt-tool	권한 프롬프트 처리를 위한 MCP 도구 (--print와 함께만 사용)	claude --permission-prompt-tool mcp__auth__prompt

CLI 옵션과 기능의 전체 목록은 CLI 참조 문서를 참조하세요.

인증

Anthropic API 키

기본 인증의 경우 Anthropic Console에서 Anthropic API 키를 검색하고 빠른 시작에서 설명한 대로 ANTHROPIC_API_KEY 환경 변수를 설정하세요.

타사 API 자격 증명

SDK는 타사 API 제공업체를 통한 인증도 지원합니다:

• Amazon Bedrock: CLAUDE_CODE_USE_BEDROCK=1 환경 변수를 설정하고 AWS 자격 증명을 구성하세요
• Google Vertex AI: CLAUDE_CODE_USE_VERTEX=1 환경 변수를 설정하고 Google Cloud 자격 증명을 구성하세요

타사 제공업체에 대한 자세한 구성 지침은 Amazon Bedrock 및 Google Vertex AI 문서를 참조하세요.

다중 턴 대화

다중 턴 대화의 경우 대화를 재개하거나 가장 최근 세션에서 계속할 수 있습니다:

명령줄

# 가장 최근 대화 계속
claude --continue "이제 더 나은 성능을 위해 리팩토링하세요"

# 세션 ID로 특정 대화 재개
claude --resume 550e8400-e29b-41d4-a716-446655440000 "테스트를 업데이트하세요"

# 비대화형 모드로 재개
claude --resume 550e8400-e29b-41d4-a716-446655440000 "모든 린팅 문제를 수정하세요" --no-interactive

계획 모드 사용

계획 모드를 사용하면 Claude가 수정 없이 코드를 분석할 수 있어 코드 검토 및 변경 계획에 유용합니다.

명령줄

claude -p "이 코드를 검토하세요" --permission-mode plan

계획 모드는 편집, 파일 생성 및 명령 실행을 제한합니다. 자세한 내용은 권한 모드를 참조하세요.

사용자 정의 시스템 프롬프트

시스템 프롬프트는 에이전트의 역할, 전문성 및 행동을 정의합니다. 여기서 구축하고 있는 에이전트의 종류를 지정합니다:

명령줄

# SRE 인시던트 대응 에이전트
claude -p "API가 다운되었습니다. 조사하세요" \
  --append-system-prompt "당신은 SRE 전문가입니다. 문제를 체계적으로 진단하고 실행 가능한 솔루션을 제공하세요."

# 법무 문서 검토 에이전트  
claude -p "이 계약서를 검토하세요" \
  --append-system-prompt "당신은 기업 변호사입니다. 위험을 식별하고 개선 사항을 제안하며 규정 준수를 보장하세요."

# 기본 시스템 프롬프트에 추가
claude -p "이 함수를 리팩토링하세요" \
  --append-system-prompt "항상 포괄적인 오류 처리와 단위 테스트를 포함하세요."

고급 사용법

MCP를 통한 사용자 정의 도구

Model Context Protocol(MCP)을 사용하면 에이전트에게 사용자 정의 도구와 기능을 제공할 수 있습니다. 이는 도메인별 통합이 필요한 전문 에이전트를 구축하는 데 중요합니다.

예시 에이전트 도구 구성:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "your-slack-token"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "your-jira-token"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "your-db-url"}
    }
  }
}

사용 예시:

명령줄

# 모니터링 도구를 사용한 SRE 에이전트
claude -p "결제 서비스 장애를 조사하세요" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "당신은 SRE입니다. 모니터링 데이터를 사용하여 문제를 진단하세요."

# CRM 액세스를 사용한 고객 지원 에이전트
claude -p "고객 티켓 #12345 해결을 도와주세요" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "당신은 기술 지원 전문가입니다."

MCP 도구를 사용할 때는 --allowedTools 플래그를 사용하여 명시적으로 허용해야 합니다. MCP 도구 이름은 mcp__<serverName>__<toolName> 패턴을 따릅니다. 여기서:

• serverName은 MCP 구성 파일의 키입니다
• toolName은 해당 서버에서 제공하는 특정 도구입니다

이 보안 조치는 MCP 도구가 명시적으로 허용된 경우에만 사용되도록 보장합니다.

서버 이름만 지정하면(즉, mcp__<serverName>), 해당 서버의 모든 도구가 허용됩니다.

글로브 패턴(예: mcp__go*)은 지원되지 않습니다.

사용자 정의 권한 프롬프트 도구

선택적으로 --permission-prompt-tool을 사용하여 사용자가 모델에 특정 도구 호출 권한을 부여하는지 확인하는 데 사용할 MCP 도구를 전달할 수 있습니다. 모델이 도구를 호출할 때 다음과 같은 일이 발생합니다:

1. 먼저 권한 설정을 확인합니다: 모든 settings.json 파일과 SDK에 전달된 --allowedTools 및 --disallowedTools; 이 중 하나가 도구 호출을 허용하거나 거부하면 도구 호출을 진행합니다
2. 그렇지 않으면 --permission-prompt-tool에서 제공한 MCP 도구를 호출합니다

--permission-prompt-tool MCP 도구는 도구 이름과 입력을 전달받고 결과와 함께 JSON 문자열화된 페이로드를 반환해야 합니다. 페이로드는 다음 중 하나여야 합니다:

// 도구 호출이 허용됨
{
  "behavior": "allow",
  "updatedInput": {...}, // 업데이트된 입력, 또는 원래 입력을 그대로 반환
}

// 도구 호출이 거부됨
{
  "behavior": "deny",
  "message": "..." // 권한이 거부된 이유를 설명하는 사람이 읽을 수 있는 문자열
}

구현 예시:

명령줄

# MCP 서버 구성과 함께 사용
claude -p "보안 문제를 분석하고 수정하세요" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# 사용자 정의 권한 규칙과 함께
claude -p "코드베이스를 리팩토링하세요" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

사용 참고사항:

• updatedInput을 사용하여 권한 프롬프트가 입력을 변경했음을 모델에 알리세요. 그렇지 않으면 위 예시와 같이 updatedInput을 원래 입력으로 설정하세요. 예를 들어, 도구가 사용자에게 파일 편집 차이를 보여주고 사용자가 차이를 수동으로 편집할 수 있게 하는 경우, 권한 프롬프트 도구는 업데이트된 편집을 반환해야 합니다.
• 페이로드는 JSON 문자열화되어야 합니다

출력 형식

SDK는 여러 출력 형식을 지원합니다:

텍스트 출력 (기본값)

명령줄

claude -p "src/components/Header.tsx 파일을 설명하세요"
# 출력: 이것은 다음을 보여주는 React 컴포넌트입니다...

JSON 출력

메타데이터를 포함한 구조화된 데이터를 반환합니다:

명령줄

claude -p "데이터 레이어는 어떻게 작동하나요?" --output-format json

응답 형식:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "여기에 응답 텍스트...",
  "session_id": "abc123"
}

스트리밍 JSON 출력

수신되는 각 메시지를 스트리밍합니다:

$ claude -p "애플리케이션을 구축하세요" --output-format stream-json

각 대화는 초기 init 시스템 메시지로 시작하고, 사용자 및 어시스턴트 메시지 목록이 이어지며, 통계가 포함된 최종 result 시스템 메시지로 끝납니다. 각 메시지는 별도의 JSON 객체로 방출됩니다.

메시지 스키마

JSON API에서 반환되는 메시지는 다음 스키마에 따라 엄격하게 타입이 지정됩니다:

type SDKMessage =
  // 어시스턴트 메시지
  | {
      type: "assistant";
      message: Message; // Anthropic SDK에서
      session_id: string;
    }

  // 사용자 메시지
  | {
      type: "user";
      message: MessageParam; // Anthropic SDK에서
      session_id: string;
    }

  // 마지막 메시지로 방출됨
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // 최대 턴 수에 도달했을 때 마지막 메시지로 방출됨
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // 대화 시작 시 첫 번째 메시지로 방출됨
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

곧 이러한 타입을 JSONSchema 호환 형식으로 게시할 예정입니다. 이 형식에 대한 주요 변경 사항을 전달하기 위해 주요 Claude Code 패키지에 대해 시맨틱 버전 관리를 사용합니다.

Message 및 MessageParam 타입은 Anthropic SDK에서 사용할 수 있습니다. 예를 들어, Anthropic TypeScript 및 Python SDK를 참조하세요.

입력 형식

SDK는 여러 입력 형식을 지원합니다:

텍스트 입력 (기본값)

명령줄

# 직접 인수
claude -p "이 코드를 설명하세요"

# stdin에서
echo "이 코드를 설명하세요" | claude -p

스트리밍 JSON 입력

각 메시지가 사용자 턴을 나타내는 stdin을 통해 제공되는 메시지 스트림입니다. 이를 통해 claude 바이너리를 다시 실행하지 않고도 대화의 여러 턴을 수행할 수 있으며, 모델이 요청을 처리하는 동안 지침을 제공할 수 있습니다.

각 메시지는 출력 메시지 스키마와 동일한 형식을 따르는 JSON ‘사용자 메시지’ 객체입니다. 메시지는 각 입력 줄이 완전한 JSON 객체인 jsonl 형식을 사용하여 형식화됩니다. 스트리밍 JSON 입력에는 -p와 --output-format stream-json이 필요합니다.

현재 이는 텍스트 전용 사용자 메시지로 제한됩니다.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"이 코드를 설명하세요"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

에이전트 통합 예시

SRE 인시던트 대응 봇

명령줄

#!/bin/bash

# 자동화된 인시던트 대응 에이전트
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "인시던트: $incident_description (심각도: $severity)" \
      --append-system-prompt "당신은 SRE 전문가입니다. 문제를 진단하고 영향을 평가하며 즉각적인 조치 항목을 제공하세요." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# 사용법
investigate_incident "결제 API가 500 오류를 반환합니다" "high"

자동화된 보안 검토

명령줄

# 풀 리퀘스트용 보안 감사 에이전트
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "당신은 보안 엔지니어입니다. 이 PR의 취약점, 안전하지 않은 패턴 및 규정 준수 문제를 검토하세요." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# 사용법 및 파일로 저장
audit_pr 123 > security-report.json

다중 턴 법무 어시스턴트

명령줄

# 세션 지속성을 사용한 법무 문서 검토
session_id=$(claude -p "법무 검토 세션을 시작하세요" --output-format json | jq -r '.session_id')

# 여러 단계로 계약서 검토
claude -p --resume "$session_id" "contract.pdf의 책임 조항을 검토하세요"
claude -p --resume "$session_id" "GDPR 요구 사항 준수를 확인하세요" 
claude -p --resume "$session_id" "위험의 경영진 요약을 생성하세요"

Python 전용 모범 사례

주요 패턴

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# 항상 컨텍스트 매니저 사용
async with ClaudeSDKClient() as client:
    await client.query("이 코드를 분석하세요")
    async for msg in client.receive_response():
        # 스트리밍 메시지 처리
        pass

# 여러 에이전트를 동시에 실행
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("main.py를 검토하세요"),
        tester.query("main.py용 테스트를 작성하세요")
    )

# 오류 처리
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # 여기에 코드
        pass
except CLINotFoundError:
    print("CLI 설치: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"프로세스 오류: {e}")

# 메타데이터와 함께 전체 응답 수집
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

IPython/Jupyter 팁

# Jupyter에서 셀에서 직접 await 사용
client = ClaudeSDKClient()
await client.connect()
await client.query("data.csv를 분석하세요")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# 재사용 가능한 헬퍼 함수 생성
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

모범 사례

• 프로그래밍 방식의 응답 파싱을 위해 JSON 출력 형식 사용:

  # jq로 JSON 응답 파싱
  result=$(claude -p "코드 생성" --output-format json)
  code=$(echo "$result" | jq -r '.result')
  cost=$(echo "$result" | jq -r '.cost_usd')
  

• 오류를 우아하게 처리 - 종료 코드와 stderr 확인:

  if ! claude -p "$prompt" 2>error.log; then
      echo "오류가 발생했습니다:" >&2
      cat error.log >&2
      exit 1
  fi
  

• 다중 턴 대화에서 컨텍스트를 유지하기 위해 세션 관리 사용

• 장시간 실행되는 작업에 대해 타임아웃 고려:

  timeout 300 claude -p "$complex_prompt" || echo "5분 후 타임아웃"
  

• 여러 요청을 할 때 호출 사이에 지연을 추가하여 속도 제한 준수

관련 리소스

• CLI 사용법 및 제어 - 완전한 CLI 문서
• GitHub Actions 통합 - Claude로 GitHub 워크플로우 자동화
• 일반적인 워크플로우 - 일반적인 사용 사례에 대한 단계별 가이드