Claude Agent SDK 실전 — 자율 코딩 에이전트 직접 만들어보기

"Claude Code가 저절로 코드를 고친다고? 그 엔진, 이제 내 서버에서도 돌릴 수 있습니다."

이번에 다루는 것:
→ Claude Agent SDK가 일반 Anthropic API와 다른 이유
→ 설치 및 기본 에이전트 루프 구현 (Python / TypeScript)
→ 파일 편집·셸 실행·서브에이전트 병렬화 실전 예제
→ Managed Agents API로 클라우드 배포하기
→ 언제 쓰고, 언제 쓰지 말아야 하는지

---

배경 — Claude Code SDK에서 Claude Agent SDK로

Anthropic이 Claude Code를 만들면서 깨달은 게 있습니다. 에이전트에게 필요한 건 대화 능력이 아니라 컴퓨터 접근권이라는 것입니다.

파일을 읽고, 셸 명령을 실행하고, 결과를 보고 다시 수정하는 루프. 이 루프를 구현한 것이 Claude Code의 핵심 엔진이었고, Anthropic은 이 엔진을 외부 개발자에게 개방하면서 이름을 Claude Agent SDK로 바꿨습니다.

기존 Anthropic Client SDK 방식:
→ 개발자가 직접 tool_use 응답을 감지
→ 직접 툴을 실행하고 결과를 다시 messages에 넣음
→ stop_reason == "end_turn"일 때까지 루프를 직접 관리
→ 컨텍스트 오버플로우, 에러 핸들링 모두 직접 처리

Claude Agent SDK 방식:
→ Claude가 직접 툴 실행 루프를 자율 관리
→ 파일 편집, bash, 서브에이전트 스폰 기본 내장
→ 컨텍스트 한계 도달 시 자동 compaction
→ 개발자는 "뭘 할지"만 지시하면 됨

---

비교 — Client SDK vs Agent SDK

Client SDK:
→ 직접 tool_use 루프 구현 필요
→ 세밀한 제어 가능
→ 간단한 단일 턴 앱에 적합
→ 어떤 LLM 프로바이더와도 사용 가능

Agent SDK:
→ 에이전트 루프 자동화
→ bash, 파일 편집, 서브에이전트 기본 제공
→ 복잡한 멀티스텝 자동화에 적합
→ Claude 모델 전용

---

실전 1 — 설치 및 첫 번째 에이전트

패키지 설치부터 시작합니다.

# Python
pip install claude-agent-sdk

# TypeScript / Node.js
npm install @anthropic-ai/claude-agent-sdk

# API 키 환경변수 등록
export ANTHROPIC_API_KEY="sk-ant-..."

Claude Code CLI가 Agent SDK에 자동 번들됩니다. 별도 설치 불필요입니다.

가장 단순한 형태의 에이전트부터 만들어봅니다.

# Python — 기본 에이전트 실행
import asyncio
import claude_agent_sdk as agent

async def main():
    async for message in agent.query(
        prompt="현재 디렉토리의 Python 파일을 분석하고 \
                개선 사항을 README.md에 정리해줘",
        options=agent.ClaudeOptions(
            model="claude-opus-4-7-20260416",
            max_turns=30,
        )
    ):
        if message.type == "assistant":
            print(message.content)
        elif message.type == "tool_use":
            print(f"[툴 사용] {message.tool_name}: {message.input}")

asyncio.run(main())

개념 설명:
→ query()는 비동기 제너레이터 — 메시지를 스트리밍으로 받음
→ max_turns: 에이전트가 자율로 실행할 최대 툴 호출 횟수
→ message.type으로 어시스턴트 텍스트 / 툴 사용 / 결과 구분
→ 중단 조건 없으면 Claude가 "완료됐다" 판단할 때까지 실행

---

실전 2 — 파일 편집 + 셸 실행 에이전트

에이전트의 핵심 능력은 실제 파일을 건드리는 것입니다. 버그 픽스 에이전트를 만들어봅니다.

# Python — 자율 버그 픽스 에이전트
import asyncio
import claude_agent_sdk as agent

SYSTEM_PROMPT = """
당신은 자율 코드 수정 에이전트입니다.
주어진 버그를 분석하고, 파일을 직접 수정하고,
테스트를 실행해서 수정이 올바른지 검증하세요.
반드시 테스트를 통과한 뒤에만 완료를 선언하세요.
"""

async def fix_bug(issue_description: str, repo_path: str):
    async for message in agent.query(
        prompt=f"""
        저장소 경로: {repo_path}
        
        수정할 버그:
        {issue_description}
        
        1. 관련 파일 탐색
        2. 원인 분석
        3. 코드 수정
        4. 테스트 실행 및 검증
        5. 변경 사항 요약 출력
        """,
        options=agent.ClaudeOptions(
            model="claude-opus-4-7-20260416",
            system_prompt=SYSTEM_PROMPT,
            max_turns=50,
            allowed_tools=["bash", "text_editor"],  # 허용 툴 명시적 지정
        )
    ):
        print(message)

asyncio.run(fix_bug(
    issue_description="user_auth.py의 토큰 만료 검사 로직이 UTC 대신 로컬 시간을 사용하고 있음",
    repo_path="./my-project"
))

TypeScript 버전도 동일하게 동작합니다.

// TypeScript — 파일 수정 에이전트
import { query, ClaudeOptions } from "@anthropic-ai/claude-agent-sdk";

async function runAgent(task: string) {
  const options: ClaudeOptions = {
    model: "claude-opus-4-7-20260416",
    maxTurns: 40,
    allowedTools: ["bash", "text_editor"],
  };

  for await (const message of query({ prompt: task, options })) {
    if (message.type === "result") {
      console.log("완료:", message.result);
    }
  }
}

runAgent("package.json의 의존성을 분석하고 보안 취약점이 있는 패키지를 최신 버전으로 업그레이드해줘");

에이전트가 실행하는 내장 툴:
→ bash: 셸 명령 실행 (테스트, lint, 빌드 등)
→ text_editor: 파일 생성·수정·삭제
→ glob / grep: 파일 탐색 및 패턴 검색
→ task (서브에이전트 스폰): 병렬 작업 분기

---

실전 3 — 서브에이전트로 병렬 분석 에이전트 만들기

대규모 코드베이스 분석처럼 동시에 여러 작업을 해야 할 때 서브에이전트를 씁니다.

# Python — 병렬 코드리뷰 에이전트
import asyncio
import claude_agent_sdk as agent

REVIEW_PROMPT = """
당신은 코드 리뷰 오케스트레이터입니다.
아래 전략으로 병렬 서브에이전트를 활용하세요:

1. 보안 서브에이전트: 인증, SQL 인젝션, XSS 취약점 분석
2. 성능 서브에이전트: N+1 쿼리, 메모리 누수, 비효율 로직 탐색
3. 테스트 서브에이전트: 커버리지 측정 및 빠진 테스트케이스 도출

각 서브에이전트가 완료되면 결과를 통합해서 최종 리포트를 작성하세요.
"""

async def parallel_code_review(repo_path: str):
    print(f"[시작] {repo_path} 병렬 코드 리뷰")
    
    async for message in agent.query(
        prompt=f"저장소 {repo_path}를 보안·성능·테스트 관점에서 병렬로 분석해줘",
        options=agent.ClaudeOptions(
            model="claude-opus-4-7-20260416",
            system_prompt=REVIEW_PROMPT,
            max_turns=100,          # 서브에이전트 포함 총 턴 수
            max_subagents=5,        # 동시 실행 서브에이전트 한도
        )
    ):
        if message.type == "tool_use" and message.tool_name == "task":
            print(f"[서브에이전트 스폰] {message.input.get('description', '')}")
        elif message.type == "result":
            print("\n===== 최종 리뷰 결과 =====")
            print(message.result)

asyncio.run(parallel_code_review("./backend"))

 

서브에이전트 핵심 개념:
→ 오케스트레이터가 task 툴로 서브에이전트를 스폰
→ 각 서브에이전트는 독립된 컨텍스트 윈도우를 가짐
→ 서브에이전트끼리 컨텍스트 공유 없음 — 격리 보장
→ 완료 후 관련 결과만 오케스트레이터에게 반환
→ 대용량 파일 분석 시 메모리 효율 극대화

---

실전 4 — Managed Agents API로 클라우드 배포

로컬이 아닌 Anthropic 인프라에서 에이전트를 실행하고 싶다면 Managed Agents API를 씁니다. 샌드박스 환경, 세션 관리, 스트리밍을 Anthropic이 대신 처리합니다.

# Python — Managed Agents 퀵스타트
import anthropic

client = anthropic.Anthropic()

# 1. 에이전트 생성 (재사용 가능한 설정)
agent_config = client.managed_agents.agents.create(
    name="code-reviewer",
    model="claude-opus-4-7-20260416",
    system_prompt="당신은 시니어 개발자로서 코드 품질을 엄격하게 리뷰합니다.",
    tools=["bash", "text_editor"],
)
print(f"에이전트 ID: {agent_config.id}")

# 2. 환경 설정 (샌드박스 컨테이너 템플릿)
environment = client.managed_agents.environments.create(
    agent_id=agent_config.id,
    template="python-3.12",         # 사전 정의 컨테이너 템플릿
    packages=["pytest", "ruff"],    # 추가 패키지
)

# 3. 세션 시작 및 스트리밍
session = client.managed_agents.sessions.create(
    agent_id=agent_config.id,
    environment_id=environment.id,
)

with client.managed_agents.sessions.stream(
    session_id=session.id,
    prompt="이 저장소의 Python 파일을 ruff로 린트하고 문제를 자동 수정해줘",
) as stream:
    for event in stream:
        print(event)

Managed Agents vs 로컬 Agent SDK:
→ Managed: Anthropic이 샌드박스·세션·인프라 관리
→ 로컬: 내 서버에서 실행, 완전한 환경 제어 가능
→ Managed: managed-agents-2026-04-01 베타 헤더 필요
→ 로컬: API 키만 있으면 즉시 시작
→ 둘 다 같은 모델, 같은 툴셋 사용

---

마무리 / 결론

✅ 이럴 때 써라
→ 멀티스텝 코드 수정·리팩토링을 자동화하고 싶을 때
→ CI/CD 파이프라인에 자율 에이전트를 붙이고 싶을 때
→ 병렬 분석이 필요한 대용량 코드베이스 처리
→ 파일 시스템 접근 + 셸 실행이 모두 필요한 작업
→ Claude Code와 동일한 에이전트 파워를 API로 쓰고 싶을 때

❌ 이럴 때 쓰지 마라
→ 단순 단일 턴 Q&A — 일반 Messages API로 충분
→ OpenAI·Gemini 등 멀티 프로바이더 지원이 필요한 경우
→ 에이전트 내부 스텝을 완전히 제어해야 하는 경우 (Client SDK가 적합)
→ 프로덕션에서 과금 구조 예측이 중요한 경우 (턴 수 기반 과금 주의)
→ 보안 정책상 외부 LLM 실행이 금지된 환경