The Tool Registry & the Agent Loop

Before an AI model can use a tool, we have to describe that tool in a way both our program and the model understand. This block defines a single container — a Tool — that packs everything about one tool into one object: what it's called, what it does, what inputs it takes, how dangerous it is, and the actual code that runs it. A @dataclass is just Python's shortcut for "a simple record with named fields".

1. The five lines under class Tool: are the fields every tool must have: name (short id like "kubectl_logs"), description (plain-English text the model reads to decide when to use it), input_schema (what arguments it accepts), risk (how dangerous — the field the safety gate will check later), and run (the real Python function to execute).
2. risk: RiskClass is called out with a comment as the safety-critical field. Keeping the risk level glued to the tool means later code can look up "how dangerous is this tool?" in one place — you can never accidentally run a tool without knowing its risk.
3. def spec(self) returns a small dictionary with just name, description, and input_schema. That is exactly the shape the Anthropic API's tools=[...] parameter expects — so spec() is how we hand a tool to the model without leaking our internal risk and run fields.
4. TOOLS: dict[str, Tool] = {} is an empty registry — a phone book that maps each tool's name to its Tool object. register(tool) simply adds a tool to that book. _obj(...) is a tiny helper that builds the standard "object with these properties" JSON schema, so we don't repeat it for every tool.

What the output means: Nothing prints — this file only defines the shape of a tool and an empty registry. It's the foundation the next steps fill in.

Try this: Ask yourself: which field does the model actually see, and which stays private to your program? (Hint: only the three fields returned by spec() go to the model; risk and run never leave your machine.)

Here we actually create and register two real tools. Each register(Tool(...)) call fills in the five fields from Step 1 for one tool and drops it into the TOOLS registry. These are read-only tools — they only look at the mock cluster, they never change anything — so they are completely safe to let the model call.

1. The first tool is named "kubectl_get_pods". Read its description: "List pods with status and restart counts. Use FIRST when diagnosing…". That sentence is written for the model to read — the words "Use FIRST" nudge the model to check pod health before anything else. A good description is how you steer an agent's behaviour.
2. _obj({"namespace": {"type":"string"}}, []) is the input schema: it says "this tool accepts one optional argument called namespace that is a string". The empty list [] means no argument is required.
3. RiskClass.READ_ONLY tags the tool as safe. The lambda on the next line is the actual code that runs when the model calls the tool — here it just forwards the request to cluster.get_pods(namespace) and defaults namespace to "staging".
4. The second tool, "kubectl_logs", follows the identical recipe but requires a pod argument (note ["pod"] in the schema). The trailing comment says the other tools use the same pattern — once you understand one register(Tool(...)) block, you understand them all.

What the output means: Again nothing prints; each call quietly adds one tool to the TOOLS registry. After this file runs, TOOLS holds several named, described, risk-tagged tools ready for the model to choose from.

Try this: Reword kubectl_get_pods's description to be vague (e.g. just "lists pods") and imagine the effect: with weaker wording the model is less likely to call it first. The description is the instruction manual you give the model.

This is the agent loop — the beating heart of the whole capstone. An "agent" is just a loop that: (1) asks the model what to do, (2) if the model asks to use a tool, runs that tool, (3) feeds the tool's result back to the model, and (4) repeats until the model says it's finished. The model never touches your systems directly — your loop runs the tools on its behalf.

1. MAX_STEPS = 8 and for _ in range(MAX_STEPS): set a hard cap of 8 passes. The comment says always terminates — this guarantees the loop can never run forever, even if the model keeps asking for more tools. A step cap is a basic safety net for every agent.
2. messages is the running conversation. It starts with the user's incident. Each pass calls client.messages.create(...), sending the system instructions, the tools=specs list (from Step 2's registry), and the whole conversation so far. The model reads it all and replies.
3. if resp.stop_reason == "end_turn": means the model is done — it has no more tools to call and just wants to answer. We pull out its text reply and return it, ending the loop.
4. Otherwise the model asked to use one or more tools. We first append the model's turn to messages verbatim, then loop over resp.content: for each block where b.type == "tool_use", we run the matching tool with TOOLS[b.name].run(**b.input) and collect the result.
5. Each result is packaged as a tool_result carrying the same b.id (its tool_use_id) so the model knows which request it answers. All results go back in one user message (messages.append(...)), and the loop repeats. If we ever exhaust all 8 steps, the final return reports it hit the step limit.

What the output means: When run, this returns Claude's final diagnosis as plain text — after it has silently called whatever read-only tools it needed along the way. If the model gets stuck looping, you'd instead see "Stopped: hit step limit."

Try this: Trace one full lap in your head: user asks → model says "call kubectl_get_pods" → loop runs it → result appended → model reads result and either answers (end_turn) or asks for another tool. That call-run-feedback cycle is what makes it an agent.

Now you actually run the agent from a terminal. This is the first time the code talks to the real model over the internet, so an API key is needed from here on. You type the incident in plain English and let the agent investigate.

1. cd devops-agent moves into the project folder. python cli.py "checkout-api-7d9f in staging keeps restarting" launches the program and passes your incident description as the input the loop will send to the model.
2. You did not tell it which tools to run or in what order. The agent decides that itself using the tool descriptions from Step 2 — that is the whole point of an agent.

What the output means: The OBSERVE rung line confirms it stayed at the safe, read-only level. The paragraph is the model's diagnosis: it connected the crash-looping pod, the "password authentication failed" log line, and a recent deploy that changed the database secret — then suggested a fix without touching anything. The audit log below lists every tool it called (all [read_only]), giving you a full trail of what the agent did.

Try this: Read the three audit lines in order — pods, then logs, then deploys. That ordering came straight from the "Use FIRST" wording in the tool descriptions. Change the incident text and watch which tools the agent chooses to call.

Good agents come with tests. The clever move here is splitting tests into ones that need no API key (fast, free, always run) and ones that call the model (slower, cost money). These two tests are the free kind — they check the registry and tool wiring without ever contacting Claude.

1. test_every_tool_has_a_risk_class loops over every tool in the TOOLS registry and asserts that its risk really is a RiskClass. The message f"{name} missing risk" is what prints if one is missing — so no tool can ever sneak into the registry untagged and later slip past the safety gate.
2. test_readonly_tool_runs_and_returns_data actually calls the kubectl_get_pods tool and checks the returned pods include one in "CrashLoopBackOff". This proves the registry is correctly wired to the mock cluster — the tool runs and gives back real data.
3. An assert is a test's way of saying "this must be true". If it is, the test passes silently; if not, the test fails and shows your message — that's how you know something broke.

What the output means: Run with pytest, both tests pass silently (no output means success). Because neither talks to the model, they run in a fraction of a second and cost nothing — safe to run on every commit in CI.

Try this: Temporarily change a tool's risk to a plain string like "safe" instead of a RiskClass, and rerun — the first test will fail and print … missing risk, showing you exactly how the guard catches mistakes.