Claude Code 상세 사용법 15: Agent SDK로 내 자동화 만들기 | DAKER 커뮤니티

Claude Code 상세 사용법 15: Agent SDK로 내 자동화 만들기

Claude Code 공식 Agent SDK 문서는 SDK를 Python 또는 TypeScript에서 자율 에이전트를 만드는 방법으로 설명한다. CLI에서 claude -p를 호출하는 자동화가 "프롬프트를 실행하는 방식"이라면, Agent SDK는 메시지 스트림, 도구 권한, 세션, hooks, MCP를 코드 안에서 제어하는 방식이다.

아래 Mermaid는 Agent SDK 자동화가 단순 프롬프트 실행과 달라지는 지점을 정리한다. 세션, 권한, 스트림, 검증 결과를 제품 코드가 관리해야 할 때 SDK를 선택하는 편이 맞다.

1. SDK가 필요한 일을 먼저 고른다

처음부터 SDK로 모든 것을 감싸면 복잡해진다. 아래 조건이 있을 때만 SDK가 잘 맞는다.

단발 작업은 여전히 CLI가 단순하다. 예를 들어 매일 린트 실패를 요약하는 정도라면 claude -p와 쉘 스크립트가 더 유지보수하기 쉽다.

2. 최소 실행 파일부터 만든다

공식 quickstart 기준으로 Python은 claude-agent-sdk, TypeScript는 @anthropic-ai/claude-agent-sdk를 설치한다. SDK는 API 키 기반 인증을 전제로 하며, 기존 claude.ai 로그인 권한을 제품에 대신 빌려주는 방식으로 설계하면 안 된다.

4. query와 ClaudeSDKClient를 구분한다

query()는 매번 새 세션에 가까운 단발 작업에 어울린다. 반대로 ClaudeSDKClient는 같은 대화를 이어가거나 중간 입력, interrupt, 장기 실행 상태를 다뤄야 할 때 쓴다. 제품 기능으로 "리뷰 요청 → 사용자의 추가 질문 → 수정 반영"을 한 흐름에 넣으려면 client 쪽이 자연스럽다.

5. 운영 자동화는 결과 계약이 필요하다

SDK 자동화의 출력은 사람이 읽는 답변만 있으면 부족하다. 최소한 아래를 남긴다.

1. 수정한 파일
2. 실행한 명령
3. 실패한 명령과 로그 요약
4. 사용한 도구와 권한 모드
5. 다음 사람이 확인할 체크포인트

Senior takeaway: Claude Code Agent SDK는 "더 강한 CLI"가 아니라 제품과 CI 안에 Claude Code의 agentic coding 루프를 넣는 인터페이스다. 작은 읽기 전용 에이전트로 시작하고, 도구 권한과 검증 출력을 한 단계씩 올려야 자동화가 팀의 개발 생산성을 해치지 않는다.

mkdir my-agent
cd my-agent
uv init
uv add claude-agent-sdk

Python에서는 query()가 가장 작은 시작점이다.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="src 폴더의 테스트 누락 위험을 찾아 요약해줘.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            permission_mode="dontAsk",
        ),
    ):
        print(message)

asyncio.run(main())

이 예시는 읽기 전용 감사다. 처음부터 Bash와 Edit를 열지 않는 이유는 실패 모드가 단순하기 때문이다.

3. 권한 모드는 자동화 수준을 말한다

공식 문서의 핵심은 allowed_tools와 permission_mode를 같이 설계하는 것이다. dontAsk는 허용 도구 밖을 거절하므로 읽기 전용 분석에 좋다. acceptEdits는 파일 편집과 일부 파일 시스템 명령을 자동 승인하므로 신뢰한 로컬 리포지터리에서 쓴다. bypassPermissions는 격리된 CI나 샌드박스처럼 폭발 반경이 통제될 때만 고려한다.

Redirecting to Claude Code 상세 사용법 15: Agent SDK로 내 자동화 만들기 | DAKER 커뮤니티...