Claude Agent SDK 입문 — 나만의 AI 에이전트 만들기 (Python·TS)

클로드 활용법

API로 클로드를 부르는 데 익숙해졌다면, 다음은 스스로 도구를 쓰며 일하는 에이전트입니다. Claude Agent SDK는 Claude Code를 움직이는 바로 그 엔진(도구·에이전트 루프·컨텍스트 관리)을 코드로 쓰게 해줍니다. 이 글은 어떤 에이전트를 만들 수 있는지 살펴보고, 최소 에이전트를 만들어 안전하게 다루는 법까지 입문 수준으로 정리합니다. (단발 호출인 API와의 차이는 Claude API 입문을 참고하세요.)

1. 에이전트란, 그리고 언제 SDK를 쓰나

일반 API 호출은 “한 번 묻고 한 번 답”입니다. 반면 에이전트는 목표를 주면 스스로 도구를 골라 쓰고, 결과를 보고 다음 행동을 정하는 루프를 돕니다.

API로 충분 → 한 번의 입력 → 한 번의 출력(요약·분류·텍스트 생성).
Agent SDK가 필요 → 파일·셸·외부도구를 오가며 여러 단계 작업을 자동으로.

2. 이런 에이전트를 만들 수 있다 (사례)

개발·코드

코드 리뷰 봇 → PR이 열리면 보안·버그·스타일을 자동 리뷰하고 코멘트를 단다(GitHub MCP + Read·Grep).
버그 수정 에이전트 → 이슈를 받아 재현 → 수정 → 테스트 → PR 초안까지.
테스트 보강 에이전트 → 커버리지가 빈 분기를 찾아 테스트를 추가하고 실행.
마이그레이션 에이전트 → 레거시 문법을 신버전으로 일괄 변환(작게 나눠 검증).

데이터·분석

데이터 분석 에이전트 → CSV·DB를 읽어 집계·요약 리포트를 생성(Bash·Read + DB MCP).
모니터링 에이전트 → 매일 지표를 가져와 이상치를 찾아 알린다(예약 실행과 결합).

운영·지원

온콜 도우미 → 에러 로그(Sentry MCP)를 읽고 원인 가설·대응안을 정리.
문의 트리아지 → 고객 문의를 분류하고 답변 초안·담당 라우팅을 제안(최종 발송은 사람).

콘텐츠·업무 자동화

콘텐츠 파이프라인 → 초안 생성 → 사실 검수 → 정해진 형식으로 정리(발행은 승인 후).
문서 동기화 에이전트 → 코드 변경을 감지해 README·docstring을 갱신.

공통 패턴은 같습니다. 목표 + 허용 도구 + 권한 모드만 정하면 나머지 루프는 SDK가 돕니다. 단, 외부로 나가는 행동(발송·배포·결제)에는 사람 확인을 끼워 넣으세요.

3. 기업들은 이렇게 쓴다 (실제 도입 사례)

에이전트는 이미 현업에서 쓰이고 있습니다. 공개된 사례 몇 가지를 보면 감이 잡힙니다.

에이전트형 개발도구 회사 → Cursor·GitHub·Replit·Vercel·Asana 같은 곳이 클로드로 프로덕션급 에이전트를 만들고 있습니다.
디자인 시스템 자동화 → Bolt는 Claude Agent SDK 위에서 자율 디자인 시스템 에이전트를 구축합니다.
대규모 엔지니어링 → Shopify·Canva 등도 코드리뷰·대규모 리팩터링·CI 자동화에 Claude Code/에이전트를 활용하는 것으로 알려져 있습니다.
헬스케어·전문서비스 → Anthropic 고객 사례에 따르면 Novo Nordisk는 임상 문서 작업을 수 주에서 분 단위로 줄였고, Deloitte·Cox Automotive 등도 도입 효과를 공개했습니다.
글로벌 트렌드 리포트 → Anthropic의 2026 에이전트 코딩 트렌드 리포트에는 Rakuten·TELUS·Zapier·CRED 등의 사례가 담겼습니다.
국내 → 국내 팀들도 코드리뷰·리팩터링·인프라 자동화에 Claude Code를 적용한 경험을 잇따라 공유하고 있습니다.

패턴은 비슷합니다. 반복적이고 규칙이 분명한 작업(문서화·코드리뷰·데이터 처리·마이그레이션)부터 에이전트에 맡기고, 사람은 검토·승인에 집중합니다. 사례 수치·세부는 보도·공식 자료 기준이며, 도입 전 원문으로 확인하세요.

4. 최소 에이전트 만들기

설치는 한 줄입니다. 파이썬(3.10+) 또는 타입스크립트를 씁니다.

pip install claude-agent-sdk

핵심은 query() 함수입니다. 프롬프트와 옵션을 주면 SDK가 루프를 알아서 돌리고, 진행 메시지를 비동기로 흘려줍니다.

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="이 폴더의 README를 읽고 오타만 고쳐줘",
        options=ClaudeAgentOptions(
            system_prompt="너는 신중한 코딩 에이전트야.",
            allowed_tools=["Read", "Edit"],   # 허용할 도구만 화이트리스트
            permission_mode="default",         # 위험한 작업은 확인
        ),
    ):
        print(message)

anyio.run(main)

정확한 옵션명·시그니처는 버전에 따라 다를 수 있으니 공식 문서에서 확인하세요(파이썬은 snake_case, 타입스크립트는 camelCase). 최종 확인일 2026-05-26.

내장 도구는 Claude Code와 같습니다 — Read·Edit·Write·Bash·Glob·Grep. 루프·재시도·컨텍스트 정리는 SDK가 처리하므로, 우리는 무엇을 시킬지와 무엇을 허용할지에 집중하면 됩니다.

5. 실전 팁 — 권한·관측·실패 처리

권한 모드로 자율성 조절 → default(위험 작업 확인) / accept-edits(파일 변경 자동 승인) / bypass(완전 자율). 처음엔 default로 시작하세요.
도구 화이트리스트 → allowed_tools로 꼭 필요한 도구만 허용해 사고 범위를 좁힙니다.
관측 → 스트리밍 메시지를 로그로 남겨 에이전트가 무엇을 왜 했는지 추적하세요.
실패 처리 → 루프·재시도는 SDK가 처리하지만, 외부 작업(배포·결제 등)은 사람 확인 단계를 두세요.

6. Claude Code · MCP와의 관계

Claude Code → 이 Agent SDK 위에 만들어진 ‘완성된 터미널 앱’.
Agent SDK → 같은 엔진으로 나만의 에이전트를 직접 만드는 도구.
MCP → 에이전트에 외부 도구·데이터를 연결하는 표준. SDK의 mcp_servers 옵션으로 붙입니다.

즉 Claude Code가 마음에 들지만 내 워크플로우에 맞게 커스텀하고 싶을 때 Agent SDK로 내려가는 셈입니다.

7. 다음 학습 경로

서브에이전트 → 역할별 전문 에이전트를 분리해 부모가 호출.
훅(hooks) → 에이전트 생애주기에 콜백을 걸어 자동 검증·로깅.
세션 → 여러 query에 걸쳐 맥락 유지.

참고 — 2026-06-15부터 구독 플랜의 Agent SDK 사용량은 별도 월 크레딧에서 차감됩니다(Pro 월 $20, Max 20x $200 포함). 정확한 정책은 공식 문서에서 확인하세요.

마무리

Agent SDK는 “query()로 루프를 맡기고, 허용 도구와 권한만 통제”하면 시작할 수 있습니다. 위 사례 중 하나를 골라 작은 버전부터 만들어보세요. 이로써 개발자를 위한 클로드 활용법 시리즈를 마칩니다 — 채팅·Claude Code·API·MCP를 거쳐 직접 에이전트를 만드는 데까지 왔습니다. 전체 로드맵은 개발자를 위한 클로드 활용법에서 다시 볼 수 있습니다.

패키지·옵션·요금 정책은 변동될 수 있습니다. 최신 내용은 공식 문서를 확인하세요.

출처

함께 읽기

Claude 가격·요금제 2026 — Free·Pro·Max·Team·API 한눈에 비교

Claude API 입문 — 첫 호출부터 tool use까지

개발자를 위한 클로드 활용법 — 시리즈 허브

Claude Agent SDK로 나만의 AI 에이전트 만들기 — 입문