Claude Code Agent SDK란

Claude Code Agent SDK는 Anthropic이 공개한 Python/TypeScript 라이브러리로, Claude Code의 에이전트 기능을 프로그래밍 방식으로 활용할 수 있습니다. 파일 읽기/쓰기, 코드 실행, 웹 검색 등 Claude Code의 내장 도구를 그대로 사용하면서 커스텀 워크플로를 구성할 수 있습니다.

설치 및 기본 설정

Python SDK 설치

# pip으로 설치
pip install claude-code-sdk

# 필수: Claude Code CLI가 설치되어 있어야 함
npm install -g @anthropic-ai/claude-code

TypeScript SDK 설치

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

Python SDK 기본 사용법

import asyncio
from claude_code_sdk import query, ClaudeCodeOptions, Message

async def main():
    messages: list[Message] = []

    # Claude Code에 질의
    async for event in query(
        prompt="src/ 폴더의 Python 파일 중 테스트가 없는 함수를 찾아줘",
        options=ClaudeCodeOptions(
            max_turns=10,
            system_prompt="당신은 코드 품질 검사 전문가입니다.",
        ),
    ):
        if event.type == "assistant":
            for block in event.message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif event.type == "result":
            print(f"\n--- 완료 (비용: ${event.cost_usd:.4f}) ---")
            messages = event.messages

asyncio.run(main())

TypeScript SDK 기본 사용법

import { query, ClaudeCodeOptions } from '@anthropic-ai/claude-code-sdk';

async function main() {
  const options: ClaudeCodeOptions = {
    maxTurns: 10,
    systemPrompt: '당신은 코드 리뷰 전문가입니다.',
  };

  for await (const event of query({
    prompt: 'package.json의 의존성 중 보안 취약점이 있는지 확인해줘',
    options,
  })) {
    if (event.type === 'assistant') {
      for (const block of event.message.content) {
        if ('text' in block) {
          console.log(block.text);
        }
      }
    }
  }
}

main();

멀티턴 대화

import asyncio
from claude_code_sdk import query, ClaudeCodeOptions

async def multi_turn():
    conversation = []

    # 1단계: 코드 분석
    async for event in query(
        prompt="src/auth.py의 보안 취약점을 분석해줘",
        options=ClaudeCodeOptions(max_turns=5),
    ):
        if event.type == "result":
            conversation = event.messages

    # 2단계: 이전 대화를 이어서 수정 요청
    async for event in query(
        prompt="발견된 취약점 중 가장 심각한 것부터 수정해줘",
        options=ClaudeCodeOptions(
            max_turns=10,
            resume=conversation,  # 이전 대화 이어서
        ),
    ):
        if event.type == "assistant":
            for block in event.message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(multi_turn())

커스텀 도구(MCP) 연동

from claude_code_sdk import query, ClaudeCodeOptions

# MCP 서버를 통한 커스텀 도구 사용
options = ClaudeCodeOptions(
    max_turns=15,
    mcp_servers={
        "database": {
            "command": "npx",
            "args": ["-y", "@my/db-mcp-server"],
            "env": {"DB_URL": "postgresql://localhost/mydb"}
        },
        "slack": {
            "command": "npx",
            "args": ["-y", "@my/slack-mcp-server"],
            "env": {"SLACK_TOKEN": "xoxb-..."}
        }
    }
)

CLAUDE.md로 에이전트 동작 제어

프로젝트 루트에 CLAUDE.md를 배치하면 SDK로 실행하는 에이전트에도 동일하게 적용됩니다.

# CLAUDE.md 예시
## 규칙
- TypeScript 사용 시 strict 모드 필수
- 테스트 파일은 __tests__/ 디렉토리에 작성
- API 호출 시 반드시 에러 핸들링 포함

## 금지 사항
- console.log 대신 logger 모듈 사용
- any 타입 사용 금지

Hooks로 도구 실행 제어

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "node scripts/validate-command.js"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npx prettier --write $FILE_PATH"
      }
    ]
  }
}

핵심 정리

• Python/TypeScript SDK로 Claude Code를 프로그래밍 방식으로 사용
• query() 함수로 프롬프트 전송, 스트리밍 이벤트로 결과 수신
• resume 옵션으로 멀티턴 대화 구현
• MCP 서버로 데이터베이스, Slack 등 커스텀 도구 연동
• CLAUDE.md와 Hooks로 에이전트 동작 규칙 설정