Claude Code SDK

⚠️ 주의: 영상의 패키지 이름은 더 이상 동작하지 않음 → 현재는 @anthropic-ai/claude-agent-sdk 사용

Agent SDK란

Agent SDK는 자신의 애플리케이션이나 스크립트에서 Claude Code를 프로그램적으로 실행할 수 있게 해주는 SDK입니다. TypeScript, Python 라이브러리를 통해 사용가능하고, CLI에서도 당연히 사용 가능합니다. Agent SDK는 Claude Code를 코드를 통해 직접 제어할 수 있게 해줍니다. 터미널에서 사용하는 Claude Code CLI와 동일합니다. 이렇게 Agent SDK는 agent 루프(파일 읽기, 편집, 도구 사용)를 코드를 통해 직접 제어 가능하게 해줍니다. 앞서 Hook 예시에서 보았듯이 Agent SDK는 큰 파이프라인 또는 도구의 일부/중간에 Claude Code를 사용하고 싶을 때(지능형 명령) 유용합니다.

설치

Agent SDK의 패키지 이름은 @anthropic-ai/claude-agent-sdk입니다.

⚠️ 비슷한 이름의 @anthropic-ai/claude-code는 CLI 자체라 import할 수 없음.

원하는 경로로 이동해 패키지를 설치하면 됩니다.

mkdir sdk-demo
cd sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk

간단한 예시

nano index.mjs를 입력해 빠르게 index.mjs를 만들고 다음 코드를 붙여넣어보세요.

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = "List the files in the current directory";

for await (const message of query({ prompt })) {
  console.log(JSON.stringify(message, null, 2));
}

그리고 다음 명령어로 index.mjs를 실행합니다.

node index.mjs

→ CLI에서 보던 것과 동일한 JSON 메시지 스트림 출력 (도구 호출, 도구 결과, Claude의 텍스트 응답 포함)이 보입니다.

도구 제한하기: allowedTools

기본적으로 SDK는 읽기 전용 도구만 사용 가능합니다. 편집 도구 등 원하는 도구를 사용하고 싶다면 allowedTools 를 사용하면 됩니다.

for await (const message of query({
  prompt,
  options: { allowedTools: ["Edit"] },
})) {
  // ...
}

allowedTools 는 CLI에서 --allowedTools 플래그와 동일한 역할을 합니다.

SDK 지원 기능

CLI가 하는 모든 것을 지원합니다.

• 커스텀 시스템 프롬프트
• MCP 서버
• Hooks
• 서브에이전트
• 세션 재개 (session resumption)

활용 시나리오

• 17단원의 query Hook. Hook 안에서 또 다른 Claude를 spawn해 리뷰하는 사례
• 일괄 처리 스크립트로 여러 파일에 동일 작업을 자동 적용
• CI/CD 파이프라인 통합 (GitHub Action 외 환경에서도 활용 가능)
• 외부 시스템 트리거 (예: Slack 명령으로 Claude 작업 실행)

요약