Claude Agent SDK 적용 기준: CLI, Client SDK, Managed Agents와 헷갈릴 때 보는 구조

Anthropic의 Claude Agent SDK 문서는 에이전트 제품을 만들 때 자주 헷갈리는 선택지를 명확히 나눈다. Agent SDK, Claude Code CLI, Client SDK, Managed Agents는 모두 Claude 계열 도구지만 쓰임새가 다르다. Agent SDK는 Claude Code의 agent loop, 도구, context management를 Python과 TypeScript 라이브러리로 쓰는 방식이다.

검색 의도는 ‘Claude Agent SDK를 언제 써야 하는가’다. 답은 직접 tool loop를 만들고 싶지 않지만, 제품 안에 agent 기능을 넣고 싶을 때다. 단순 API 호출이면 Client SDK가 낫고, 터미널에서 일회성 개발 작업을 하는 개발자라면 CLI가 낫다. 장시간 비동기 agent와 hosted sandbox가 필요하면 Managed Agents가 후보가 된다.

네 가지 선택지를 먼저 분리한다

Agent SDK는 라이브러리다. 앱 코드 안에서 agent loop를 실행하고, 파일 읽기·쓰기·명령 실행·웹 검색 같은 built-in tools를 제어하며, hooks, subagents, MCP, permissions, sessions를 사용할 수 있다. Python과 TypeScript만 공식 대상이다.

Claude Code CLI는 사람이 터미널에서 상호작용하기 좋다. 기존 개발자가 빠르게 버그를 고치거나 코드베이스를 탐색할 때 맞다. 다른 언어에서 같은 agent loop를 쓰고 싶다면 CLI를 subprocess로 실행하고 -p, --output-format json을 쓰는 방법도 문서에 언급돼 있다.

Client SDK는 Anthropic API에 직접 붙는 방식이다. tool loop를 직접 구현할 수 있고, 제품 요구사항이 단순하거나 완전한 제어가 필요할 때 맞다. 다만 agent loop, 세션, permission 같은 상위 기능은 직접 만들어야 한다.

Managed Agents는 hosted REST API와 sandbox를 제공하는 별도 제품이다. 인프라를 직접 운영하기 싫고, 장시간 비동기 작업을 맡기고 싶을 때 맞는다. 반대로 로컬 파일 시스템과 제품 UI 안의 세밀한 제어가 중요하다면 Agent SDK가 더 맞을 수 있다.

Agent SDK가 유리한 제품 유형

Agent SDK는 ‘우리 앱 안에 agent를 넣고 싶다’는 요구에 맞다. 예를 들어 개발자 도구, 코드 리뷰 서비스, 내부 자동화 UI, QA agent, 문서 maintenance bot, 로컬 프로젝트 분석 도구가 여기에 들어간다. 제품은 자체 화면과 권한 체계를 유지하면서 Claude Code의 agent loop를 활용할 수 있다.

SDK가 제공하는 built-in tools는 강력하다. 파일을 읽고 쓰고, 명령을 실행하고, 웹 검색을 할 수 있다. 그래서 안전장치 없이 제품에 붙이면 위험하다. 사용자가 업로드한 프로젝트를 분석하는 agent와 회사 저장소를 수정하는 agent는 권한 레벨이 완전히 다르다.

제품 설계에서는 tool permission을 기능별로 나눠야 한다. read-only analysis, local write, command execution, network access, external write를 같은 권한으로 묶으면 안 된다. 처음에는 read-only와 명령 실행 없는 flow부터 시작하는 편이 좋다.

sessions와 fork는 사용자 경험을 바꾼다

Agent SDK에는 sessions가 있다. 맥락을 여러 exchange에 걸쳐 유지하고, 나중에 resume하거나 fork할 수 있다. 이것은 제품 UX에 큰 영향을 준다. 사용자는 ‘아까 그 작업 이어서 해줘’, ‘방금 계획에서 테스트 추가 버전으로 갈라서 해봐’ 같은 흐름을 기대하게 된다.

세션 기능을 넣을 때는 저장 정책이 필요하다. 어떤 프롬프트와 도구 결과를 보관할지, 파일 내용이 얼마나 남는지, 사용자가 삭제할 수 있는지 정해야 한다. 코드와 로그에는 secret, 고객 정보, 내부 URL이 섞일 수 있다. 편리한 session resume이 곧 데이터 보관 책임이 된다.

Fork는 비교 실험에 좋다. 같은 초기 분석에서 A안은 최소 수정, B안은 리팩터링 포함으로 갈라 실행할 수 있다. 하지만 최종 반영된 branch와 버려진 fork를 명확히 표시해야 한다. 그렇지 않으면 사용자가 어떤 결과를 신뢰해야 하는지 헷갈린다.

hooks와 subagents는 구조화된 확장이다

Agent SDK는 hooks와 subagents를 제공한다. Hooks는 agent lifecycle의 특정 지점에서 custom code를 실행한다. 예를 들어 도구 호출 전 권한 검사, 명령 실행 후 로그 수집, 작업 완료 전 테스트 실행을 붙일 수 있다.

Subagents는 집중된 하위 작업에 유용하다. 코드베이스 전체를 다루는 agent 안에서 test-fixer, docs-writer, security-reviewer 같은 specialized agent를 부를 수 있다. 다만 역할 이름만 나누면 복잡도만 늘어난다. subagent는 권한, 입력 범위, 성공 기준이 분리될 때만 쓰는 편이 낫다.

좋은 패턴은 main agent가 planning과 coordination을 담당하고, subagent는 read-only review나 특정 파일 범위의 작업만 수행하는 구조다. 보안 리뷰 subagent에는 write 권한을 주지 않는 편이 안전하다.

branding과 인증 제한도 제품 설계에 포함된다

문서에는 파트너가 Claude branding을 사용할 때 허용 표현과 금지 표현이 적혀 있다. 예를 들어 제품이 Claude Code처럼 보이거나 Claude Code-branded ASCII art를 흉내 내면 안 된다. ‘Claude Agent’나 ‘Powered by Claude’ 같은 표현은 조건 안에서 가능하다.

또 하나 중요한 제한은 인증이다. 문서의 note에는 별도 승인이 없다면 third party developer가 claude.ai login이나 rate limits를 자신의 제품에 제공할 수 없고, Quickstart의 API key 인증 방식을 사용하라고 되어 있다. 즉 고객에게 ‘Claude 계정으로 로그인해서 우리 제품 agent를 쓰세요’라는 식으로 설계하면 안 될 수 있다.

제품 출시 전에는 기술 통합만 보지 말고, 인증 방식과 브랜딩 문구가 약관에 맞는지 확인해야 한다. 이 부분을 늦게 발견하면 UI와 온보딩을 다시 짜야 한다.

실행 체크리스트

• 터미널 작업은 CLI, 직접 API 제어는 Client SDK, 제품 내 agent loop는 Agent SDK, hosted long-running 작업은 Managed Agents로 나눈다.
• Agent SDK 도입 전 read-only, local write, command execution, external write 권한을 분리한다.
• session resume과 fork를 제공한다면 보관 데이터, 삭제 정책, 최종 선택 표시를 설계한다.
• hooks는 테스트·로그·권한 검사처럼 검증 가능한 용도부터 붙인다.
• subagent는 역할 이름이 아니라 권한과 성공 기준이 다를 때만 만든다.
• claude.ai login이나 rate limit을 third party 제품에 제공하지 않도록 인증 방식을 확인한다.
• Claude branding 문구가 Anthropic 가이드라인에 맞는지 출시 전에 점검한다.

출처: Anthropic Claude Agent SDK overview