Agent SDK 아키텍처

Agent SDK란 무엇인가

Agent SDK는 Claude Code의 에이전트 루프를 TypeScript 또는 Python 애플리케이션 안에서 실행하도록 제공하는 개발 도구다. 앱은 프롬프트 하나를 보내고 텍스트만 받는 데서 멈추지 않는다. 에이전트가 도구를 선택하고, 결과를 읽고, 다음 행동을 결정하는 여러 턴의 작업을 스트리밍으로 관찰하고 제어할 수 있다.

Anthropic Client SDK와 역할을 혼동하지 않는 것이 중요하다. Client SDK는 Messages API 등을 직접 호출할 때 사용하고, Agent SDK는 Claude Code의 도구·권한·세션·hooks·MCP 통합을 활용하는 에이전트를 만들 때 사용한다.

애플리케이션
    │ query()와 옵션
    ▼
Agent SDK ── 권한·세션·도구·MCP ── Claude Code 에이전트 루프
    │
    ▼
스트리밍 메시지와 최종 결과

현재 패키지 이름

TypeScript Agent SDK의 공개 패키지 이름은 @anthropic-ai/claude-agent-sdk다. 예전 Claude Code SDK 이름을 사용한 코드가 있다면 마이그레이션 가이드로 패키지와 import를 먼저 갱신한다. 이름만 바꾸고 예전 비공개 제어 프로토콜이나 삭제된 세션 API를 그대로 유지하면 동작을 보장할 수 없다.

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

기본 실행 모델

query()는 비동기 이터레이터를 반환한다. 애플리케이션은 메시지를 순서대로 읽어 화면·로그·상태 저장소에 반영하고, result 메시지에서 작업의 성공 여부와 세션 식별자를 확인한다. 도구 실행을 무제한으로 허용하지 말고, 작업에 필요한 allowedTools와 작업 디렉터리를 제한한다.

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

for await (const message of query({
  prompt: "auth 모듈을 읽고 개선 후보를 요약해 주세요.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

애플리케이션 설계 경계

Agent SDK는 개발자 프로세스와 인프라에서 동작하므로, 애플리케이션이 권한·인증·비밀·로그 보존을 책임져야 한다. 프로덕션에서는 사용자별 작업 디렉터리를 분리하고, 네트워크·파일 쓰기·MCP 도구를 최소 권한으로 구성하며, 도구 실행과 승인 결정을 감사 가능하게 남긴다. 실행 환경을 분리할 수 없을 때는 쓰기 권한을 부여하지 않는 읽기 전용 분석부터 시작하는 편이 안전하다.

이 장의 다음 내용에서는 SDK를 통신 메시지 형식을 추측해 제어하는 방법이 아니라, 공식 옵션·승인 흐름·세션 모델로 제어하는 방법을 다룬다.