5-step Flow

모든 tool-calling 시스템은 — provider 무관하게 — 같은 loop 야. Step 한 번 외워두면 이 quest 의 나머지는 그 위의 장식이야.

Tool 정의. 각 tool 은 name, 한 문장 description, 인자 JSON Schema.
Tool 리스트와 함께 모델 호출. 모델은 질문과 사용 가능한 액션 메뉴를 같이 봐.
모델이 결정. 텍스트로 답하거나 (tool 불필요), 또는 name 과 인자를 담은 구조화된 tool-call object 를 반환.
네 코드에서 tool 실행 (모델은 절대 직접 실행 안 함), 결과를 새 메시지로 대화에 넣음.
모델 다시 호출. 또 tool 부르거나, 같은 tool 다른 인자로 부르거나, 텍스트로 끝냄.

새로 짜는 사람은 5 단계에서 자주 미끄러져. Loop 는 모델이 '나 끝났어' 하고 stop reason 을 내놓을 때까지 계속 돌아 — Anthropic 은 보통 end_turn, OpenAI 는 stop, Gemini 는 STOP. 멈출 시점은 네가 정하는 게 아니야. Stop reason 을 읽고 거기에 반응하는 거지. '무조건 세 번 돌기' 나 '첫 tool call 하면 끝' 같은 걸 박아두면, 너무 일찍 끝나거나 영원히 멈추지 않는 agent 가 나와.

다른 함정은 대화를 어떻게 쌓느냐야. Tool 결과는 대화의 어엿한 메시지야 — 모델은 다음 turn 에 그걸 user 메시지와 똑같이 봐. Assistant 의 tool-call 메시지와 tool 결과를 둘 다 넣는 걸 까먹으면, 다음 호출 때 모델은 자기가 tool 을 불렀다는 사실조차 잊고 같은 tool 을 또 부르려 들어. 왕복 한 번을 제대로 닫는 게 그래서 중요해.

Code

정직한 agent loop, 10 줄·python

def agent(user_msg, tools, run_tool, max_turns=20):
    messages = [{"role": "user", "content": user_msg}]
    for _ in range(max_turns):
        resp = client.messages.create(model=MODEL, tools=tools, messages=messages, max_tokens=2048)
        messages.append({"role": "assistant", "content": resp.content})
        if resp.stop_reason == "end_turn":
            return resp
        results = []
        for block in resp.content:
            if block.type == "tool_use":
                results.append({"type": "tool_result", "tool_use_id": block.id,
                                "content": run_tool(block.name, block.input)})
        messages.append({"role": "user", "content": results})
    raise TimeoutError("Loop never finished — check tool descriptions or max_turns")

Code

External links

Exercise

Progress

댓글 0