루프가 없으면 에이전트도 없습니다

상담원은 정확히 어떤 일을 하나요?

터미널에서 Claude Code를 실행하고 "모든 TODO 주석을 목록으로 구성"하면 표시되는 내용은 자체적으로 grep을 결정한 다음 cat 몇 개의 파일을 결정하고 마크다운을 출력하는 것입니다. 모델은 코드 자체를 실행하지 않습니다. 실행을 요청하기만 합니다. 실제로 "손과 발이 있는" 것처럼 보이게 만드는 것은 주위에 있는 30줄 정도의 접착제 코드입니다.

본 레슨은 풀의 원을 분리하여 명확하게 보는 것입니다. 이를 에이전트 루프(에이전트 루프)라고 하며 구조는 다음과 같습니다.

while response.stop_reason == "tool_use":
    response = LLM(messages, tools)      # 1. ask the model
    execute_tools(response.tool_calls)   # 2. run what it asked for
    messages.append(tool_results)        # 3. feed results back

그렇습니다. 더 이상은 없습니다. 프로덕션의 Claude 코드에는 권한, 후크, 하위 에이전트, 작업 트리 격리 및 메모리 압축이 이 위에 쌓여 있지만 핵심은 여전히 ​​이 네 줄입니다.

주요 직관: 모델이 응답할 때마다 "도구를 조정하고 싶습니다" 또는 "완료되었습니다"입니다. 루프는 이전 상태에 있는 한 계속됩니다. 후자의 상태가 되면 루프가 종료됩니다. 기준은 응답의 stop_reason 필드입니다.

메시지 보기[] 단계별 성장

다음 루프 시뮬레이션의 작업은 "현재 디렉터리에 어떤 파일이 있습니까? 그런 다음 package.json을 읽으십시오"입니다. 단계를 클릭합니다. 이 버튼을 누를 때마다 주기에서 한 가지 작업이 진행됩니다. 왼쪽에는 사람이 보는 말풍선이 있고, 오른쪽에는 모델에 채워진 실제 messages[] 배열이 있습니다. 배열이 어떻게 커지는지 확인하세요.

도구 결과를 메시지 기록에 다시 입력해야 합니다.

초보자에게 가장 쉬운 함정은 "실행 도구"를 부작용으로 간주하는 것입니다. 일단 실행되면 완료됩니다. 하지만 모델은 다음 추론 단계에서 messages[]만 볼 수 있으며 그 안에 없는 일이 발생했는지는 알 수 없습니다. 추가 단계가 없으면 전체 루프가 잘못됩니다.

모든 실수가 동일한 것은 아닙니다. 두 가지 일반적인 유형:

• 추가는 잊어버리세요: 모델은 다음에 결과를 볼 수 없으며 동일한 도구를 다시 요청하며 무한 루프가 발생합니다.
• 추가하지만 tool_use_id 손실: Anthropic API는 tool_result must have tool_use_id 오류를 직접 보고하고 루프는 API 호출 단계에서 축소됩니다.

동일한 작업: "프로젝트에 있는 Python 파일 수 계산". 두 버전을 나란히 실행하여 엔딩의 차이를 확인하세요.

stop_reason 이해

모델은 반환될 때마다 stop_reason을 가져옵니다. 루프를 계속할지 결정하려면 다음 필드를 살펴보세요.

• tool_use — 모델이 도구를 조정하려고 하며 주기를 계속합니다.
• end_turn — 모델은 완료되었다고 느끼고 루프를 종료합니다.
• max_tokens — 토큰의 상한이 생성되면 잘리고 루프를 종료합니다(일반적으로 사용자에게 출력이 불완전하다는 메시지를 표시하는 예외로 처리됨).
• stop_sequence — 사용자 정의 중지 문자열이 발견되면 루프를 종료합니다.

"tool_use이 없는 한 계속한다"라고 잘못 적거나, max_tokens을 무시하고 바로 정상 종료로 처리하는 것은 일반적인 버그입니다.

행동하고 실행하라

로컬 클론 shareAI-lab/learn-claude-code:

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env  # fill in ANTHROPIC_API_KEY
python agents/s01_agent_loop.py

그런 다음 실제 작업을 수행해 보세요. 帮我数一下这个仓库里有多少 .py 文件. ls -R을 보내는 것을 볼 수 있고, 출력을 보고, 또 다른 find . -name "*.py" | wc -l을 보낸 다음 답을 알려줄 것입니다. 전체 프로세스는 이 루프입니다.

[]

while True:
    resp = LLM(msgs, tools)
    msgs.append({"role":"assistant",
                 "content": resp.content})
    if resp.stop_reason != "tool_use":
        return
    results = execute(resp.tool_uses)
    msgs.append({"role":"user",
                 "content": results})

while True:
    resp = LLM(msgs, tools)
    msgs.append({"role":"assistant",
                 "content": resp.content})
    if resp.stop_reason != "tool_use":
        return
    results = execute(resp.tool_uses)
    # BUG: forgot to append results
    # msgs.append(...)