The Basic Agent Loop

Implement the core agent loop — the control flow that turns a language model into an agent. The model call is a stub you are given; the exercise is the loop that drives it. This is the first thing interviewers ask you to build in an agent-coding round.

How the loop works

You keep a running list of messages. Each turn you call model(messages) and it returns one of two things:

• a final answer — {"role": "assistant", "type": "final", "content": "..."} — stop and return the content.
• a tool call — {"role": "assistant", "type": "tool", "name": "search", "args": {"q": "..."}} — look up the tool by name in tools, call it with args, append the assistant’s tool call and the tool’s result to messages, and loop again.

You must cap the loop at max_steps so a model that never finishes cannot run forever.

Task

Complete run_agent(model, tools, user_msg, max_steps=10):

1. Start messages with the user message: {"role": "user", "content": user_msg}.
2. Loop up to max_steps times: call the model, and either return the final content or execute the named tool and append both the assistant message and a tool-result message {"role": "tool", "name": ..., "content": <tool output>}.
3. If the loop runs out of steps, return a clear message like "Stopped: reached max steps.".

Example

def model(messages):
    # (mock) first turn asks for a tool, second turn answers
    if not any(m["role"] == "tool" for m in messages):
        return {"role": "assistant", "type": "tool", "name": "add", "args": {"a": 2, "b": 3}}
    return {"role": "assistant", "type": "final", "content": "The answer is 5."}

tools = {"add": lambda args: str(args["a"] + args["b"])}

run_agent(model, tools, "what is 2 + 3?")   # -> "The answer is 5."

Constraints

• Handle an unknown tool name gracefully (append an error result rather than crashing).
• Do not call any real LLM or network — model and the tools are provided.

Approach

The agent is a bounded while loop over a growing message list. Each turn the model either finishes (return) or requests a tool (dispatch, append the result, continue). A step counter guarantees termination.

Solution

def run_agent(model, tools, user_msg, max_steps=10):
    messages = [{"role": "user", "content": user_msg}]

    for _ in range(max_steps):
        action = model(messages)

        if action["type"] == "final":
            return action["content"]

        # otherwise it's a tool call
        name, args = action["name"], action.get("args", {})
        messages.append(action)                      # record what the model asked for

        tool = tools.get(name)
        if tool is None:
            result = f"error: unknown tool '{name}'"
        else:
            try:
                result = tool(args)
            except Exception as e:                   # a broken tool shouldn't crash the agent
                result = f"error: {e}"

        messages.append({"role": "tool", "name": name, "content": result})

    return "Stopped: reached max steps."

Walkthrough

On the example:

1. messages = [user: "what is 2 + 3?"]. model sees no tool result yet and returns a tool call add(a=2, b=3).
2. We append the tool call, run tools["add"] -> "5", and append {"role": "tool", "name": "add", "content": "5"}.
3. Next iteration: model now sees a tool message and returns {"type": "final", "content": "The answer is 5."}, which we return.

Complexity & notes

• Time is O(steps × model/tool cost); the loop itself is O(1) bookkeeping per step. Space is O(total messages).
• The max_steps cap is the single most important line — without it, a model that keeps calling tools loops forever and burns money.
• Unknown-tool and tool-exception handling append an error as a tool result so the model can see it and recover on the next turn (the basis of “reflect and retry”, covered in the Reliability pattern).
• Real frameworks add streaming, parallel tool calls, and token accounting, but this loop is the irreducible core.