빠른 시작

Agent SDK를 사용하여 코드를 읽고, 버그를 찾고, 수동 개입 없이 자동으로 수정하는 AI 에이전트를 구축하세요.

수행할 작업:

1. Agent SDK로 프로젝트 설정
2. 버그가 있는 코드 파일 생성
3. 자동으로 버그를 찾아 수정하는 에이전트 실행

사전 요구 사항

• Node.js 18+ 또는 Python 3.10+
• Anthropic 계정 (여기에서 가입)

설정

버그가 있는 파일 생성

이 빠른 시작에서는 코드의 버그를 찾아 수정할 수 있는 에이전트를 구축하는 과정을 안내합니다. 먼저, 에이전트가 수정할 의도적인 버그가 포함된 파일이 필요합니다. 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()

이 코드에는 두 가지 버그가 있습니다:

1. calculate_average([])는 0으로 나누기 오류로 충돌합니다
2. get_user_name(None)은 TypeError로 충돌합니다

버그를 찾아 수정하는 에이전트 구축

Python SDK를 사용하는 경우 agent.py를, TypeScript의 경우 agent.ts를 생성합니다:

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

async def main():
    # 에이전트 루프: Claude가 작업하는 동안 메시지를 스트리밍합니다
    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"],  # Claude가 사용할 수 있는 도구
            permission_mode="acceptEdits"            # 파일 편집 자동 승인
        )
    ):
        # 사람이 읽을 수 있는 출력 인쇄
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)              # Claude의 추론
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")   # 호출되는 도구
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # 최종 결과

asyncio.run(main())

이 코드는 세 가지 주요 부분으로 구성됩니다:

1. query: 에이전트 루프를 생성하는 메인 진입점입니다. 비동기 이터레이터를 반환하므로 async for를 사용하여 Claude가 작업하는 동안 메시지를 스트리밍합니다. 전체 API는 Python 또는 TypeScript SDK 레퍼런스를 참조하세요.

2. prompt: Claude에게 수행할 작업을 지시합니다. Claude는 작업에 따라 어떤 도구를 사용할지 스스로 판단합니다.

3. options: 에이전트의 구성입니다. 이 예제에서는 allowedTools를 사용하여 Claude를 Read, Edit, Glob으로 제한하고, permissionMode: "acceptEdits"로 파일 변경을 자동 승인합니다. 다른 옵션으로는 systemPrompt, mcpServers 등이 있습니다. 모든 옵션은 Python 또는 TypeScript를 참조하세요.

async for 루프는 Claude가 생각하고, 도구를 호출하고, 결과를 관찰하고, 다음에 할 일을 결정하는 동안 계속 실행됩니다. 각 반복은 메시지를 생성합니다: Claude의 추론, 도구 호출, 도구 결과 또는 최종 결과. SDK가 오케스트레이션(도구 실행, 컨텍스트 관리, 재시도)을 처리하므로 스트림만 소비하면 됩니다. 루프는 Claude가 작업을 완료하거나 오류가 발생하면 종료됩니다.

루프 내부의 메시지 처리는 사람이 읽을 수 있는 출력을 필터링합니다. 필터링 없이는 시스템 초기화 및 내부 상태를 포함한 원시 메시지 객체가 표시되는데, 이는 디버깅에는 유용하지만 그 외에는 노이즈가 됩니다.

에이전트 실행

에이전트가 준비되었습니다. 다음 명령으로 실행하세요:

실행 후 utils.py를 확인하세요. 빈 리스트와 null 사용자를 처리하는 방어적 코드가 추가된 것을 볼 수 있습니다. 에이전트가 자율적으로:

1. utils.py를 읽어 코드를 이해했습니다
2. 로직을 분석하고 충돌을 일으킬 수 있는 엣지 케이스를 식별했습니다
3. 적절한 오류 처리를 추가하도록 파일을 편집했습니다

이것이 Agent SDK를 차별화하는 점입니다: Claude가 도구를 직접 실행하며, 사용자에게 구현을 요청하지 않습니다.

다른 프롬프트 시도

에이전트가 설정되었으니, 다양한 프롬프트를 시도해 보세요:

• "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"

에이전트 커스터마이즈

옵션을 변경하여 에이전트의 동작을 수정할 수 있습니다. 다음은 몇 가지 예시입니다:

웹 검색 기능 추가:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Claude에 커스텀 시스템 프롬프트 제공:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines."
)

터미널에서 명령 실행:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)

Bash가 활성화된 상태에서 다음을 시도해 보세요: "Write unit tests for utils.py, run them, and fix any failures"

핵심 개념

도구는 에이전트가 할 수 있는 작업을 제어합니다:

권한 모드는 원하는 사람의 감독 수준을 제어합니다:

위의 예제는 acceptEdits 모드를 사용하여 파일 작업을 자동 승인하므로 에이전트가 대화형 프롬프트 없이 실행될 수 있습니다. 사용자에게 승인을 요청하려면 default 모드를 사용하고 사용자 입력을 수집하는 canUseTool 콜백을 제공하세요. 더 세밀한 제어는 권한을 참조하세요.

다음 단계

첫 번째 에이전트를 만들었으니, 기능을 확장하고 사용 사례에 맞게 조정하는 방법을 알아보세요:

• 권한: 에이전트가 할 수 있는 작업과 승인이 필요한 시점을 제어합니다
• 훅: 도구 호출 전후에 커스텀 코드를 실행합니다
• 세션: 컨텍스트를 유지하는 멀티턴 에이전트를 구축합니다
• MCP 서버: 데이터베이스, 브라우저, API 및 기타 외부 시스템에 연결합니다
• 호스팅: Docker, 클라우드 및 CI/CD에 에이전트를 배포합니다
• 예제 에이전트: 이메일 어시스턴트, 리서치 에이전트 등 완전한 예제를 확인하세요