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 을 읽고 반응하는 거지. '항상 3 번 loop' 나 '첫 tool call 후 stop' 같은 hard-coding 은 너무 일찍 끝나거나 영원히 hang 하는 agent 를 만들어.

다른 함정은 conversation 구성. Tool 결과는 대화의 first-class 메시지야 — 모델이 다음 turn 에 user message 와 같은 방식으로 봐. Assistant 의 tool-call 메시지와 tool 결과를 둘 다 추가하는 걸 까먹으면, 다음 호출 때 모델은 자기가 tool call 을 했다는 사실 자체를 잊고 같은 tool 을 또 부르려 들어. Round-trip 절제가 중요해.

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