What an agent actually is

1. Send messages and tool definitions
2. Did the model request a tool?
      no  -> done, return its answer
      yes -> run the tools, append the results, go to 1

def run(task: str, max_turns: int = 10) -> str:
    messages = [{"role": "user", "content": task}]

    for turn in range(max_turns):
        response = client.chat(messages, tools=TOOLS)
        messages.append(response.message)

        if response.stop_reason != "tool_use":
            return response.text                  # model is done

        for call in response.tool_calls:
            result = run_tool(call)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            })

    return "Stopped: reached the turn limit."

import json

def find_order(customer):
    return {"order_id": "A-4471", "total_cents": 2900}

def refund(order_id):
    return {"refunded": order_id}

TOOLS = {"find_order": find_order, "refund": refund}

class StubModel:
    """A scripted stand-in for a hosted model, so the loop runs offline and
    prints the same thing on every run. One script entry per response."""
    def __init__(self, script):
        self.script, self.calls = list(script), 0

    def chat(self, messages, tools=None):
        self.calls += 1
        return self.script[min(self.calls, len(self.script)) - 1]

def run(model, task, max_turns=6):
    messages = [{"role": "user", "content": task}]
    transcript = []
    for turn in range(max_turns):
        reply = model.chat(messages, tools=TOOLS)
        messages.append({"role": "assistant", "content": reply})
        if reply["stop_reason"] != "tool_use":
            return reply["text"], transcript
        for call in reply["tool_calls"]:
            result = TOOLS[call["name"]](**call["args"])
            transcript.append((turn, call["name"], call["args"], result))
            messages.append({"role": "tool", "content": json.dumps(result)})
    return "stopped: reached the turn limit", transcript

SCRIPT = [
    {"stop_reason": "tool_use",
     "tool_calls": [{"name": "find_order", "args": {"customer": "ada"}}]},
    {"stop_reason": "tool_use",
     "tool_calls": [{"name": "refund", "args": {"order_id": "A-4471"}}]},
    {"stop_reason": "end_turn", "text": "Refunded order A-4471."},
]

answer, transcript = run(StubModel(SCRIPT), "Refund Ada's most recent order.")
for turn, name, args, result in transcript:
    print(f"turn {turn}: {name}({args}) -> {result}")
print("answer:", answer)

# turn 0: find_order({'customer': 'ada'}) -> {'order_id': 'A-4471', 'total_cents': 2900}
# turn 1: refund({'order_id': 'A-4471'}) -> {'refunded': 'A-4471'}
# answer: Refunded order A-4471.

BAD_CALLS = [
    {"name": "refund",     "args": {"order_id": "A-4471"}},       # fine
    {"name": "refund",     "args": {"order": "A-4471"}},          # wrong key
    {"name": "refund",     "args": {}},                           # nothing at all
    {"name": "refund_ord", "args": {"order_id": "A-4471"}},       # invented tool
]

def dispatch_naive(call):
    return TOOLS[call["name"]](**call["args"])

def dispatch(call):
    """Never raises. Every outcome is something the model can read and act on."""
    fn = TOOLS.get(call["name"])
    if fn is None:
        return {"ok": False, "error": "no tool named " + call["name"]
                + ". Available: " + ", ".join(sorted(TOOLS))}
    try:
        return {"ok": True, "result": fn(**call["args"])}
    except TypeError as e:
        return {"ok": False, "error": "bad arguments: " + str(e)}
    except Exception as e:
        return {"ok": False, "error": type(e).__name__ + ": " + str(e)}

survived = 0
for call in BAD_CALLS:
    try:
        dispatch_naive(call)
        survived += 1
    except Exception as e:
        print("naive loop died:", type(e).__name__)
print("naive dispatcher survived", survived, "of", len(BAD_CALLS), "calls")
print()
for call in BAD_CALLS:
    print(dispatch(call))

# naive loop died: TypeError
# naive loop died: TypeError
# naive loop died: KeyError
# naive dispatcher survived 1 of 4 calls
#
# {'ok': True, 'result': {'refunded': 'A-4471'}}
# {'ok': False, 'error': "bad arguments: refund() got an unexpected keyword argument 'order'"}
# {'ok': False, 'error': "bad arguments: refund() missing 1 required positional argument: 'order_id'"}
# {'ok': False, 'error': 'no tool named refund_ord. Available: find_order, refund'}

ORDERS = {"A-4471": {"total_cents": 2900, "status": "shipped"}}
WANT = 900          # the customer is owed 9.00, not the whole order

def refund_loose(order_id, amount_cents=None):
    """Defaults that act. Omitting the amount refunds everything."""
    amount = ORDERS[order_id]["total_cents"] if amount_cents is None else amount_cents
    return {"ok": True, "refunded_cents": amount}

def refund_strict(order_id, amount_cents):
    """No default, one unit in the name, and the value checked against the order."""
    if not isinstance(amount_cents, int):
        return {"ok": False, "error": "amount_cents must be a whole number of cents, "
                                      "got " + repr(amount_cents)}
    total = ORDERS[order_id]["total_cents"]
    if not 0 < amount_cents <= total:
        return {"ok": False, "error": f"amount_cents must be between 1 and {total}"}
    return {"ok": True, "refunded_cents": amount_cents}

EMITTED = [
    {"order_id": "A-4471", "amount_cents": 900},   # what you hoped for
    {"order_id": "A-4471"},                        # forgot the amount
    {"order_id": "A-4471", "amount_cents": 9.0},   # dollars, not cents
]

for label, fn in (("loose", refund_loose), ("strict", refund_strict)):
    for args in EMITTED:
        try:
            out = fn(**args)
        except TypeError as e:
            out = {"ok": False, "error": "bad arguments: " + str(e)}
        verdict = ("correct" if out.get("refunded_cents") == WANT
                   else "REJECTED" if not out["ok"]
                   else "SILENTLY WRONG: refunded " + str(out["refunded_cents"]))
        print(f"{label:<7}{str(args):<50}{verdict}")

# loose  {'order_id': 'A-4471', 'amount_cents': 900}       correct
# loose  {'order_id': 'A-4471'}                            SILENTLY WRONG: refunded 2900
# loose  {'order_id': 'A-4471', 'amount_cents': 9.0}       SILENTLY WRONG: refunded 9.0
# strict {'order_id': 'A-4471', 'amount_cents': 900}       correct
# strict {'order_id': 'A-4471'}                            REJECTED
# strict {'order_id': 'A-4471', 'amount_cents': 9.0}       REJECTED

# Each task needs some number of lookups before the answer is knowable. You do
# not know that number in advance; that is the whole difficulty.
DEPTHS = [1, 1, 1, 2, 1, 3, 8]
MAX_CALLS = 6

def pipeline(depth):
    """Look up once, then answer. Two model calls, always."""
    return 2, depth <= 1

def pipeline_with_a_decision(depth):
    """Look up; if that missed, look up in the other system; then answer."""
    return min(depth, 2) + 1, depth <= 2

def agent(depth):
    """Keep going until the model stops asking, or the cap trips."""
    calls = min(depth + 1, MAX_CALLS)
    return calls, depth + 1 <= MAX_CALLS

print(f"{'strategy':<26}{'model calls':>12}{'solved':>9}")
for name, fn in (("pipeline", pipeline),
                 ("pipeline with a decision", pipeline_with_a_decision),
                 ("agent", agent)):
    runs = [fn(d) for d in DEPTHS]
    calls = sum(c for c, _ in runs)
    solved = sum(ok for _, ok in runs)
    print(f"{name:<26}{calls:>12}{solved:>6}/{len(DEPTHS)}")
print("worst case calls: pipeline 2, decision 3, agent", MAX_CALLS, "(the cap)")

# strategy                   model calls   solved
# pipeline                            14     4/7
# pipeline with a decision            17     5/7
# agent                               21     6/7
# worst case calls: pipeline 2, decision 3, agent 6 (the cap)