Agent SDK 빠른 시작(Quickstart)

Agent SDK 빠른 시작(Quickstart)

Agent SDK로 코드를 읽고 버그를 찾아 자동으로 고치는 AI 에이전트를 만들어 보는 가이드예요. 먼저 Agent SDK로 프로젝트를 구성하고, 버그가 있는 파일을 하나 만든 다음, 버그를 찾아 고치는 에이전트를 실행해요. 전제조건은 Node.js 18+ 또는 **Python 3.10+**와 Anthropic 계정이에요.

출처: 공식문서

본문

설정하기

1. 프로젝트 폴더 생성

mkdir my-agent
cd my-agent

자신의 프로젝트라면 어느 폴더에서든 SDK를 실행할 수 있고, 기본적으로 그 디렉터리와 하위 디렉터리의 파일에 접근할 수 있어요.

2. SDK 설치

  • TypeScript(새 프로젝트): 
    npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
    "type": "module"로 최상위 await를 쓰고, tsx가 TypeScript를 직접 실행해요.
  • Python(uv): 
    uv init
uv add claude-agent-sdk
  • Python(pip, macOS/Linux): 
    python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
  • Python(pip, Windows): 
    py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk
    PowerShell이 Activate.ps1을 막으면 Set-ExecutionPolicy -Scope Process RemoteSigned를 먼저 실행하세요.

TypeScript·Python SDK 둘 다 네이티브 Claude Code 바이너리를 번들하므로 대부분 별도 설치가 필요 없어요. 단 pip가 플랫폼 휠 대신 소스 배포판을 설치하는 경우(예: ARM64 Windows)나 npm 옵셔널 의존성을 건너뛰는 npm ci --omit=optional 같은 경우엔 바이너리가 없으니 Claude Code를 네이티브로 설치하세요.

3. API 키 설정

Claude Console에서 API 키를 받아 쉘 환경변수로 설정해요.

export ANTHROPIC_API_KEY=your-api-key

$env:ANTHROPIC_API_KEY = "your-api-key"

SDK는 에이전트를 실행하는 프로세스의 환경에서 키를 읽어요. .env 파일을 자동으로 로드하지 않으니, .env에 보관한다면 dotenv 패키지 등으로 직접 로드해야 해요.

SDK는 서드파티 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 Cloud's Agent Platform: CLAUDE_CODE_USE_VERTEX=1 + Google Cloud 자격 증명
  • Microsoft Foundry: CLAUDE_CODE_USE_FOUNDRY=1 + Azure 자격 증명

버그 있는 파일 만들기

my-agent 디렉터리에 utils.py를 만들고 다음 코드를 붙여 넣어요.

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

이 코드엔 버그가 둘 있어요. calculate_average([])는 0으로 나눠 크래시하고, get_user_name(None)은 TypeError로 크래시해요.

버그를 찾아 고치는 에이전트 만들기

Python이면 agent.py, TypeScript면 agent.ts를 만들어요(CommonJS 프로젝트면 agent.mts).

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


async def main():
    # Agentic loop: streams messages as Claude works
    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"],  # Auto-approve these tools
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

// Agentic loop: streams messages as Claude works
for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
    permissionMode: "acceptEdits" // Auto-approve file edits
  }
})) {
  // Print human-readable output
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) {
        console.log(block.text); // Claude's reasoning
      } else if ("name" in block) {
        console.log(`Tool: ${block.name}`); // Tool being called
      }
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`); // Final result
  }
}

코드는 세 부분으로 이뤄져요.

  1. query: 에이전트 루프를 만드는 주 진입점. async 이터레이터를 반환하므로 async for로 메시지를 스트리밍.
  2. prompt: Claude가 할 일. 작업에 따라 어떤 도구를 쓸지 Claude가 정해요.
  3. options: 에이전트 구성. allowedTools로 Read·Edit·Glob을 사전 승인하고 permissionMode: "acceptEdits"로 파일 변경을 자동 승인. systemPrompt, mcpServers 등 다른 옵션도 있어요.

async for 루프는 Claude가 생각하고, 도구를 호출하고, 결과를 보고, 다음을 결정하는 동안 계속 돌아요. 각 이터레이션에 메시지(추론·도구 호출·도구 결과·최종 결과)가 나오고, SDK가 오케스트레이션·도구 실행·컨텍스트 관리·재시도를 처리하니 우리는 스트림을 소비하기만 하면 돼요.

이 예시는 실시간 진행을 보여주는 스트리밍을 써요. 라이브 출력이 필요 없는 백그라운드 잡·CI에선 메시지를 한 번에 모을 수 있어요.

에이전트 실행

# TypeScript
npx tsx agent.ts
# Python (uv)
uv run agent.py
# Python (pip)
python agent.py

에이전트는 작업하며 추론과 호출 도구를 출력하고 Done: success로 끝나요. 실행 후 utils.py를 확인하면 빈 리스트와 null 사용자를 다루는 방어 코드가 들어 있어요. 에이전트가 utils.py를 Read하고, 크래시할 엣지 케이스를 분석하고, Edit로 오류 처리를 추가한 거예요. 이것이 Agent SDK의 핵심 차이예요 — Claude가 도구를 직접 실행하지, 우리가 구현하라고 요청하지 않아요.

Not logged in이나 Invalid API key 인증 오류가 나면 에이전트를 실행하는 쉘에 ANTHROPIC_API_KEY를 설정했는지 확인하세요.

다른 프롬프트 시도: "Add docstrings to all functions in utils.py", "Add type hints to all functions in utils.py", "Create a README.md documenting the functions in utils.py".

에이전트 커스터마이즈: 웹 검색을 추가하려면 allowedTools에 WebSearch를, 커스텀 시스템 프롬프트는 systemPrompt/system_prompt, 터미널 명령은 Bash 도구를 추가하면 돼요. Bash로 "Write unit tests for utils.py, run them, and fix any failures"를 시도해 보세요.

핵심 개념

도구가 에이전트가 할 수 있는 일을 정해요. Read·Glob·Grep은 읽기 전용 분석, Read·Edit·Glob은 코드 분석·수정, Read·Edit·Bash·Glob·Grep은 전체 자동화예요. 권한 모드가 인간의 감독 수준을 정하며, SDK는 활성 모드를 allow/deny 규칙과 함께 고정된 순서로 평가해요.

더 알아보기

  • Permissions: 에이전트 권한·승인 제어
  • Hooks: 도구 호출 전후 커스텀 코드
  • Sessions: 컨텍스트를 유지하는 다중 턴 에이전트
  • MCP servers: 데이터베이스·브라우저·API 연결
  • Hosting: Docker·클라우드·CI/CD 배포
  • Example agents: 이메일 어시스턴트·리서치 에이전트 등