클로드 코드 API 사용법 — Agent SDK로 직접 박는 길

클로드 코드(Claude Code)를 가장 많이 쓰는 입구는 터미널 CLI(claude)다. 하지만 CLI만 있는 게 아니다. 같은 엔진을 Python·TypeScript 라이브러리로 부르는 길이 따로 있다. Claude Agent SDK다.

이 글은 Agent SDK를 처음 박는 사람을 위한 한 페이지 정리다. 설치 한 줄, 인증 한 줄, 호출 한 함수에서 시작해 도구 권한·훅·세션·MCP·서브에이전트까지 차례로 짚는다. 결제 경로를 먼저 정해야 한다면 Pro·Max·API 비교 글이 앞 순서다.

1. CLI vs SDK — 같은 엔진, 두 입구

Anthropic 공식 문서는 두 입구의 관계를 이렇게 설명한다. CLI와 Agent SDK는 같은 기능을 다른 인터페이스로 노출한 것이다. CLI는 사람이 손으로 치는 대화형 환경에 최적화돼 있고, SDK는 코드에서 호출하는 자동화·통합 환경에 최적화돼 있다. 둘 사이의 작업 흐름은 직접 번역된다.

실무에서는 다음 표가 거의 그대로 들어맞는다.

한 가지 더 짚고 가야 할 차이가 있다. Anthropic Client SDK라는 라이브러리가 따로 존재한다. 이건 메시지 API에 직접 붙는 SDK다. Agent SDK와 헷갈리지 말아야 한다. Client SDK는 툴 호출이 들어오면 그 실행을 사용자가 직접 짜야 한다. Agent SDK는 그 루프를 Claude가 알아서 돌린다. Read·Write·Bash 같은 도구는 라이브러리 안에서 이미 구현돼 있다.

2. 두 줄 설치 — Python·TypeScript

설치는 한 줄이다. 패키지 매니저만 다르다.

3. 인증 — ANTHROPIC_API_KEY 한 줄

인증은 환경변수 한 줄로 끝난다. API 키는 platform.claude.com(Claude Console)에서 발급받는다. 콘솔에서 무엇이 보이는지는 대시보드 사용법 글에서 별도로 다룬다.

키 하나만 있으면 SDK가 알아서 인증한다. 클라우드 환경에서 돌릴 때는 사이드 옵션이 두 가지 있다. AWS Bedrock(CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI(CLAUDE_CODE_USE_VERTEX=1), Azure Foundry(CLAUDE_CODE_USE_FOUNDRY=1)로 각각 가입돼 있다면 환경변수 하나만 더 켜면 그쪽 자격증명을 따라간다. 1인 개발자는 거의 쓸 일이 없고, 회사가 이미 그쪽 클라우드 결제 계정을 가지고 있을 때 의미가 생긴다.

4. 첫 호출 — query() 안에서 일어나는 일

Agent SDK의 진입점은 query() 함수 하나다. 프롬프트와 옵션을 넘기면 비동기 이터레이터를 돌려준다. 그 이터레이터에서 메시지가 흘러나오는 동안 Claude가 도구를 호출하고 결과를 받고 다음 행동을 결정한다 — 그 루프를 SDK가 내부에서 굴린다.

두 언어 모두 같은 모양을 띤다. 프롬프트 한 줄, 허용 도구 목록 하나. result 필드가 있는 메시지가 최종 응답이고, 그 전 메시지들은 도구 호출·결과 같은 중간 단계다. 디버깅할 때는 모든 메시지를 찍어보면 SDK 내부에서 무슨 일이 벌어지는지 그대로 보인다.

5. 도구 권한 — allowed_tools와 permission_mode

Agent SDK가 기본으로 제공하는 도구는 10여 종이다. 각자 분명한 책임이 있고 권한 범위가 갈린다.

권한 제어는 두 축으로 한다. allowed_tools는 화이트리스트 — 여기 들어간 도구만 사용 가능. permission_mode는 사용 방식 — acceptEdits를 켜면 파일 수정에 사용자 확인 없이 진행하고, 기본 모드는 매번 확인을 요구한다. 코드 리뷰 같은 읽기 전용 작업은 allowed_tools=["Read","Glob","Grep"]만 주면 다른 위험한 행동을 아예 봉쇄할 수 있다.

6. 훅 — 도구 호출 전후에 코드 끼우기

훅(Hooks)은 에이전트의 생애 주기 안 특정 시점에 사용자 코드를 끼워 넣는 메커니즘이다. 검증·로깅·차단·변환 — 어떤 용도로도 쓸 수 있다. 주요 훅은 다음과 같다.

훅의 가장 흔한 용도는 감사(audit). 모든 파일 수정이 별도 로그 파일에 추적되도록 PostToolUse에 Edit|Write 매처를 걸어두면 누가 무엇을 언제 바꿨는지 코드 한 줄 없이 기록된다. 보안·규정 요구가 있는 환경에서 SDK를 들이밀 때 첫 번째로 짓는 안전장치다.

7. MCP·서브에이전트 — 외부 시스템과 분업

SDK는 단독으로 닫혀 있지 않다. 두 가지 확장 경로가 있다.

MCP(Model Context Protocol)는 외부 시스템을 도구로 붙이는 표준이다. 데이터베이스, 브라우저, Slack, Jira, 자체 사내 API — 무엇이든 MCP 서버로 노출하면 에이전트가 그걸 호출할 수 있다. 옵션의 mcp_servers(Python) 또는 mcpServers(TypeScript)에 등록만 하면 끝. Playwright MCP를 박으면 에이전트가 브라우저를 직접 조작하고, Google Drive MCP를 박으면 디자인 문서를 읽어 코드로 번역한다.

서브에이전트(Subagents)는 큰 작업을 작은 전문 에이전트들로 나누는 메커니즘이다. 메인 에이전트가 코드 리뷰어 서브에이전트에 분석을 위임하고, 보안 검토 서브에이전트에 별도로 보안 리뷰를 시키고, 결과를 받아 종합하는 식이다. 각 서브에이전트는 자체 시스템 프롬프트·자체 도구 권한·자체 컨텍스트를 가진다. 메인 에이전트의 컨텍스트가 잡다한 정보로 채워지는 걸 막는 효과가 가장 크다.

8. 세션 — 컨텍스트를 다음 실행에 넘기기

SDK는 세션을 JSONL 파일로 저장한다. 첫 호출에서 받은 session_id를 다음 호출의 resume 옵션에 넣으면 그 컨텍스트를 통째로 이어받는다. 인증 모듈을 한 번 읽힌 다음, 같은 컨텍스트에서 "그걸 호출하는 모든 곳을 찾아라"라고 시키면 "그것"이 인증 모듈이라는 것을 알고 있다.

여기에서 한 단계 더 나가면 포크(fork)다. 같은 세션에서 두 가지 다른 접근을 동시에 시도해 결과를 비교하는 패턴. 같은 컨텍스트를 두 갈래로 갈라 한쪽은 보수적인 리팩토링, 다른 한쪽은 적극적인 재설계를 시키고 결과를 합쳐서 선택지로 만든다. CI에서 PR 두 개를 동시에 만드는 워크플로가 이 위에 올라간다.

9. CLI 헤드리스 모드 — 파이프와 조합

SDK까지 갈 필요 없이 CLI의 -p 옵션만으로도 자동화의 절반은 끝난다. claude -p "..."는 인터랙티브 모드가 아닌 헤드리스 모드로 한 번 실행하고 결과를 stdout으로 뱉는다. 파이프·스크립트와 조합되는 순간 다음 같은 한 줄짜리 자동화가 만들어진다.

SDK는 이런 한 줄 자동화를 코드 안에 더 정교하게 박을 때 의미가 생긴다. 결과 메시지를 파싱해서 분기, 도구 권한을 상황별로 다르게 부여, 훅으로 외부 시스템 연동, 세션을 다음 단계로 이어가기 — CLI -p가 닿지 못하는 모든 영역이 SDK다.