에이전트 루프의 작동 원리

​

루프 한눈에 보기

1. 프롬프트 수신. Claude가 프롬프트, 시스템 프롬프트, 도구 정의, 대화 기록과 함께 프롬프트를 받습니다. SDK는 세션 메타데이터를 포함하는 서브타입 "init"이 있는 SystemMessage를 생성합니다.
2. 평가 및 응답. Claude가 현재 상태를 평가하고 진행 방법을 결정합니다. 텍스트로 응답하거나, 하나 이상의 도구 호출을 요청하거나, 둘 다 할 수 있습니다. SDK는 텍스트와 도구 호출 요청을 포함하는 AssistantMessage를 생성합니다.
3. 도구 실행. SDK가 요청된 각 도구를 실행하고 결과를 수집합니다. 각 도구 결과 세트가 다음 결정을 위해 Claude에게 다시 피드백됩니다. hooks를 사용하여 도구 호출을 실행 전에 가로채고, 수정하거나, 차단할 수 있습니다.
4. 반복. 2단계와 3단계가 주기로 반복됩니다. 각 전체 주기는 한 턴입니다. Claude는 도구 호출이 없는 응답을 생성할 때까지 도구를 계속 호출하고 결과를 처리합니다.
5. 결과 반환. SDK는 텍스트 응답(도구 호출 없음)이 있는 최종 AssistantMessage를 생성한 후, 최종 텍스트, 토큰 사용량, 비용, 세션 ID가 있는 ResultMessage를 생성합니다.

​

턴과 메시지

1. 턴 1: Claude가 Bash를 호출하여 npm test를 실행합니다. SDK는 도구 호출이 있는 AssistantMessage를 생성하고, 명령을 실행한 후, 출력(3개 실패)이 있는 UserMessage를 생성합니다.
2. 턴 2: Claude가 auth.ts와 auth.test.ts에서 Read를 호출합니다. SDK가 파일 내용을 반환하고 AssistantMessage를 생성합니다.
3. 턴 3: Claude가 Edit를 호출하여 auth.ts를 수정한 후, Bash를 호출하여 npm test를 다시 실행합니다. 3개 테스트 모두 통과합니다. SDK는 AssistantMessage를 생성합니다.
4. 최종 턴: Claude가 도구 호출이 없는 텍스트 전용 응답을 생성합니다: “auth 버그를 수정했고, 3개 테스트 모두 통과합니다.” SDK는 이 텍스트가 있는 최종 AssistantMessage를 생성한 후, 비용 및 사용량이 있는 ResultMessage를 생성합니다.

​

메시지 타입

• SystemMessage: 세션 생명주기 이벤트. subtype 필드가 이를 구분합니다: "init"은 첫 번째 메시지(세션 메타데이터)이고, "compact_boundary"는 압축 후에 발생합니다. TypeScript에서 압축 경계는 SDKSystemMessage의 서브타입이 아니라 자체 SDKCompactBoundaryMessage 타입입니다.
• AssistantMessage: 최종 텍스트 전용 응답을 포함하여 각 Claude 응답 후에 생성됩니다. 해당 턴의 텍스트 콘텐츠 블록과 도구 호출 블록을 포함합니다.
• UserMessage: 각 도구 실행 후 Claude에게 다시 전송되는 도구 결과 콘텐츠와 함께 생성됩니다. 루프 중간에 스트리밍하는 모든 사용자 입력에 대해서도 생성됩니다.
• StreamEvent: 부분 메시지가 활성화된 경우에만 생성됩니다. 원본 API 스트리밍 이벤트(텍스트 델타, 도구 입력 청크)를 포함합니다. 스트림 응답을 참조하세요.
• ResultMessage: 에이전트 루프의 끝을 표시합니다. 최종 텍스트 결과, 토큰 사용량, 비용, 세션 ID를 포함합니다. subtype 필드를 확인하여 작업이 성공했는지 또는 제한에 도달했는지 확인합니다. prompt_suggestion과 같은 소수의 후행 시스템 이벤트가 이후에 도착할 수 있으므로 결과에서 중단하지 말고 스트림을 완료까지 반복합니다. 결과 처리를 참조하세요.

​

메시지 처리

• 최종 결과만: ResultMessage를 처리하여 출력, 비용, 작업이 성공했는지 또는 제한에 도달했는지 확인합니다.
• 진행 상황 업데이트: AssistantMessage를 처리하여 Claude가 각 턴에서 무엇을 하고 있는지, 어떤 도구를 호출했는지 확인합니다.
• 라이브 스트리밍: 부분 메시지를 활성화하여(include_partial_messages Python, includePartialMessages TypeScript) 실시간으로 StreamEvent 메시지를 받습니다. 실시간 스트림 응답을 참조하세요.

• Python: claude_agent_sdk에서 가져온 클래스에 대해 isinstance()로 메시지 타입을 확인합니다(예: isinstance(message, ResultMessage)).
• TypeScript: type 문자열 필드를 확인합니다(예: message.type === "result"). AssistantMessage와 UserMessage는 원본 API 메시지를 .message 필드에 래핑하므로 콘텐츠 블록은 message.content가 아니라 message.message.content에 있습니다.

from claude_agent_sdk import query, AssistantMessage, ResultMessage

async for message in query(prompt="Summarize this project"):
    if isinstance(message, AssistantMessage):
        print(f"Turn completed: {len(message.content)} content blocks")
    if isinstance(message, ResultMessage):
        if message.subtype == "success":
            print(message.result)
        else:
            print(f"Stopped: {message.subtype}")

​

도구 실행

​

내장 도구

• MCP 서버로 외부 서비스 연결(데이터베이스, 브라우저, API)
• 사용자 정의 도구 핸들러로 사용자 정의 도구 정의
• 설정 소스를 통해 프로젝트 스킬 로드 재사용 가능한 워크플로우

​

도구 권한

• allowed_tools / allowedTools 나열된 도구를 자동 승인합니다. ["Read", "Glob", "Grep"]이 허용된 도구 목록에 있는 읽기 전용 에이전트는 프롬프트 없이 해당 도구를 실행합니다. 나열되지 않은 도구는 여전히 사용 가능하지만 권한이 필요합니다.
• disallowed_tools / disallowedTools 다른 설정에 관계없이 나열된 도구를 차단합니다. 도구가 실행되기 전에 규칙이 확인되는 순서는 권한을 참조하세요.
• permission_mode / permissionMode 허용 또는 거부 규칙으로 다루지 않는 도구에 어떤 일이 발생하는지 제어합니다. 사용 가능한 모드는 권한 모드를 참조하세요.

​

병렬 도구 실행

​

루프 실행 방식 제어

​

턴과 예산

​

노력 수준

​

권한 모드

​

모델

​

컨텍스트 윈도우

​

컨텍스트를 소비하는 것

​

자동 압축

• CLAUDE.md의 요약 지침: 압축기는 다른 컨텍스트처럼 CLAUDE.md를 읽으므로 요약할 때 보존할 내용을 알려주는 섹션을 포함할 수 있습니다. 섹션 헤더는 자유 형식입니다(매직 문자열이 아님); 압축기는 의도와 일치합니다.
• PreCompact hook: 압축 전에 사용자 정의 로직을 실행합니다(예: 전체 기록을 보관). hook은 trigger 필드(manual 또는 auto)를 받습니다. hooks를 참조하세요.
• 수동 압축: /compact를 프롬프트 문자열로 보내 필요에 따라 압축을 트리거합니다. 이 방식으로 전송된 명령은 SDK 입력이며, CLI 전용 바로 가기가 아닙니다. SDK의 슬래시 명령을 참조하세요.

# 요약 지침

이 대화를 요약할 때 항상 보존합니다:
- 현재 작업 목표 및 수용 기준
- 읽거나 수정한 파일 경로
- 테스트 결과 및 오류 메시지
- 결정 및 그 뒤의 추론

​

컨텍스트 효율성 유지

• 서브작업에 서브에이전트 사용. 각 서브에이전트는 새로운 대화로 시작합니다(이전 메시지 기록 없음, 자신의 시스템 프롬프트 및 CLAUDE.md 같은 프로젝트 수준 컨텍스트는 로드함). 부모의 턴을 보지 않으며, 최종 응답만 도구 결과로 부모에게 반환됩니다. 주 에이전트의 컨텍스트는 전체 서브작업 기록이 아니라 해당 요약으로 증가합니다. 서브에이전트가 상속하는 것을 참조하세요.
• 도구를 선택적으로 사용합니다. 모든 도구 정의는 컨텍스트 공간을 차지합니다. AgentDefinition의 tools 필드를 사용하여 서브에이전트를 필요한 최소 세트로 범위를 지정합니다.
• MCP 서버 비용을 주시합니다. MCP 도구 검색은 기본적으로 MCP 도구 스키마를 지연시키고 필요에 따라 로드합니다. 도구 검색이 꺼져 있거나, Vertex AI에 있거나, 비자사 ANTHROPIC_BASE_URL 뒤에 있으면 각 MCP 서버는 모든 도구 스키마를 모든 요청에 추가하므로 많은 도구가 있는 몇 개의 서버는 에이전트가 작업을 수행하기 전에 상당한 컨텍스트를 소비할 수 있습니다.
• 일상적인 작업에 낮은 노력을 사용합니다. 파일을 읽거나 디렉토리를 나열하기만 하면 되는 에이전트의 경우 노력을 "low"로 설정합니다. 이는 토큰 사용량과 비용을 줄입니다.

​

세션 및 연속성

​

결과 처리

​

Hooks

​

모두 함께 사용

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    async for message in query(
        prompt="Find and fix the bug causing test failures in the auth module",
        options=ClaudeAgentOptions(
            allowed_tools=[
                "Read",
                "Edit",
                "Bash",
                "Glob",
                "Grep",
            ],  # Listing tools here auto-approves them (no prompting)
            setting_sources=[
                "project"
            ],  # Load CLAUDE.md, skills, hooks from current directory
            max_turns=30,  # Prevent runaway sessions
            effort="high",  # Thorough reasoning for complex debugging
        ),
    ):
        # Handle the final result
        if isinstance(message, ResultMessage):
            session_id = message.session_id  # Save for potential resumption

            if message.subtype == "success":
                print(f"Done: {message.result}")
            elif message.subtype == "error_max_turns":
                # Agent ran out of turns. Resume with a higher limit.
                print(f"Hit turn limit. Resume session {session_id} to continue.")
            elif message.subtype == "error_max_budget_usd":
                print("Hit budget limit.")
            else:
                print(f"Stopped: {message.subtype}")
            if message.total_cost_usd is not None:
                print(f"Cost: ${message.total_cost_usd:.4f}")


asyncio.run(run_agent())

​

다음 단계

• 아직 에이전트를 실행하지 않았나요? 빠른 시작으로 시작하여 SDK를 설치하고 끝에서 끝까지 실행되는 전체 예제를 확인합니다.
• 프로젝트에 연결할 준비가 되었나요? CLAUDE.md, 스킬, 파일시스템 hooks 로드하여 에이전트가 프로젝트 규칙을 자동으로 따르도록 합니다.
• 대화형 UI를 구축하고 있나요? 스트리밍을 활성화하여 루프가 실행되면서 라이브 텍스트 및 도구 호출을 표시합니다.
• 에이전트가 할 수 있는 것에 대해 더 엄격한 제어가 필요하신가요? 권한으로 도구 접근을 잠그고, hooks를 사용하여 실행 전에 도구 호출을 감사, 차단 또는 변환합니다.
• 장기 또는 비용이 많이 드는 작업을 실행하고 있나요? 격리된 작업을 서브에이전트로 오프로드하여 주 컨텍스트를 깔끔하게 유지합니다.