프레임워크 없이 구현하는 Claude API 멀티 에이전트 루프

대부분의 Claude API 튜토리얼은 단일 도구 호출 (tool call)만을 보여줍니다. 대부분의 프레임워크는 당신이 읽을 수 없는 추상화 (abstractions) 뒤로 루프를 숨겨버립니다. 이 포스트는 루프를 직접적으로 보여줍니다 — "Claude가 도구를 요청함"과 "Claude가 완료함" 사이에서 실제로 어떤 일이 일어나는지를 말이죠.

평이한 영어로 설명하는 루프

Claude에게 도구 (tools)를 제공할 때, 단 한 번의 API 호출만으로는 항상 충분하지 않습니다. Claude가 도구를 호출할지 결정하면, 당신이 이를 실행하고, 그 결과를 다시 전송합니다. Claude는 또 다른 도구를 호출할 수도 있고, 혹은 답변을 할 수도 있습니다. 그 사이클이 바로 에이전트 루프 (agent loop)입니다.

user message
    ↓
Claude responds
...

구현 (The implementation)

전체 루프는 agent.py에 담겨 있으며, 약 80줄 정도입니다.

def run_agent(
    system: str,
    user_message: str,
...

이것이 핵심입니다. 파일의 나머지 부분은 _call_tool (당신의 Python 함수로 디스패치)과 _extract_text (응답에서 텍스트 블록을 추출)로 구성됩니다.

사용법

Anthropic의 스키마 (schema) 형식으로 도구를 정의하세요:

TOOLS = [
    {
        "name": "read_file",
...

핸들러 (handlers)를 일반적인 Python 함수로 정의하세요:

def read_file(path: str) -> dict:
    return {"content": Path(path).read_text()}

...

에이전트를 실행하세요:

result = run_agent(
    system="You are a helpful assistant.",
    user_message="What's in README.md?",
...

왜 프레임워크를 사용하지 않는가?

프레임워크가 틀린 것은 아닙니다. 하지만 프로덕션 (production) 환경에서 무언가 고장 날 때 — 그리고 반드시 고장 나게 되어 있습니다 — 당신은 정확히 어떤 메시지가 Claude로 전송되었고, 정확히 무엇이 돌아왔는지 알고 싶어 할 것입니다. 추상화는 그것을 더 어렵게 만듭니다.

이 구현은 읽히고, 수정되고, 소유하기 위해 만들어졌습니다. 루프가 눈에 보입니다. 당신은 로깅 (logging), 승인 게이트 (approval gates), 재시도 로직 (retry logic), 또는 조건부 실행 (conditional execution)을 필요한 정확한 위치에 추가할 수 있습니다.

작동하는 두 가지 예시

리포지토리 (repo)에는 다음이 포함되어 있습니다:

• example_research.py — search 및 read_page 도구를 가진 에이전트 (실제 구현으로 교체 가능)
• example_code.py — read_file, write_file, 및 list_files 도구를 가진 에이전트

두 방식 모두 실제 Claude API 호출을 통해 엔드 투 엔드 (end-to-end)로 실행됩니다.

설치 (Install)

pip install anthropic
export ANTHROPIC_API_KEY=sk-ant-...
python example_code.py

저장소: github.com/espanhol6/claude-multiagent-loop

이 패턴은 제가 Cluster OS Jarvis의 기반으로 사용한 방식입니다. Cluster OS Jarvis는 SSE 스트리밍 (SSE streaming), 최대 6회의 도구 호출 (tool-calling) 라운드, 그리고 크론 스케줄링 (cron-scheduled) 기반의 자율 에이전트를 지원하는 프로덕션급 멀티 에이전트 프레임워크 (multi-agent framework)입니다. 여기의 루프 (loop)는 이를 단순화한 독립형 버전입니다.

Claude를 사용하여 무언가를 구축하고 있으며, 추상화 (abstractions)를 추가하기 전에 내부적으로 어떤 일이 일어나는지 이해하고 싶다면 이것이 좋은 시작점이 될 것입니다.

_João Daniel Espanhol Miguel — AI 엔지니어, 리스본. 또한 ctranslate2 + WinRT에서의 조용한 네이티브 크래시 디버깅에 대해 작성했습니다.]