Claude Agent SDK의 개요
Claude Agent SDK를 쓰면 Python이나 TypeScript 프로그램이 Claude Code를 움직이는 것과 같은 에이전트 루프, 도구, 컨텍스트 관리를 실행할 수 있습니다. 예전 이름은 Claude Code SDK였습니다. 라이브러리는 함께 들어 있는 Claude Code 바이너리를 띄워 메시지를 주고받으므로, 그 위에 만든 에이전트는 처음부터 파일을 읽고 쓰고 편집하며, 셸 명령을 실행하고, 웹을 검색할 수 있습니다.
query()는 일회성 작업을 비동기 스트림으로 실행합니다. ClaudeSDKClient는 양방향 세션을 유지하며, 평범한 Python 함수로 작성해 프로세스 내 MCP 서버로 제공하는 사용자 정의 도구와, 에이전트 수명 주기의 특정 지점에서 내 코드를 실행하는 훅을 더합니다. 서브에이전트, 재개하거나 분기할 수 있는 세션, 권한 모드, skills, plugins, .claude/ 폴더의 프로젝트 메모리는 Claude Code에서 그대로 넘어옵니다.
Python 패키지는 Python 3.10 이상이 필요합니다. 버전 0.2.178은 2026년 11월 4일 Claude Code 2.1.318을 포함해 나왔고, TypeScript 패키지는 @anthropic-ai/claude-agent-sdk로 배포됩니다.
Claude Agent SDK, 쓸 만한 가치가 있습니까?
Agent SDK의 가치는 어려운 부분이 이미 다 짜여 있다는 점입니다. 파일 편집, 셸 접근, 컨텍스트 압축, 서브에이전트, 권한 확인은 Anthropic이 며칠마다 업데이트하는 Claude Code에서 오므로, 열 줄짜리 query() 호출만으로 실제 저장소의 버그를 고치는 에이전트가 생깁니다. OpenAI Agents SDK나 LangGraph 같은 경쟁 프레임워크는 조립할 부품을 주지만, 이 SDK는 제약을 걸어야 할 완성된 실행 환경을 줍니다.
이 역전이 보안 모델을 결정합니다. 기본적으로 Claude는 Bash와 Write를 포함한 Claude Code 도구 전체를 갖습니다. allowed_tools는 나열한 도구를 자동 승인할 뿐 나머지를 없애지 않으며, 나머지는 권한 모드와 can_use_tool 콜백의 판단으로 넘어갑니다. 도구를 없애려면 disallowed_tools가 필요합니다. 서비스에 SDK를 넣는다면 quickstart보다 권한 가이드를 먼저 읽고, 입력을 믿을 수 없다면 프로세스를 컨테이너에서 돌려야 합니다.
오픈소스라는 이름표에는 각주가 필요합니다. Python 래퍼는 MIT 라이선스지만 실제 일은 포함된 Claude Code 바이너리가 하고, 문서는 SDK 사용에 Anthropic의 Commercial Terms가 적용된다고 밝힙니다. TypeScript 저장소는 모든 권리 보유로 표시돼 있습니다. 에이전트 루프는 포크할 수 없고 설정만 할 수 있습니다.
릴리스 주기는 Claude Code를 따릅니다. 2026년 9월 15일부터 11월 4일까지 Python 릴리스가 25번 나와 0.2.153에서 0.2.178이 됐지만 아직 1.0 미만입니다. 저장소에는 별 약 8,440개, 열린 이슈와 풀 리퀘스트 616개가 있습니다. 문서는 승인 없이 서드파티 제품이 claude.ai 로그인이나 플랜 사용량을 제공하는 것을 금지하므로, SDK로 만든 제품은 API 키로 과금합니다. 개발자 자신의 컴퓨터에서 로그인해 쓰는 사용량은 그 사람의 Claude 플랜에서 차감됩니다. 2026년 6월 15일 시작한다고 발표된 SDK 월간 크레딧은 바로 그날 보류됐습니다.
제 역할을 하는 곳
개발자 100명 규모 회사의 플랫폼 엔지니어
실패한 CI 작업을 분류하고 패치를 제안하는 사내 봇 운영하기
CI 러너에서 query()를 호출하며 cwd는 체크아웃 위치로, 저장소 밖은 disallowed_tools로 막고, 네트워크 명령을 막는 PreToolUse 훅을 붙입니다. 사용료는 자체 지출 한도가 있는 Console API 키로 청구됩니다.
문서 관리 제품에 에이전트를 더하는 스타트업
고객이 에이전트에게 파일 정리와 요약을 맡기게 하기
제품 자체의 동작을 @tool 데코레이터와 create_sdk_mcp_server로 도구로 노출해 프로세스 안에서 돌립니다. 고객 세션은 각자의 컨테이너에서 실행하고, claude.ai 로그인이 허용되지 않으므로 과금은 API 키로 합니다.
자기 노트북에서 잡무를 자동화하는 1인 개발자
에이전트 루프를 짜지 않고 반복되는 리팩터링을 스크립트로 만들기
ClaudeSDKClient와 acceptEdits 모드를 쓰는 짧은 Python 스크립트로 편집을 처리합니다. 개인 Claude 플랜으로 로그인하면 별도 청구 대신 그 플랜의 사용량에서 차감됩니다.
도입 전 확인할 점
- 설정
- Python 3.10 이상에서 pip install claude-agent-sdk(또는 npm install @anthropic-ai/claude-agent-sdk)를 실행하고 API 키를 설정하면 quickstart의 버그 수정 에이전트가 몇 분 안에 돌아갑니다. Claude Code를 따로 설치할 필요는 없습니다.
- 연동
- MCP 서버, 프로세스 내 사용자 정의 도구, 훅, 서브에이전트, .claude/ 폴더의 skills와 plugins. 모델 접근은 Claude API, Amazon Bedrock, Google Cloud, Microsoft Foundry.
- 데이터와 개인정보
- 자기 프로세스의 권한으로 로컬에서 돌며, 계정의 API 또는 플랜 조건에 따라 프롬프트와 파일 내용을 Claude로 보냅니다. 기본 도구 세트는 프로세스가 닿는 곳이면 어디서든 읽고 쓰고 실행할 수 있습니다.
- 대규모 사용 시 비용
- SDK는 무료이고 비용은 API 요금의 Claude 토큰입니다. 도구 호출이 많은 에이전트 루프는 작업당 토큰을 몇 배로 늘립니다. Max, Ultra, Team 플랜에는 연결된 Console 키로 쓸 수 있는 월간 API 크레딧이 포함됩니다.
- 제한
- Claude 모델만 지원. 1.0 미만 API로 잦은 릴리스. 브랜드 규정상 제품을 Claude Code라고 부를 수 없음. 에이전트 루프 자체는 수정할 수 없습니다.
좋은 점
- Claude Code의 파일, 셸, 웹 도구를 처음부터 사용
- 별도 프로세스 없이 프로세스 내 MCP 서버로 사용자 정의 도구 제공
- 훅, 서브에이전트, 세션, plugins를 그대로 이어받음
- API, Bedrock, Google Cloud, Foundry에서 같은 엔진
- Claude Code에 맞춘 잦은 릴리스
아쉬운 점
- 핵심 바이너리는 비공개이며 Anthropic의 Commercial Terms 적용
- 기본적으로 모든 도구 사용 가능, allowed_tools는 제한하지 않음
- Claude 모델만 지원
- 1.0 미만이며 며칠마다 릴리스
- 제품 사용자에게 claude.ai 로그인을 제공할 수 없음
추천 대상
Claude Code 수준의 코딩·파일 작업 에이전트를 자사 제품에 넣으려 하며 Claude로 표준화한 개발자.
Claude Agent SDK 대안
Claude Agent SDK: 자주 묻는 질문
- Claude Agent SDK, 쓸 만한 가치가 있습니까?
- 파일을 편집하고 명령을 실행할 줄 아는 에이전트로 가는 가장 빠른 길입니다. 단, 그 안에 닫힌 엔진으로 들어 있는 Claude Code를 받아들인다면 말입니다. 평점은 5점 만점에 4.2점입니다.
- Claude Agent SDK의 가격은 얼마입니까?
- Python 래퍼는 MIT 라이선스로 무료입니다. 포함된 Claude Code 바이너리와 TypeScript 패키지는 Anthropic의 Commercial Terms를 따릅니다. 비용은 Claude API 사용료이거나 내 Claude 플랜 사용량 차감입니다.
- Claude Agent SDK의 단점은 무엇입니까?
- 핵심 바이너리는 비공개이며 Anthropic의 Commercial Terms 적용; 기본적으로 모든 도구 사용 가능, allowed_tools는 제한하지 않음; Claude 모델만 지원; 1.0 미만이며 며칠마다 릴리스; 제품 사용자에게 claude.ai 로그인을 제공할 수 없음.
- Claude Agent SDK에 적합한 사람은 누구입니까?
- Claude Code 수준의 코딩·파일 작업 에이전트를 자사 제품에 넣으려 하며 Claude로 표준화한 개발자.
- 팀이나 프로덕션 환경에서 Claude Agent SDK의 비용은 얼마입니까?
- SDK는 무료이고 비용은 API 요금의 Claude 토큰입니다. 도구 호출이 많은 에이전트 루프는 작업당 토큰을 몇 배로 늘립니다. Max, Ultra, Team 플랜에는 연결된 Console 키로 쓸 수 있는 월간 API 크레딧이 포함됩니다.
- Claude Agent SDK에 회사 데이터를 맡겨도 안전합니까?
- 자기 프로세스의 권한으로 로컬에서 돌며, 계정의 API 또는 플랜 조건에 따라 프롬프트와 파일 내용을 Claude로 보냅니다. 기본 도구 세트는 프로세스가 닿는 곳이면 어디서든 읽고 쓰고 실행할 수 있습니다.
- Claude Agent SDK의 가장 좋은 대안은 무엇입니까?
- 저희가 리뷰한 것 중 가장 가까운 대안은 OpenAI Agents SDK, Pydantic AI, LangGraph 및 Google Agent Development Kit (ADK)입니다.
답변 확인일: 2026년 11월 6일.
Claude Agent SDK 개발사입니까? 이 평점을 사이트에 표시하십시오
