왜 지금 AI 에이전트인가?

2026년 3월 현재, AI 개발의 패러다임이 완전히 바뀌었습니다. 단순히 프롬프트를 보내고 응답을 받는 시대는 지났습니다. 이제는 AI 에이전트가 파일을 읽고, 코드를 분석하고, 버그를 수정하고, 웹을 검색하는 것까지 자율적으로 수행합니다. 그리고 이 모든 것을 가능하게 하는 도구가 바로 Claude Agent SDK입니다.

Anthropic이 출시한 Claude Agent SDK는 Claude Code를 구동하는 것과 동일한 에이전트 루프, 도구 생태계, 컨텍스트 관리를 Python과 TypeScript로 프로그래밍할 수 있게 해줍니다. 기존의 Client SDK와 달리, 도구 실행 루프를 직접 구현할 필요 없이 Claude가 자율적으로 도구를 선택하고 실행합니다. 이 가이드에서는 설치부터 프로덕션 배포까지, AI 에이전트 구축의 전 과정을 단계별로 안내하겠습니다.

Claude Agent SDK란 무엇인가?

Claude Agent SDK는 원래 "Claude Code SDK"라는 이름으로 출시되었다가, 에이전트 기능이 대폭 확장되면서 현재의 이름으로 변경되었습니다. 핵심 개념은 간단합니다. 컨텍스트 수집 → 행동 수행 → 결과 확인 → 반복이라는 구조화된 루프를 통해 AI가 자율적으로 작업을 완수합니다.

기존의 Anthropic Client SDK에서는 개발자가 직접 도구 실행 루프를 구현해야 했습니다. 응답에서 tool_use를 감지하고, 해당 도구를 실행하고, 결과를 다시 API에 전달하는 과정을 모두 직접 코딩해야 했습니다. Agent SDK는 이 모든 오케스트레이션을 자동으로 처리합니다.

내장 도구도 풍부합니다. 파일 읽기/쓰기(Read, Write, Edit), 터미널 명령 실행(Bash), 파일 검색(Glob, Grep), 웹 검색 및 페이지 분석(WebSearch, WebFetch), 그리고 사용자 질문(AskUserQuestion)까지 즉시 사용할 수 있습니다.

환경 설정: 5분 안에 시작하기

사전 요구사항

Python을 사용한다면 Python 3.10 이상, TypeScript라면 Node.js 18 이상이 필요합니다. 또한 Claude Console에서 API 키를 발급받아야 합니다.

Python 설치

mkdir my-agent && cd my-agent
python3 -m venv .venv && source .venv/bin/activate
pip3 install claude-agent-sdk

uv 패키지 매니저를 사용하면 더 빠릅니다:

uv init && uv add claude-agent-sdk

TypeScript 설치

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-agent-sdk
npm install -D typescript @types/node tsx

API 키 설정

export ANTHROPIC_API_KEY=your-api-key

Amazon Bedrock, Google Vertex AI, Microsoft Azure를 통한 인증도 지원됩니다. Bedrock의 경우 CLAUDE_CODE_USE_BEDROCK=1, Vertex AI는 CLAUDE_CODE_USE_VERTEX=1, Azure는 CLAUDE_CODE_USE_FOUNDRY=1 환경 변수를 설정하면 됩니다.

첫 번째 에이전트 만들기: 버그 자동 수정기

실제로 동작하는 에이전트를 만들어 보겠습니다. 먼저 의도적으로 버그가 있는 utils.py 파일을 만듭니다:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)  # 빈 리스트일 때 ZeroDivisionError

def get_user_name(user):
    return user["name"].upper()  # user가 None일 때 TypeError

이제 이 버그를 자동으로 찾아 수정하는 에이전트를 작성합니다:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

python3 agent.py를 실행하면, Claude는 자율적으로 파일을 읽고, 버그를 분석하고, 적절한 에러 핸들링 코드를 추가합니다. 개발자가 도구 실행 로직을 직접 구현할 필요가 전혀 없습니다.

핵심 구성 요소를 살펴보면: query는 에이전틱 루프를 생성하는 메인 진입점이고, allowed_tools는 에이전트가 사용할 수 있는 도구를 지정하며, permission_mode="acceptEdits"는 파일 수정을 자동 승인합니다.

커스텀 도구와 시스템 프롬프트 활용

기본 도구만으로도 많은 것을 할 수 있지만, 시스템 프롬프트를 통해 에이전트의 행동을 정밀하게 제어할 수 있습니다:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits",
    system_prompt="당신은 시니어 Python 개발자입니다. 항상 PEP 8 스타일 가이드를 따르세요.",
)

Bash 도구를 추가하면 에이전트가 테스트를 실행하고 결과를 확인할 수도 있습니다. "utils.py에 대한 단위 테스트를 작성하고, 실행한 뒤, 실패하는 테스트를 수정해주세요" 같은 프롬프트가 가능해집니다.

MCP(Model Context Protocol) 서버를 연결하면 데이터베이스, 브라우저, 외부 API 등과도 통합할 수 있습니다:

options = ClaudeAgentOptions(
    mcp_servers={
        "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
    }
)

이 설정만으로 에이전트가 웹 브라우저를 자동으로 조작할 수 있게 됩니다.

서브에이전트와 멀티에이전트 시스템

복잡한 작업에서는 하나의 에이전트로는 부족할 수 있습니다. Claude Agent SDK는 서브에이전트(Subagent) 패턴을 지원하여, 메인 에이전트가 전문화된 하위 에이전트에게 작업을 위임할 수 있습니다.

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep", "Agent"],
    agents={
        "code-reviewer": AgentDefinition(
            description="코드 품질과 보안 리뷰 전문가",
            prompt="코드 품질을 분석하고 개선점을 제안하세요.",
            tools=["Read", "Glob", "Grep"],
        )
    },
)

allowed_tools에 "Agent"를 포함시키면 메인 에이전트가 서브에이전트를 호출할 수 있습니다. 각 서브에이전트는 독립된 컨텍스트 윈도우에서 실행되므로, 컨텍스트 오염(context pollution) 문제를 방지할 수 있습니다.

Anthropic이 최근 공개한 Agent Teams 기능은 이를 한 단계 더 발전시켰습니다. 각 팀원 에이전트가 역할별 지시사항을 받고, 서로 메시지를 주고받으며, 리드 에이전트가 결과를 종합합니다. 멀티에이전트 시스템이 특히 효과적인 경우는 세 가지입니다: 컨텍스트 오염이 성능을 저하시킬 때, 작업을 병렬로 실행할 수 있을 때, 그리고 전문화가 도구 선택이나 작업 집중도를 높일 때입니다.

세션 관리와 컨텍스트 유지

실무에서는 여러 번의 대화를 거쳐 작업이 진행되는 경우가 많습니다. Claude Agent SDK의 세션 기능을 사용하면 이전 대화의 컨텍스트를 유지한 채 작업을 이어갈 수 있습니다:

# 첫 번째 쿼리: 세션 ID 캡처
session_id = None
async for message in query(
    prompt="인증 모듈을 분석해주세요",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if hasattr(message, "subtype") and message.subtype == "init":
        session_id = message.session_id

# 두 번째 쿼리: 이전 컨텍스트를 유지한 채 계속
async for message in query(
    prompt="이 모듈을 호출하는 곳을 모두 찾아주세요",
    options=ClaudeAgentOptions(resume=session_id),
):
    if hasattr(message, "result"):
        print(message.result)

"이 모듈"이라는 표현이 이전 대화의 인증 모듈을 정확히 참조합니다. 세션을 포크(fork)하면 같은 컨텍스트에서 다른 접근 방식을 탐색할 수도 있습니다.

Hooks: 에이전트 행동 커스터마이징

Hooks는 에이전트 생명주기의 주요 시점에 커스텀 코드를 실행할 수 있는 강력한 기능입니다. PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd 등의 이벤트에 콜백을 등록할 수 있습니다.

예를 들어, 모든 파일 변경사항을 감사 로그에 기록하는 후크를 설정할 수 있습니다:

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}

options = ClaudeAgentOptions(
    permission_mode="acceptEdits",
    hooks={
        "PostToolUse": [
            HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
        ]
    },
)

프로덕션 환경에서는 이러한 후크를 활용하여 보안 감사, 비용 모니터링, 자동 롤백 등의 기능을 구현할 수 있습니다.

프로덕션 배포 가이드

개발 환경에서 잘 동작하는 에이전트를 프로덕션에 배포할 때는 몇 가지 중요한 원칙이 있습니다.

컨테이너화는 필수입니다. Docker, gVisor, Firecracker 등의 샌드박스 환경에서 에이전트를 실행해야 합니다. 멀티 테넌트 애플리케이션에서는 각 사용자 작업마다 새로운 에피메럴(ephemeral) 컨테이너를 생성하고, 완료 후 삭제하는 것이 권장됩니다.

API 자격 증명은 에이전트 외부에서 관리해야 합니다. ANTHROPIC_BASE_URL 변수를 통해 모든 API 트래픽을 신뢰할 수 있는 프록시로 라우팅하면, 인증 정보 주입, 요청 로깅, 조직 정책 적용을 중앙에서 관리할 수 있습니다.

관측 가능성(Observability)도 핵심입니다. OpenTelemetry 트레이스로 프롬프트, 도구 호출, 토큰 사용량, 오케스트레이션 단계를 추적하고, 서브에이전트 간 상관 ID를 설정하세요. 기능 플래그 뒤에서 단계적으로 롤아웃하고, 이상 감지 시 자동 롤백 트리거를 설정하는 것이 좋습니다.

비용과 가격 정책

Claude Agent SDK 자체는 무료이며, 비용은 API 토큰 사용량에 따라 발생합니다. 2026년 3월 기준 주요 모델의 가격은 다음과 같습니다:

• Claude Opus 4.6: 입력 $5 / 출력 $25 (백만 토큰당)
• Claude Sonnet 4.6: 입력 $3 / 출력 $15 (백만 토큰당)
• Claude Haiku 4.5: 입력 $1 / 출력 $5 (백만 토큰당)

배치 처리를 사용하면 토큰 가격의 50% 할인을 받을 수 있습니다. 에이전트는 여러 번의 도구 호출을 거치면서 상당한 토큰을 소비할 수 있으므로, 서브에이전트 분리를 통한 컨텍스트 최적화와 적절한 모델 선택이 비용 관리의 핵심입니다.

Claude vs OpenAI: 에이전트 프레임워크 비교

2026년 기준으로 Claude와 OpenAI의 플래그십 모델은 전반적인 성능에서 거의 대등한 수준에 도달했습니다. 하지만 에이전트 개발 접근 방식에서는 뚜렷한 차이가 있습니다.

Claude Agent SDK는 개발자 중심의 로컬 워크플로우를 강조합니다. 확장된 컨텍스트 윈도우, 지속적 추론 능력, 그리고 코드베이스 전체를 이해하는 능력이 강점입니다. 터미널 기반으로 작동하며, 개발자가 루프 안에 있는(developer-in-the-loop) 방식을 선호합니다.

OpenAI의 에이전트 스택은 자율적이고 클라우드 기반의 작업 위임을 지향합니다. GPT-5.4의 네이티브 컴퓨터 사용(computer use) 기능과 빠른 반복 속도가 차별점입니다.

실질적으로 선택 기준은 워크플로우에 달려있습니다. 코딩과 로컬 개발 자동화에는 Claude가, 클라우드 기반 자율 실행에는 OpenAI가 각각 강점을 보입니다.

실전 팁과 권장 사항

처음 시작할 때: 내장 도구부터 시작하세요. Read, Edit, Glob만으로도 코드 분석과 수정 에이전트를 만들 수 있습니다. 커스텀 도구는 내장 도구로 해결되지 않는 특정 요구사항이 있을 때만 추가하는 것이 좋습니다.

프롬프트 설계: 에이전트에게 무엇을 하라고만 말하세요. "어떤 도구를 사용하라"고 지시할 필요 없이, Claude가 작업에 맞는 도구를 스스로 선택합니다.

서브에이전트 활용: 프로덕션에서 가장 안정적인 에이전트는 "각 서브에이전트에 하나의 업무, 오케스트레이터가 조율"이라는 간단한 규칙을 따릅니다.

권한 모드 선택: 개발 중에는 acceptEdits, CI/CD 파이프라인에서는 bypassPermissions(샌드박스 환경), 사용자 대면 애플리케이션에서는 default 모드와 canUseTool 콜백 조합을 사용하세요.

앞으로의 전망

AI 에이전트 개발은 2026년 가장 빠르게 성장하는 소프트웨어 개발 분야 중 하나입니다. Claude Agent SDK는 프로덕션 수준의 에이전트를 구축하기 위한 가장 성숙한 프레임워크 중 하나로 자리잡았으며, 서브에이전트, Agent Teams, MCP 통합 등의 기능을 통해 점점 더 복잡한 자동화 시나리오를 지원하고 있습니다. 중요한 것은 지금 당장 시작하는 것입니다. 간단한 파일 분석 에이전트부터 만들어보고, 점진적으로 도구와 서브에이전트를 추가해 나가면서 여러분만의 AI 자동화 파이프라인을 구축해 보시기 바랍니다.