Claude Code SDK

 (docs.anthropic.com)
1P by GN⁺ | ★ favorite | 댓글 1개
  • Claude Agent SDK는 Claude Code의 도구 실행, 에이전트 루프, 컨텍스트 관리를 Python·TypeScript 코드에서 제어하게 해 파일 읽기, 명령 실행, 웹 검색, 코드 편집을 자동화함
  • 기본 도구로 Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion을 제공해 코드베이스 탐색부터 사용자 확인 질문까지 별도 실행 계층 없이 처리할 수 있음
  • 훅, 서브에이전트, MCP, 권한, 세션을 조합하면 파일 변경 감사 로그, 코드 리뷰 전용 서브에이전트, Playwright 기반 브라우저 자동화, 읽기 전용 분석 에이전트 같은 구성이 가능함
  • 설치는 @anthropic-ai/claude-agent-sdk 또는 claude-agent-sdk로 진행하며, Python은 3.10 이상이 필요하고 TypeScript SDK는 플랫폼용 네이티브 Claude Code 바이너리를 선택 의존성으로 포함함
  • Agent SDK는 도구 루프를 직접 구현하는 Anthropic Client SDK와 달리 내장 도구 실행을 제공하며, Managed Agents처럼 Anthropic 인프라가 아니라 사용자 프로세스와 인프라에서 실행됨

Claude Agent SDK가 맡는 범위

  • Claude Agent SDK는 Claude Code를 구동하는 도구, 에이전트 루프, 컨텍스트 관리를 Python과 TypeScript에서 사용할 수 있게 함
  • 에이전트는 파일 읽기, 명령 실행, 웹 검색, 코드 편집을 수행할 수 있음
  • 내장 도구 실행이 포함돼 사용자가 별도 도구 실행 계층을 직접 만들지 않아도 에이전트가 작업을 시작할 수 있음
  • 기본 예시는 auth.py의 버그를 찾고 고치는 작업에 Read, Edit, Bash 도구를 허용함

설치와 인증 흐름

  • 언어별 패키지로 설치함
    • TypeScript: npm install @anthropic-ai/claude-agent-sdk
    • Python: pip install claude-agent-sdk
  • Python 패키지는 Python 3.10 이상이 필요함
    • No matching distribution found for claude-agent-sdk 오류가 나면 인터프리터가 3.10보다 오래된 버전일 수 있음
    • macOS 또는 Linux에서는 python3 --version, Windows에서는 py --version으로 확인함
  • TypeScript SDK는 플랫폼용 네이티브 Claude Code 바이너리를 선택 의존성으로 포함하므로 Claude Code를 별도로 설치할 필요가 없음
  • API 키는 Console에서 발급받아 ANTHROPIC_API_KEY 환경 변수로 설정함
  • 서드파티 API 제공자 인증도 지원함
    • Amazon Bedrock: CLAUDE_CODE_USE_BEDROCK=1 설정 후 AWS 자격 증명 구성
    • Claude Platform on AWS: CLAUDE_CODE_USE_ANTHROPIC_AWS=1, ANTHROPIC_AWS_WORKSPACE_ID 설정 후 AWS 자격 증명 구성
    • Google Vertex AI: CLAUDE_CODE_USE_VERTEX=1 설정 후 Google Cloud 자격 증명 구성
    • Microsoft Azure: CLAUDE_CODE_USE_FOUNDRY=1 설정 후 Azure 자격 증명 구성
  • Anthropic은 사전 승인 없이는 서드파티 개발자가 Claude Agent SDK 기반 제품에 claude.ai 로그인이나 rate limit을 제공하는 것을 허용하지 않음

기본 도구와 에이전트 기능

  • SDK는 Claude Code의 주요 기능을 코드에서 다룰 수 있게 함
    • 내장 도구
    • 훅
    • 서브에이전트
    • MCP
    • 권한
    • 세션
  • 주요 내장 도구는 다음 역할을 수행함
    • Read: 작업 디렉터리 안의 파일 읽기
    • Write: 새 파일 생성
    • Edit: 기존 파일에 정밀한 편집 적용
    • Bash: 터미널 명령, 스크립트, git 작업 실행
    • Monitor: 백그라운드 스크립트를 감시하고 각 출력 줄에 이벤트로 반응
    • Glob: **/*.ts, src/**/*.py 같은 패턴으로 파일 찾기
    • Grep: 정규식으로 파일 내용 검색
    • WebSearch: 최신 정보를 웹에서 검색
    • WebFetch: 웹 페이지 콘텐츠 가져오기와 파싱
    • AskUserQuestion: 복수 선택 옵션으로 사용자에게 확인 질문하기
  • 예시 에이전트는 Read, Glob, Grep를 허용해 코드베이스의 TODO 주석을 찾아 요약함

훅, 서브에이전트, MCP

  • 훅(hook) 은 에이전트 생명주기의 주요 지점에서 사용자 코드를 실행함
    • 콜백 함수로 에이전트 동작을 검증, 기록, 차단, 변환할 수 있음
    • 사용 가능한 훅에는 PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit 등이 있음
    • 예시는 PostToolUse에서 Edit|Write 작업을 감지해 audit.log에 파일 변경을 기록함
  • 서브에이전트는 집중된 하위 작업을 처리하는 특화 에이전트임
    • 메인 에이전트가 작업을 위임하고 서브에이전트가 결과를 반환함
    • 커스텀 에이전트는 설명, 프롬프트, 사용할 도구로 정의함
    • 서브에이전트 호출은 Agent 도구를 통해 이뤄지므로 자동 승인하려면 allowedTools에 Agent를 포함해야 함
    • 서브에이전트 컨텍스트 안의 메시지는 parent_tool_use_id 필드를 포함해 어떤 서브에이전트 실행에 속하는지 추적할 수 있음
  • Model Context Protocol(MCP) 로 데이터베이스, 브라우저, API 등 외부 시스템에 연결할 수 있음

권한과 세션 관리

  • 권한 설정은 에이전트가 사용할 수 있는 도구를 제한함
    • 안전한 작업은 허용하고, 위험한 작업은 차단하며, 민감한 동작에는 승인을 요구할 수 있음
    • 예시는 Read, Glob, Grep만 사전 승인해 코드를 분석하되 수정하지 않는 읽기 전용 에이전트를 구성함
  • AskUserQuestion 도구와 대화형 승인 프롬프트는 사용자 입력 처리 흐름에서 함께 사용됨
  • 세션은 여러 교환에 걸쳐 컨텍스트를 유지함
    • Claude는 읽은 파일, 수행한 분석, 대화 기록을 기억함
    • 이후 같은 세션을 재개하거나 다른 접근을 탐색하기 위해 포크할 수 있음
    • 예시는 첫 번째 쿼리에서 session_id를 얻고, 두 번째 쿼리에서 resume=session_id로 같은 컨텍스트를 이어감

Claude Code 설정 지원

  • SDK는 Claude Code의 파일시스템 기반 설정을 지원함
  • 기본 옵션에서는 작업 디렉터리의 .claude/와 ~/.claude/에서 설정을 로드함
  • 로드할 설정 소스를 제한하려면 Python에서는 setting_sources, TypeScript에서는 settingSources 옵션을 사용함
  • 지원 기능과 위치는 다음과 같음
    • Skills: Claude가 자동 사용하거나 /name으로 호출하는 특화 기능, .claude/skills/*/SKILL.md
    • Commands: 레거시 형식의 커스텀 명령, .claude/commands/*.md
    • Memory: 프로젝트 컨텍스트와 지시사항, CLAUDE.md 또는 .claude/CLAUDE.md
    • Plugins: skills, agents, hooks, MCP servers 확장, plugins 옵션으로 프로그래밍 방식 구성

다른 Claude 도구와의 차이

  • Anthropic Client SDK는 직접 API 접근을 제공하며, 사용자가 프롬프트를 보내고 도구 실행을 직접 구현함
  • Agent SDK에서는 Claude가 도구 처리를 자율적으로 수행함
    • Client SDK에서는 사용자가 도구 루프를 구현함
    • Agent SDK는 Claude에 내장 도구 실행을 제공함
  • 용도별 선택 기준은 다음과 같음
    • 대화형 개발: CLI
    • CI/CD 파이프라인: SDK
    • 커스텀 애플리케이션: SDK
    • 일회성 작업: CLI
    • 프로덕션 자동화: SDK
  • 여러 팀은 일상 개발에는 CLI를, 프로덕션에는 SDK를 함께 사용하며 워크플로는 서로 직접 옮길 수 있음
  • Managed Agents는 Anthropic이 에이전트와 샌드박스를 실행하는 호스팅 REST API임
  • Agent SDK는 사용자 프로세스 안에서 에이전트 루프를 실행하는 라이브러리임
    • 실행 위치: Agent SDK는 사용자 프로세스와 인프라, Managed Agents는 Anthropic 관리 인프라
    • 인터페이스: Agent SDK는 Python 또는 TypeScript 라이브러리, Managed Agents는 REST API
    • 작업 대상: Agent SDK는 사용자 인프라의 파일, Managed Agents는 세션별 관리형 샌드박스
    • 세션 상태: Agent SDK는 파일시스템의 JSONL, Managed Agents는 Anthropic 호스팅 이벤트 로그
    • 커스텀 도구: Agent SDK는 프로세스 내 Python 또는 TypeScript 함수, Managed Agents는 Claude가 도구를 트리거하고 사용자가 실행 결과를 반환
    • 적합한 용도: Agent SDK는 로컬 프로토타이핑과 파일시스템·서비스에 직접 접근하는 에이전트, Managed Agents는 샌드박스나 세션 인프라를 운영하지 않는 프로덕션 에이전트와 장기 실행·비동기 세션
  • 일반적인 경로는 Agent SDK로 로컬 프로토타입을 만든 뒤 프로덕션에서는 Managed Agents로 옮기는 방식임

변경 로그, 버그 신고, 브랜딩

  • SDK 업데이트, 버그 수정, 새 기능은 각 저장소의 변경 로그에서 확인함
  • 버그나 이슈는 GitHub에서 신고함
  • 파트너가 Claude Agent SDK를 통합할 때 Claude 브랜딩 사용은 선택 사항임
    • 허용: “Claude Agent”, “Claude”, “Powered by Claude”
    • 금지: “Claude Code”, “Claude Code Agent”, Claude Code 브랜드 ASCII 아트 또는 Claude Code를 모방한 시각 요소
    • 제품은 자체 브랜딩을 유지해야 하며 Claude Code 또는 Anthropic 제품처럼 보여서는 안 됨
  • Claude Agent SDK 사용에는 Anthropic’s Commercial Terms of Service가 적용됨
    • 특정 컴포넌트나 의존성이 해당 컴포넌트의 LICENSE 파일에서 다른 라이선스를 명시한 경우는 예외임

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • Claude Code가 지향하는 방향은 내가 에이전트형 코딩 도구에서 원하는 것과 정확히 맞고, “Unix 도구 같은” 철학도 좋음
    공개 프리뷰 초기부터 써 왔는데 방향성이 보였음. 코딩 에이전트의 이상적인 최종 상태는 Jira 티켓 같은 기능 요청을 주면 검토하고 피드백할 PR을 만들어 주는 것이라고 봄. 그런 의미에서 Cursor, Windsurf 같은 로컬 편집기 중심 도구는 CI 안에서 동작할 수 없어서 막다른 길에 가까움. 코드베이스를 AI에 맞게 규칙, MCP 등으로 정비한다면 헤드리스 사용까지 이어질 수 있는 기술을 목표로 해야 함. Claude Code는 도구를 통해 자동화 일부로 쉽게 쓸 수 있어서, 이제 코딩 에이전트를 생각할 때 기본값이 됐고 Codex npm 패키지도 비슷함. 다만 회사들이 에이전트 활용에 맞게 코드베이스를 정비하도록 돕는 일을 하니, 쉽게 설정 가능한 도구 쪽으로 편향이 있을 수 있음

    • 그 “이상적인 최종 상태”에는 동의하기 어려움. 내가 원하는 모습은 방 안에서 여러 화면에 둘러싸여 AI 에이전트들이 코딩, 설계, 테스트를 하고, 나는 중앙에서 방향을 잡아 주고 취향을 적용하는 것임
      전부 대화로 이뤄지고, 99%는 키보드를 만질 필요가 없는 형태를 기대함
    • 아니라고 봄. 코딩 에이전트의 “이상적인” 최종 상태는 내 컴퓨터나 내가 원하는 머신에서 돌아가는 자유·오픈소스 코딩 에이전트임
      터미널에서 ls, ps, kill 같은 명령을 실행할 때마다 돈을 낸다고 상상해 보면 말이 안 됨. LLM도 마찬가지임. 독점 LLM을 금지하자는 뜻은 아니지만, 예전의 해커들이 주 도구로 삼아야 하는 건 자유롭고 오픈소스인 도구여야 함
    • Anthropic도 오늘 비슷한 방향의 기능을 베타로 발표함: https://docs.anthropic.com/en/docs/claude-code/github-action...
    • Cursor와 MCP로도 이런 작업을 해 봤음. 하루 정도 지나니 사용량 제한에 걸려 가장 느리고 멍청한 모델로 떨어졌음
      Claude로도 해 봤지만 금방 제한을 소진함. PR이 바로 “가도 되는” 수준인 경우는 25% 정도뿐이고, AI가 어디서 망쳤는지 찾느니 그냥 제대로 직접 하는 편이 더 빠를 때가 많음
    • 기능 요청을 주면 검토할 PR을 만들어 주는 상태라는 말은 이해하지만, 그러면 소프트웨어 작업에서 가장 영혼을 갉아먹는 부분인 Jira 티켓만 남는 셈이라 우울함

  • Claude Code는 코딩에 LLM을 쓰는 방식 중 가장 마음에 듦
    하지만 진짜 필요한 건 아무 모델이나 넘길 수 있고, 여러 모델의 답변도 비교할 수 있는 오픈소스 버전이라고 봄. Aider나 다른 대안은 Claude Code만큼 쓰기 좋게 느껴지지 않음. Anthropic 입장에서는 해자가 사라지니 원하지 않겠지만, 소비자 입장에서는 특정 생태계에 묶이지 않고 최고의 모델을 쓰고 싶을 뿐임. 아마 이게 LLM 모델 제공사들이 가장 두려워하는 지점일 듯함

    • OpenAI Codex가 아마 가장 가까운 대안임. 오픈소스이고 어느 제공사의 모델이든 사용할 수 있음
      지금은 Claude Code만큼 좋지는 않지만 금방 따라잡을 것 같음. https://github.com/openai/codex/tree/main
    • OpenCode 프로젝트가 관심에 맞을 수 있음: https://github.com/opencode-ai/opencode
      아직 개발 중이지만 유망해 보임
    • Claude Code가 Aider보다 더 잘하는 것이 뭔지 궁금함
    • 최근에 자기 홍보를 너무 많이 하긴 했지만, 이전 댓글을 보면 내가 Go로 만든 서비스가 있음. 정확히 이런 요구를 겨냥한 것임
    • 동의하지만, 다른 모델도 MCP 서버와 작업하는 법을 알도록 훈련돼 있어야 하는 것 아닌가? 아니면 문제가 안 되는 건가?

  • Aider는 오래전부터 Python과 셸 스크립팅을 지원해 왔음 [0]
    최근 130개 새 프로그래밍 언어 지원을 추가하는 과정에서 즉석 Bash 스크립팅을 Aider로 하는 스크린캐스트도 만들었음 [1]. 이런 접근이 얼마나 강력할 수 있는지 감을 줄 수 있음.
    [0] https://aider.chat/docs/scripting.html
    [1] https://aider.chat/docs/recordings/tree-sitter-language-pack...

    • Aider를 정말 좋아함. MCP도 곧 지원될 예정이고, 개발 브랜치를 테스트 중임
      그러면 신뢰하는 모델을 써서 PR, 티켓 등을 통해 처음부터 끝까지 개발할 수 있음
    • Aider를 Claude Code에 얼마나 가깝게 만들 수 있는지 궁금함. Claude Code의 사용자 경험은 좋았지만, Gemini 2.5 Pro를 선호해서 쓰지 않음
      커밋까지 해 주는 건 별로 원하지 않고, 주로 Claude Code의 사용감이 마음에 듦
    • Aider는 잘 다듬어진 GitHub Actions 워크플로가 있으면 크게 좋아질 수 있음
      저장소에 파일 하나만 추가하면 이슈를 통해 어떤 모델과도 대화할 수 있는 식이면 됨

  • Claude Code 팀이 더 자세히 다룬 내용: http://latent.space/p/claude-code
    대본만 훑어봐도 되는데, 개인적으로는 Anthropic 직원들이 무제한 Claude를 쓰면서도 평균 하루 6달러 정도 사용한다는 점, 헤드리스 Claude Code를 CI 어디서나 쓰는 “Linux” 유틸리티처럼 보는 점, 사용자 확장 가능한 플랫폼으로 보는 점, 샌드박싱·브랜칭·계획 기능이 향후 로드맵에 있다는 점, Sonnet 3.7을 지속형 에이전트 모델로 보는 점이 인상적임

    • 링크에는 Anthropic 내부 엔지니어 중 하루에 1,000달러 넘게 쓴 사람도 있다고 되어 있음
      직원별 지출의 P50, P75, P95가 얼마인지가 궁금함
    • 내가 잘못 쓰는 건지도 모르지만, Claude Code를 2시간 쓰면 쉽게 20달러 이상 나감
      개인 프로젝트에는 너무 비싸서 사용을 중단했음
    • 최근 latent space 팟캐스트를 정말 즐겁게 듣고 있음. 높은 신호대잡음비를 유지하면서도 전반적인 산출량이 이 정도인 사람이나 팟캐스트는 거의 없다고 봄
      지난 반년 혹은 몇 년 동안 여러 사업을 키우면서도 공개 작업의 양과 가치가 계속 커지는 게 놀라움. 다른 사람들도 비슷한 생산성 기울기를 찾을 수 있으면 좋겠음. 대략 무엇이 잘 맞는지 공유하긴 하지만 재현하기는 쉽지 않음. simonw, gwern 정도가 떠오름
    • 그 팟캐스트가 얼마나 중립적이었는지, 아니면 그냥 이 제품의 영업성 홍보였는지 궁금함

  • 내가 AI 코드 어시스턴트를 만든다면, 특정 기반 모델 제공사에 묶어 두는 일은 제일 마지막에 할 것임
    이 제품이 성공하려면 지금 막 모델 성능이 고원에 도달했고, 모든 기반 모델이 거의 같은 성능과 능력으로 수렴하며, 통합 업체들이 익숙한 SDK 같은 사소한 편의로 선택하게 된다는 전제가 필요함

    • 명령과 인자를 제외하면 묶이는 부분이 많지 않음. 그냥 입력과 출력일 뿐임
      다른 것으로 바꾸거나 래퍼를 씌우면 됨. 여기서 복잡한 일은 많지 않음
    • 지금 시점에서 Claude Code는 에이전트형 코딩 영역의 소프트웨어 차별화 요소임
      AI 코드 어시스턴트 관련 무언가를 만들고 있는데, Claude Code를 통합하는 방법부터 해킹하고 있었음. 우리가 가장 먼저 그 위에 만들고 싶었던 대상임. 락인을 걱정하기엔 너무 이르고, 최고가 필요하니 최고를 중심으로만 만들 것임

  • Claude Code는 이미 비대화형 모드로 쓸 수 있었고, 따라서 다른 Unix 명령줄 유틸리티처럼 다른 앱에 통합할 수 있었음
    이 SDK는 현재 명령줄 사용만 지원하는 것 같은데, 그러면 이미 있던 것과 같은 것 아닌가? 실제로 뭐가 새로워진 건지 모르겠음. 내가 놓친 게 뭔가?

    • 나도 모르겠음. 내가 보기엔 아무도 이 점을 거의 얘기하지 않는 것 같아 이상함

  • Codebuff(https://www.codebuff.com/)도 추천함. Claude Code와 비슷한 훌륭한 CLI 코드 어시스턴트이고 토큰 비용을 많이 절약할 수 있음
    이 프로젝트와 관련은 없고 그냥 사용자임

  • 약관에 “서비스와 경쟁하는 제품이나 서비스를 개발하기 위해, 인공지능 또는 머신러닝 알고리즘이나 모델을 개발·훈련하거나 서비스를 재판매하기 위해 사용할 수 없다”고 되어 있음
    일반 지능과 경쟁하지 않는 소프트웨어 제품이나 서비스가 대체 뭐가 있는지 궁금함. 지능을 팔면서 엄격히 해석하면 아무 데도 쓰지 말라는 법적 조항을 붙이는 셈임. 너무 모호해서 집행 불가능한 건가? 일반 지능과 경쟁하는 데 쓸 수 없다면 산출물은 어떻게 소유한다는 건가? “법적 약관 따위 아무도 신경 안 쓴다”는 식인가? 아무도 신경 안 쓴다면 왜 서비스 사용에 포괄적 금지를 걸어 두는 건가? 이런 결과물을 받기 위해 소송 패소 책임까지 받아들여야 한다는 건지 의문이 너무 많음

    • 변호사들에게 마음대로 쓰게 두면 이런 일이 생김
    • “artificial”을 “general”로 바꿨으니 의미가 당연히 달라짐

  • 모델 락인이 있으면 사용에 큰 불리함이 됨. 누군가 최신 최고 성능 모델을 내놨는데 이미 이 인프라에 투자했다면 갇히게 됨
    나중에 개방하더라도, 해당 모델이 그 CLI에 맞게 특별히 훈련됐을 가능성이 높아서 잘 작동하지 않을 수 있음. Codex CLI만 봐도 Gemini 2.5 Pro를 쓸 수는 있지만 OpenAI 모델에 비해 무작위로 멈추거나 실패하는 일이 많음

  • 새 GitHub Action은 내가 찾던 바로 그 기능임: https://docs.anthropic.com/en/docs/claude-code/github-action...
    그런데 Claude Code의 Max 플랜으로 쓰는 방법은 없어 보임. 내가 보기엔 API 키만 받는 것 같음

답변달기