Claude Code SDK로 자율 에이전트 구축하기: 실전 개발자 가이드

Claude Code SDK로 자율 에이전트 구축하기: 실전 개발자 가이드

Claude Code SDK — 공식 명칭은 Agent SDK —는 Claude Code의 전체 에이전틱 엔진을 프로그래밍 방식으로 구동할 수 있게 해주는 Python 및 TypeScript 라이브러리입니다. 터미널도 필요 없고, 키보드 앞에 사람이 있을 필요도 없이, 애플리케이션이 비동기 query() 함수를 호출하고 에이전트 작업의 모든 단계를 스트리밍으로 받아오기만 하면 됩니다. Claude Code를 대화형으로 사용해 보셨다면, SDK는 파일 읽기 / 코드 편집 / 명령 실행이라는 동일한 루프를 CI 파이프라인, 코드 리뷰 봇, 멀티 에이전트 오케스트레이터, 또는 어떤 백엔드 서비스에도 내장할 수 있는 조합 가능한 라이브러리로 제공합니다.

Agent SDK란 무엇이고, 왜 존재하는가

Claude Code는 터미널 도구로 잘 알려져 있습니다. 프롬프트를 입력하면 에이전트가 코드베이스를 추론하고, 내장 도구(Read, Edit, Bash, Grep 등)를 호출하며, 결과를 다시 작성해 돌려줍니다. 하지만 이 루프를 자동화하고 싶은 순간 — 모든 풀 리퀘스트마다 리뷰를 트리거하거나, 여러 개의 전문 서브 에이전트로 분산시키거나, 그 위에 제품을 구축하고 싶을 때 — 대화형 CLI는 적절한 추상화가 아닙니다. 라이브러리가 필요합니다.

Agent SDK가 그 공백을 채웁니다. Anthropic의 공식 문서에 따르면, 이는 "Claude Code를 구동하는 것과 동일한 도구, 에이전트 루프, 컨텍스트 관리를 Python과 TypeScript로 프로그래밍 가능하게" 노출합니다. 이는 마케팅 언어가 아니라 말 그대로의 아키텍처입니다. SDK는 Claude Code CLI 바이너리를 관리형 서브프로세스로 실행하고, stdio를 통해 통신하며, 모든 것을 코드가 소비하고 반응할 수 있는 타입이 지정된 메시지 객체의 비동기 스트림으로 노출합니다.

이 구분은 몇 가지 이유로 중요합니다:

동일한 엔진, 다른 인터페이스. CLI에서 SDK로 전환한다고 해서 더 열등하거나 단순한 도구로 이동하는 것이 아닙니다. SDK는 CLI의 모든 기능 — MCP 서버 연결, 훅 생명주기, 스킬 파일, CLAUDE.md 메모리, 서브 에이전트 위임, 전체 도구 목록 — 을 그대로 물려받습니다.

SDK가 도구 실행을 대신해 줍니다. Anthropic Client SDK(더 저수준의 anthropic Python/JS 패키지)를 사용하면서 Claude가 도구를 호출하게 하려면, 도구 루프를 직접 구현해야 합니다: API를 호출하고, 도구 사용 응답을 감지하고, 도구를 실행하고, 결과를 다시 피드백하고, Claude가 멈출 때까지 반복하는 식입니다. Agent SDK는 이 전체 루프를 단 하나의 async for message in query(...)로 압축합니다 — Claude가 어떤 도구를 호출할지 결정하고, 자신의 서브프로세스 내에서 실행하며, 작업이 끝날 때까지 계속 루프를 돕니다. 여러분은 그저 스트림을 소비하기만 하면 됩니다.

설계부터 헤드리스. CLI의 권한 프롬프트 — "이 bash 명령을 허용할까요?" — 는 사람의 입력을 기다리며 블로킹됩니다. SDK는 이를 permissionMode 옵션과 여러 권한 모드로 대체합니다 — 예를 들어 파일 편집을 자동 승인하는 acceptEdits, 샌드박스 처리된 CI 환경에서 프롬프트 없이 모든 것을 실행하는 bypassPermissions — 여기에 커스텀 플로우를 위한 프로그래밍 방식의 승인 콜백도 추가됩니다. 정확한 모드 이름과 동작은 Anthropic의 SDK 레퍼런스에 문서화되어 있으니(최신 목록은 그쪽을 확인하세요) 참고하시되, 효과는 동일합니다: 자동화가 키 입력을 기다리며 멈추는 일은 없습니다.

동일한 Claude Code 엔진, 두 가지 인터페이스: 사람이 개입하는 작업을 위한 대화형 CLI, 애플리케이션이 프롬프트를 제어하고 권한 모드가 승인 대화상자를 대체하는 프로그래밍 방식의 헤드리스 자동화를 위한 Agent SDK.

SDK 설치하기

Anthropic은 두 개의 패키지를 배포합니다:

• TypeScript: @anthropic-ai/claude-agent-sdk (npm)
• Python: claude-agent-sdk (pip; Python 3.10 이상 필요)

TypeScript 패키지는 플랫폼에 맞는 네이티브 Claude Code 바이너리를 번들로 포함하므로 별도의 CLI 설치가 필요하지 않습니다. 인증은 Anthropic Console에서 발급받은 ANTHROPIC_API_KEY 환경 변수를 통해 이루어집니다. SDK는 Amazon Bedrock, Google Vertex AI, Microsoft Azure AI Foundry도 지원합니다 — 관련 환경 변수 패턴은 Anthropic의 문서를 참고하세요.

핵심 개념

네 가지 개념을 이해하면 실제 SDK 사용의 대부분을 다룰 수 있습니다.

1. query() 함수와 비동기 메시지 스트림

모든 SDK 상호작용은 query()로 시작합니다. prompt 문자열과 options 객체를 전달하면, 에이전트가 작업하는 동안 타입이 지정된 메시지 객체를 내보내는 비동기 이터레이터를 반환받습니다. 에이전트가 작업을 마치거나 오류가 발생하면 루프가 종료됩니다.

받게 되는 메시지는 다음과 같습니다:

• AssistantMessage — Claude의 추론 텍스트와 도구 호출 설명
• ToolResultMessage — 각 도구 실행의 출력
• ResultMessage — 성공/실패를 나타내는 subtype 필드가 포함된 최종 결과
• SystemMessage — 세션 생명주기 이벤트(init 서브타입은 session_id를 전달)

대부분의 프로덕션 코드에서는 최종 출력을 추출하기 위해 ResultMessage를 필터링하고, 선택적으로 AssistantMessage 블록을 로깅해 에이전트가 무엇을 했는지 추적합니다.

2. 도구와 allowedTools

SDK의 내장 도구 목록은 Claude Code의 기능과 직접 매핑됩니다:

allowedTools 옵션은 이 중 일부를 사전 승인하여, 추가적인 게이트 없이 에이전트가 이를 호출할 수 있는 권한을 부여합니다. 읽기 전용 감사 에이전트는 ["Read", "Glob", "Grep"]만 나열할 수 있고, 완전한 자동화라면 ["Read", "Edit", "Bash", "Glob", "Grep"]을 포함할 수 있습니다.

3. 권한 모드

권한 모드는 에이전트가 allowedTools에 사전 승인되지 않은 도구를 사용하려 할 때 무슨 일이 일어나는지를 제어합니다:

• acceptEdits — 파일 편집과 일반적인 파일시스템 작업을 자동 승인하고, 나머지는 프롬프트를 띄웁니다. 신뢰할 수 있는 개발 워크플로우에 적합합니다.
• dontAsk — allowedTools에 없는 모든 것을 조용히 거부합니다. 잠긴 헤드리스 에이전트에 적합합니다.
• bypassPermissions — 모든 도구를 게이트 없이 실행합니다. 샌드박스 환경 내에서만 사용하세요.

SDK는 완전히 커스텀한 승인 로직을 구현할 수 있도록 프로그래밍 방식의 승인 콜백도 노출하며, 사용 가능한 모드 이름은 시간이 지나면서 늘어날 수 있으니 최신의 정확한 목록과 각 모드의 정확한 동작은 Anthropic의 SDK 레퍼런스를 참고하세요. CI에서는 거의 항상 엄격하게 범위가 지정된 기본 거부 구성이나, 직접 제어하는 컨테이너 샌드박스 내에서의 bypassPermissions를 사용하게 될 것입니다.

4. 세션, 재개, 그리고 컨텍스트

query()를 호출할 때마다 세션이 생성되거나(또는 재개되거나) 합니다. 세션의 session_id는 subtype === "init"인 첫 번째 SystemMessage에 담겨 도착합니다. 이를 캡처해서 이후 호출에서 resume: sessionId로 전달하면, 대화가 멈췄던 바로 그 지점 — 동일한 파일 읽기, 동일한 추론 히스토리, 동일한 컨텍스트 윈도우 — 에서 이어갈 수 있습니다.

이것이 멀티턴 에이전트를 구축하는 방법입니다: 첫 번째 query() 호출이 모듈을 분석하고 session_id를 캡처하면, 두 번째 query()(resume 포함)는 재설명 없이 "그것" 또는 "방금 읽은 파일"을 참조할 수 있습니다. 세션 트랜스크립트는 기본적으로 로컬 디스크에 기록됩니다. 프로덕션 환경에서는 S3, Redis, Postgres 기반의 SessionStore 어댑터를 연결하여 컨테이너 재시작 후에도 세션이 유지되도록 할 수 있습니다.

빌드 패턴 1: CI 코드 리뷰 봇

이것이 전형적인 "헤드리스 자동화" 사용 사례입니다. 모든 풀 리퀘스트마다 CI 작업이 브랜치를 체크아웃하고, 변경된 파일을 읽는 에이전트를 실행한 뒤, 리뷰 코멘트를 게시합니다.

흐름은 다음과 같습니다:

1. PR 이벤트가 GitHub Actions 워크플로우(또는 GitLab CI 작업)를 트리거합니다.
2. 러너가 브랜치를 체크아웃하고 리뷰 스크립트를 실행합니다.
3. 스크립트가 리뷰 프롬프트, allowedTools: ["Read", "Glob", "Grep", "Bash"], permissionMode: "dontAsk"로 query()를 호출합니다.
4. Claude가 diff를 읽고 패턴을 검색하며 발견 사항을 추론합니다.
5. ResultMessage가 리뷰 텍스트를 담아오면, 스크립트가 GitHub API를 통해 PR에 게시합니다.

핵심 설계 선택은 읽기 전용 도구 목록과 함께 dontAsk를 사용하는 것입니다. 에이전트는 파일을 작성하거나 도구가 허용하는 범위를 벗어난 네트워크 호출을 할 수 없으므로, CI 작업이 실수로 커밋을 머지하거나 외부 API를 호출할 수 없습니다. maxTurns 상한(options에서 설정)은 에이전트의 깊이를 제한하여 폭주하는 루프가 예산을 소모하지 않도록 합니다.

이 흐름의 아키텍처 그림은 아래를 참고하세요.

완전히 자동화된 코드 리뷰 파이프라인. SDK 에이전트는 읽기 전용 도구 목록을 가진 CI 컨테이너 내에서 실행되며, 발견 사항은 ResultMessage로 스트리밍되어 돌아오고 코드가 이를 GitHub PR 코멘트로 게시합니다. 에이전트는 파일을 작성하지 않으며 컨테이너를 벗어나지도 않습니다.

이 패턴은 훅 — Claude Code 훅 심층 분석에서 다룬 SDK 기능 — 을 사용해 확장할 수 있습니다. 모든 도구 호출을 감사 파일에 기록하거나, 특정 파일 경로의 읽기를 차단하거나, 리뷰와 함께 구조화된 텔레메트리를 내보낼 수 있습니다.

빌드 패턴 2: 멀티 에이전트 도구 체인

SDK의 agents 옵션은 각각 자체 시스템 프롬프트, 도구 목록, 권한을 가진 이름 붙여진 서브 에이전트를 정의할 수 있게 해줍니다. 메인 에이전트는 내장 Agent 도구를 통해 작업을 위임합니다. 서브 에이전트 메시지에는 parent_tool_use_id 필드가 포함되어 있어 어떤 위임이 어떤 결과물을 만들어냈는지 정확히 추적할 수 있습니다.

실용적인 예시: 보안 감사 에이전트 체인에서 code-scanner 서브 에이전트가 Grep과 Glob을 사용해 잠재적 취약점을 찾고, dependency-checker 서브 에이전트가 Bash를 실행해 패키지 메타데이터를 조회하며, 코디네이터 에이전트가 두 보고서를 하나의 통합 감사 보고서로 종합합니다. 각 서브 에이전트는 역할에 필요한 최소한의 도구 접근만 가지므로, 서브 에이전트가 위험한 명령을 환각(hallucinate)하더라도 피해 범위가 제한됩니다.

멀티 에이전트 체인은 자연스럽게 분해되는 작업에 잘 맞습니다: 관심사별로 하나의 에이전트, 각각 좁은 도구 목록, 그리고 Read와 Agent만 필요한 코디네이터가 오케스트레이션합니다. 멀티 에이전트 아키텍처가 CLAUDE.md 메모리나 스킬 파일 같은 Claude Code 기능과 어떻게 조합되는지 더 폭넓게 알고 싶다면 하니스 엔지니어링 가이드를 참고하세요.

빌드 패턴 3: 헤드리스 자동화 파이프라인

코드 리뷰를 넘어, SDK는 에이전트가 더 큰 파이프라인의 한 단계인 반복적인 자동화 어디에서든 뛰어난 성능을 발휘합니다:

야간 의존성 감사. 크론 작업이 오래된 패키지를 확인하고, 보안 스캐너를 실행하며, 구조화된 보고서를 생성하는 프롬프트로 query()를 호출합니다. Bash 도구가 npm audit 또는 pip check를 실행하고, Read가 락 파일을 검사합니다. ResultMessage가 Slack 알림에 사용됩니다.

PR 머지 시 번역 및 i18n. PR이 머지되면 웹훅이 Glob과 Read로 변경된 문자열 파일을 읽고, Write로 번역된 버전을 생성하며, Bash(gh pr create 실행)를 통해 새 PR을 여는 에이전트를 트리거합니다.

로그 이상 탐지. 최근 로그 출력을 query() 프롬프트로 파이프합니다. 에이전트는 필요하면 추가 컨텍스트 파일을 읽고, 로그를 추론하며, 구조화된 발견 사항을 내보냅니다. 파일 작성이 필요 없으므로 읽기 전용 도구 목록으로 충분합니다.

문서 동기화. PR이 머지된 후, 에이전트가 업데이트된 소스 파일을 읽고 대응하는 문서 페이지를 다시 작성한 다음 변경 사항을 커밋합니다. permissionMode: "acceptEdits"가 프롬프트 없이 파일 작성을 처리합니다.

공통 맥락: query()가 자체 제작한 LLM 통합을 대체합니다. 도구 루프를 구현하거나, 컨텍스트 윈도우를 수동으로 관리하거나, 모델 출력을 파싱해서 다음에 실행할 것을 결정할 필요가 없습니다. 에이전트가 오케스트레이션을 처리하고, 여러분은 프롬프트를 제공하고 결과를 소비하기만 하면 됩니다.

실제 예시: 버그 수정 에이전트

공식 퀵스타트는 이 패턴을 깔끔하게 보여줍니다(아래 코드는 문서화된 API를 따르니, 정확한 문법은 Anthropic의 퀵스타트 문서에서 확인하세요):

예시 Python 코드 (정확한 API는 공식 문서에서 확인):

# Illustrative — confirm exact import paths and option names in official docs
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def run_bug_fixer(file_path: str):
    async for message in query(
        prompt=f"Review {file_path} for bugs that would cause crashes. Fix any issues.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"Completed: {message.subtype}")

asyncio.run(run_bug_fixer("src/utils.py"))

예시 TypeScript 코드 (정확한 API는 공식 문서에서 확인):

// Illustrative — confirm exact import paths and option names in official docs
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review src/utils.ts for crash-causing bugs and fix them.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  }
  if (message.type === "result") console.log("Done:", message.subtype);
}

이것이 실행되면 무슨 일이 일어나는지: Claude가 Read 도구를 사용해 utils.py(또는 .ts)를 읽고, 코드를 추론하며, 엣지 케이스를 식별한 다음, Edit을 호출해 방어적 처리를 삽입합니다. 추론과 도구 호출이 AssistantMessage 객체로 스트리밍되어 지나가는 것을 볼 수 있고, 최종 ResultMessage가 완료를 알립니다. 편집을 검증하기 위해 파일을 다시 읽는 것을 포함한 전체 에이전트 루프는 SDK가 관리합니다.

이것이 Anthropic 모델 API를 직접 호출하는 것과 SDK가 다른 점입니다: 도구 실행 계층을 직접 구현할 필요가 없습니다. Claude가 언제 Read를 호출할지 결정하고, 호출하고, 파일 내용을 돌려받고, 계속 추론합니다. 루프는 자율적입니다.

권한, 샌드박싱, 프로덕션 안전성

프로덕션에서 자율 에이전트를 실행하려면 에이전트가 무엇을 건드릴 수 있는지 신중하게 생각해야 합니다. SDK는 여러 계층의 제어를 제공합니다.

도구 범위 지정이 첫 번째 방어선입니다. 에이전트가 Bash가 필요 없다면 allowedTools에 포함시키지 마세요. ["Read", "Glob", "Grep"]만 가진 에이전트는 프롬프트가 무엇을 말하든 관계없이 파일을 수정하거나, 셸 명령을 실행하거나, 네트워크 호출을 할 수 없습니다.

권한 모드는 두 번째 게이트를 제공합니다. dontAsk는 allowedTools 밖의 모든 것을 프롬프트 없이 조용히 거부되도록 보장합니다. 이는 헤드리스 환경에서 중요합니다 — 사용자 입력을 기다리며 멈추는 프롬프트는 파이프라인을 정체시킬 것입니다.

cwd 옵션은 에이전트의 파일시스템 접근을 특정 디렉터리로 범위 지정합니다. 멀티 테넌트 환경에서는 세션별 작업 디렉터리를 전달하여 다른 테넌트의 에이전트가 서로의 파일을 읽을 수 없도록 하세요.

테넌트 격리에는 추가 단계가 필요합니다: 설정이 테넌트 간에 유출되지 않도록 settingSources: []를 설정하고, 자동 메모리가 로드되지 않도록 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정하며, CLAUDE_CONFIG_DIR을 테넌트별 경로로 지정하세요. 이는 Anthropic의 호스팅 가이드에 자세히 문서화되어 있습니다.

컨테이너 샌드박싱은 바깥쪽 껍질입니다. Bash 접근이 필요한 프로덕션 에이전트의 경우, 명시적으로 허용한 도메인으로 네트워크 이그레스가 제한된 컨테이너 내에서 SDK를 실행하세요. Modal, E2B, Cloudflare Sandboxes, Fly Machines, Vercel Sandbox 같은 제공업체가 Anthropic 문서에서 샌드박스 처리된 SDK 배포 옵션으로 언급되어 있습니다.

**maxTurns**는 도구 사용 왕복 횟수를 상한선으로 제한하여 비용과 폭주 루프를 모두 억제합니다. 작업의 예상 복잡도에 따라 설정하세요 — 간단한 파일 읽기 리뷰는 510턴이면 충분할 수 있고, 복잡한 다중 파일 리팩터링은 3050턴이 필요할 수 있습니다.

프로덕션 훅과 권한 플로우를 구축하는 팀을 위해, Claude Code 훅 가이드는 PreToolUse와 PostToolUse 훅 생명주기를 자세히 다루며, 도구 호출이 실행되기 전에 이를 차단하거나 변형하거나 로깅하는 훅 콜백을 작성하는 방법도 포함합니다.

MCP: 에이전트를 외부 시스템에 연결하기

SDK는 Model Context Protocol(MCP)을 완전히 지원하며, 이를 통해 에이전트를 데이터베이스, 브라우저 자동화, Jira, Slack, GitHub, 수백 개의 커뮤니티 제작 서버 등 MCP 서버를 노출하는 모든 외부 시스템에 연결할 수 있습니다.

MCP 서버는 mcpServers 옵션에서 구성합니다 — 각 항목은 실행할 명령과 선택적 인수를 지정합니다. SDK는 이러한 서버를 서브프로세스로 시작하고, 에이전트는 내장 도구를 호출하는 것과 동일한 방식으로 이들의 도구를 호출할 수 있습니다. 이것이 코드 리뷰 에이전트에 이슈 트래커 접근 권한을 주거나, 문서 에이전트를 회사 지식 베이스에 연결하는 방법입니다.

권한 모델은 MCP 도구 호출에도 적용됩니다 — allowedTools에 MCP 도구 이름을 포함할 수 있고, permissionMode가 목록에 없는 도구에 대한 처리를 결정합니다.

함정과 흔한 실수

세션은 기본적으로 서브프로세스에 로컬입니다. 세션 트랜스크립트는 호스트의 로컬 디스크 ~/.claude/projects/ 아래에 저장됩니다. 컨테이너화되거나 수평 확장된 배포에서는 재시작이나 노드 재할당 시 세션 상태가 손실된다는 의미입니다. 컨테이너 간에 재개해야 하는 세션이 있다면 SessionStore 어댑터를 사용하세요.

서브프로세스 모델은 메모리에 영향을 미칩니다. 실행 중인 각 세션은 별도의 서브프로세스입니다. 50개의 동시 세션을 실행하면 50개의 Claude Code 프로세스가 실행된다는 의미입니다. 공식 가이드라인은 시작점으로 에이전트당 대략 1GiB RAM이지만, 실제 메모리 사용량은 세션 길이와 도구 활동에 따라 달라집니다. 이에 맞게 컨테이너 크기를 조정하고 maxTurns를 설정해 세션 깊이를 제한하세요.

대규모 서브 에이전트 팬아웃은 속도 제한에 걸립니다. 오케스트레이터가 20개의 서브 에이전트에 동시에 위임한다면, Anthropic의 API 속도 제한에 걸릴 가능성이 높습니다. 넓은 팬아웃을 배치로 나누고 디스패치 사이에 약간의 지연을 추가하세요.

bypassPermissions는 실제 샌드박스가 필요합니다. 이 모드는 모든 권한 게이트를 건너뜁니다. 전체 실행 컨텍스트를 직접 소유한 CI 컨테이너 같은 완전히 통제된 환경을 위해 설계되었습니다. SSH 키, 클라우드 자격증명, 임의의 파일시스템 경로에 접근 가능한 개발자의 컴퓨터에서 사용하는 것은 보안 위험입니다.

TypeScript SDK는 Claude Code 바이너리를 번들로 포함하지만, Python은 별도로 요구하지 않습니다. 하지만 두 SDK 모두 특정 CLI 버전에 고정됩니다. SDK 패키지를 업그레이드하면 기반이 되는 CLI도 업그레이드됩니다. 마이너 업그레이드 전에 변경 로그를 검토하세요 — 호환성이 깨지는 동작 변경은 그곳에 공지됩니다.

프롬프트 텍스트와 도구 입력은 기본적으로 OTEL 내보내기에 포함되지 않습니다. 이는 의도된 개인정보 보호 동작입니다. 디버깅을 위해 프롬프트 수준의 트레이싱이 필요하다면 Anthropic의 관측성 가이드에 문서화된 환경 변수를 통해 명시적으로 활성화해야 합니다.

구버전 SDK는 최신 모델을 지원하지 않을 수 있습니다. Anthropic의 문서에 따르면 최신 모델은 사고(thinking) 파라미터 API의 변경으로 인해 최신 SDK 버전이 필요할 수 있으므로, 오래된 SDK는 새 모델에서 실패할 수 있습니다. 새 모델을 도입할 때는 항상 변경 로그를 확인하고 검증된 버전을 고정하세요.

SDK vs. CLI: 어느 쪽이 필요한가?

대부분의 개발자에게 답은 "둘 다"이며, 이는 의도된 설계입니다.

대화형 CLI는 일상적인 개발에 적합한 도구입니다: 낯선 코드베이스를 탐색하거나, 복잡한 버그를 대화형으로 해결하거나, 일회성 리팩터링을 실행하는 것 말이죠. SDK는 사람 없이 실행되어야 하는 모든 것 — CI, 예약된 작업, 애플리케이션 기능, 멀티 에이전트 파이프라인 — 에 적합한 도구입니다.

SDK와 CLI는 경쟁 제품이 아닙니다. CLI로 대화형으로 개발한 워크플로우는 SDK 자동화로 직접 전환됩니다 — 동일한 도구, 동일한 권한 개념, 동일한 CLAUDE.md 메모리와 스킬 시스템. 오늘 터미널에서 claude로 프로토타이핑한 리뷰 워크플로우가 내일 SDK 기반 CI 봇이 됩니다.

웹 버전 Claude Code를 사용하는 팀(Claude Code on the web 가이드에서 다룸)의 경우, SDK는 웹 세션과 프로그래밍 방식의 오케스트레이션을 혼합할 수 있는 문을 열어줍니다 — 웹에서 장시간 실행되는 작업을 시작한 다음, 백엔드에서 프로그래밍 방식으로 이어받을 수 있습니다.

자주 묻는 질문

Claude Code SDK(Agent SDK)가 정확히 무엇인가요? Claude Code의 전체 에이전틱 엔진 — 도구, 권한, 세션 관리, 서브 에이전트, MCP — 을 프로그래밍 가능한 비동기 API로 노출하는 Python(claude-agent-sdk) 및 TypeScript(@anthropic-ai/claude-agent-sdk) 라이브러리입니다. query()를 호출하고, 프롬프트와 옵션을 전달하면, 에이전트의 작업을 타입이 지정된 메시지 객체로 스트리밍 받습니다.

SDK를 사용하려면 Claude Code를 설치해야 하나요? TypeScript SDK는 아니요 — 패키지에 네이티브 Claude Code 바이너리가 번들로 포함되어 있습니다. Python SDK는 claude-agent-sdk 패키지가 의존성을 처리합니다. Anthropic Console에서 발급받은 Anthropic API 키는 필요합니다.

Anthropic의 API 외의 모델에서도 SDK를 사용할 수 있나요? 네. SDK는 Amazon Bedrock, Google Vertex AI, Microsoft Azure AI Foundry, 그리고 환경 변수를 통한 AWS의 Claude Platform을 지원합니다. ANTHROPIC_BASE_URL을 설정해서 커스텀 프록시를 통해 요청을 라우팅할 수도 있습니다.

GitHub Actions 워크플로우에서 SDK를 어떻게 사용하나요? ANTHROPIC_API_KEY를 GitHub Actions 시크릿으로 추가하고, 워크플로우에서 PR 브랜치를 체크아웃하고, SDK 패키지를 설치하고, 에이전트 스크립트를 실행하세요. 에이전트가 CI 환경의 파일을 수정할 수 없도록 읽기 전용 allowedTools 목록과 함께 permissionMode: "dontAsk"를 사용하세요. Anthropic의 문서는 커스텀 SDK 코드를 작성하지 않고도 PR 리뷰와 이슈 트리아지를 자동화하는 전용 GitHub Actions 통합도 다룹니다.

Agent SDK와 Managed Agents의 차이는 무엇인가요? Agent SDK는 여러분 자신의 프로세스와 인프라 내에서 에이전트 루프를 실행하는 라이브러리입니다. Managed Agents는 Anthropic이 에이전트와 샌드박스를 실행하는 호스팅된 REST API로, 이벤트를 보내고 결과를 스트리밍으로 받습니다. SDK는 로컬 프로토타이핑과 여러분의 파일시스템에서 직접 작업하는 에이전트에 더 적합하고, Managed Agents는 컨테이너 인프라를 운영하고 싶지 않은 프로덕션 환경에 더 적합합니다.

에이전트가 접근할 수 있는 범위를 어떻게 제한하나요? allowedTools로 사용 가능한 도구를 제한하고, permissionMode: "dontAsk"로 목록 밖의 모든 것을 거부하며, cwd로 파일시스템 접근을 특정 디렉터리로 범위 지정하세요. 멀티 테넌트 배포의 경우 추가로 settingSources: []와 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정하세요.

SDK가 스트리밍 출력을 지원하나요? 네 — query()의 비동기 이터레이터는 메시지를 실시간으로 스트리밍합니다. 라이브 출력이 필요 없다면(최종 결과만 신경 쓰는 백그라운드 작업이나 CI 파이프라인의 경우), Anthropic의 문서는 반환 전에 모든 메시지를 수집하는 단일 턴 모드를 설명합니다. 공식 문서의 스트리밍 vs. 단일 턴 모드를 참고하세요.

여러 에이전트를 병렬로 실행할 수 있나요? 네. 각 query() 호출은 독립적인 서브프로세스를 생성합니다. N개의 동시 세션을 실행할 수 있지만 — 각각이 별도의 프로세스이므로, 그에 맞게 메모리를 프로비저닝하고 API 속도 제한에 유의하세요. 단일 오케스트레이터에서의 동시 서브 에이전트 팬아웃의 경우, 속도 제한에 걸리지 않도록 디스패치를 배치로 나누세요.

작업 도중 세션이 크래시되면 어떻게 되나요? 기본적으로 세션 트랜스크립트는 컨테이너에 로컬로 저장되며 재시작 시 손실됩니다. 재시작 후에도 유지하려면 SessionStore 어댑터(S3, Redis, Postgres)를 구성하고 options에 전달하세요. 그러면 새 컨테이너에서 session_id로 세션을 재개할 수 있습니다.

로컬 설정 없이 에이전트 실행하기

SDK의 가치 제안은 자동화입니다 — 하지만 그 자동화를 실행하려면 실제 인프라가 필요합니다: Python 또는 Node 런타임, API 키, 컨테이너 전략, 샌드박싱 결정, 그리고 첫 프로덕션 배포 전에 권한 모델링에 쓰는 시간까지 말이죠.

이러한 설정 부담 없이 에이전트 아이디어를 빠르게 시도해보고 싶은 개발자를 위해, Happycapy는 브라우저에서 직접 Claude Code 스타일의 에이전트를 실행합니다. 로컬 설치도, 서브프로세스 관리도, 컨테이너 프로비저닝도 필요 없습니다. 프롬프트만 가져오면 Happycapy가 실행 환경을 처리합니다 — 150개 이상의 모델과 안전한 클라우드 샌드박스에 대한 접근과 함께요. 나중에 SDK로 제품화할 에이전트 동작을 프로토타이핑하는 빠른 방법입니다.

happycapy.ai에서 무료로 시작하기

관련 가이드

• Claude Code Hooks: The Power-User Guide to Automating Your Agent
• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• What Is Harness Engineering? Building Reliable AI Agent Harnesses (2026)