Free AI agents course
Learn how to build AI agents by building one: tools, the agent loop, MCP, permissions, context management and evals, ending with a coding agent that stops when its tests pass.
Put the parts you built beside the tool runner and the Agent SDK, choose a surface for a job, and take an MCP server's tools into your registry with prefixed names, one rule per server and a capped result.
You can finish this phase having built every part of a harness and still not have seen the line you will write at work. Real harnesses are built from the same parts under other names, and most of the work is mapping one onto the other. This lesson puts the parts beside the three surfaces you meet first, then does the one thing the capstone could not: it plugs the tools of an MCP server into your registry.
Which of my parts does it provide
The parts are the same. What differs is who writes each one, who hosts the run and where a check can go.
Recall: Capstone: build a coding agent built a coding agent from its parts, and What an agent harness is named four ways to get one running. The three you meet first at work are a loop you write, the API SDK's tool runner, and the Agent SDK. Managed agents, where Anthropic hosts the loop and a sandbox, are the fourth.
The table puts each part you built beside its name on each surface. The names and options change between versions, so use it as a map and read the current docs for the lines.
| part you built | manual loop | tool runner | Agent SDK |
|---|---|---|---|
the loop over stop_reason | your while | client.beta.messages.tool_runner(...) | query(...) |
| tools and schemas | your registry | @beta_tool functions | built-in tools plus your own |
| permissions | your policy | a check in your function | permission mode, rules, can_use_tool |
| hooks | your hook bus | per-turn code you add | hooks= by event |
| context | your manager | request options | handled for you |
| subagents | your function | you start them | agents= definitions |
| sessions | your JSONL log | you keep it | resume and fork by id |
Every box is a part you built. What changes between the three is how many of them you still write. Names and options change between versions, so read the current docs.
A row in the table is a promise about who owns a decision, not a promise about quality. With a loop you write, the model call is a function you hold, so a test can pass in a script and a budget can stop the run between any two calls. With the tool runner, the loop is the SDK's, and you act per turn through what it exposes. With the Agent SDK, most decisions have a default that is good for coding work, and your job is to set the few that are not: which tools, which permission mode, how many turns. With managed agents, the run happens on Anthropic's machines: you give up some control over where it runs and gain a container you do not have to build.
None of these removes the questions of this phase. It moves them. Who may delete a file? What does a run cost? When does it stop? Where is the log? You ask them of whichever surface you choose, and you write the answers into its configuration, its hooks or your own code.
Hooks: code the harness runs at a fixed moment
The stop check is code at a lifecycle event. On the Agent SDK it would be a hook, on a loop you write it is an if after end_turn.
name = 'shop__get_campaign' server, _, raw = name.partition('__') print(server, raw)
shop get_campaign
partition splits at the first __ and returns the pieces on either side of it.
The permission check and the session log
The runner owns the loop and makes schemas from your signatures. The rest of the harness is still yours.
Write a sentence or two, then compare it with a good answer in the lesson.
The capstone could not use MCP, because it had no server to talk to. The practice server at /mcp has three tools: list_campaigns, get_campaign and search_docs. The lesson's setup defines rpc, the one function that sends a JSON-RPC request to it, the way Build a client did.
Three things change when a server's tools join your registry. Names get a server prefix, so two servers cannot clash. One permission rule can cover a whole server. And every result is capped, because a server's output is as unbounded as any tool's.
The registry lists the server's tools, stores each under shop__<name>, turns inputSchema into input_schema, and routes a call back to the raw name. It caps the text the server returns.
The lesson runs this once, before its first cell, and every cell, drill and example starts with what it defines. A cell that changes a setup object changes it for the cells after it, until the page reloads.
import json import requests MCP = "https://api.gradient.test/mcp" PV = "io.modelcontextprotocol/protocolVersion" CAPS = "io.modelcontextprotocol/clientCapabilities" def rpc(method, params=None, name=None): headers = {"MCP-Protocol-Version": "2026-07-28", "Mcp-Method": method} if name: headers["Mcp-Name"] = name body = {"jsonrpc": "2.0", "id": 1, "method": method, "params": {**(params or {}), "_meta": {PV: "2026-07-28", CAPS: {}}}} return requests.post(MCP, json=body, headers=headers).json()["result"]
class Registry: def __init__(self, cap=300): self.tools, self.cap = {}, cap def add_server(self, server): for tool in rpc("tools/list")["tools"]: name = server + "__" + tool["name"] self.tools[name] = {"server": server, "raw": tool["name"], "definition": {"name": name, "description": tool["description"], "input_schema": tool["inputSchema"]}} def call(self, name, args): tool = self.tools[name] result = rpc("tools/call", {"name": tool["raw"], "arguments": args}, name=tool["raw"]) text = result["content"][0]["text"] if len(text) > self.cap: cut = len(text) - self.cap text = text[:self.cap] + f"\n[... {cut} characters cut ...]" return text, result.get("isError", False) registry = Registry() registry.add_server("shop") for name, tool in registry.tools.items(): print(name, list(tool["definition"]["input_schema"]["properties"])) text, is_error = registry.call("shop__list_campaigns", {}) print(len(text), "characters,", "error" if is_error else "ok") print(registry.call("shop__get_campaign", {"id": "1"}))
The registry holds shop__list_campaigns with one property, status, shop__get_campaign with id, and shop__search_docs with query: the server's camelCase inputSchema became the API's input_schema. The campaign list is 533 characters, so a cap of 300 cuts 233 of them, and the text the model sees is 329 characters long with its note. The last line asks for campaign id 1, which does not exist. The server answers with isError true and a message that says what ids look like, so the model can try again. That is the same advice as A tool registry for agents: an error is a message to the model.
from fnmatch import fnmatchcase print(fnmatchcase('shop__get_campaign', 'shop__get_*'), fnmatchcase('docs__get_page', 'shop__get_*'))
True False
The first name matches the pattern shop__get_*. The second belongs to another server, so it does not.
Write route(name): split a registry name such as shop__get_campaign into (server, raw) at the first double underscore. A name with no __ raises ValueError.
Uses the setup above, 14 lines.
def route(name): return ("", name) print(route("shop__get_campaign"))
Write decide(name, rules). Each rule is "effect:pattern" with a wildcard pattern. A matching deny wins, then a matching ask, then a matching allow. A name no rule matches is "ask".
Uses the setup above, 14 lines.
from fnmatch import fnmatchcase def decide(name, rules): return "allow" print(decide("shop__get_campaign", ["allow:shop__*", "ask:shop__get_*"]))
Cap it and say how much was cut
One call must not flood the window. The cap is the registry's job whatever the source.
Write a sentence or two, then compare it with a good answer in the lesson.
The same registry sits behind the real SDKs. In the Agent SDK a server is a line of options, and its tools arrive with the prefix mcp__<server>__<tool>. In the tool runner a server's tool is a function you write, and the registry's rule and cap sit inside it. In both, the checks you wrote in this phase still apply: they move to a different place.
Three questions settle most choices. Who must host the run: you, or a service that also gives you the sandbox? How much of the harness do you need to change: a little, so a ready-made one fits, or a lot, so you want the loop in your own hands? And where must a check sit: between any two model calls, which needs your own loop, or at a lifecycle event, which hooks cover? Write the answers down before you read a framework's feature list, because the list will make every part sound necessary.
In an engineer's week the question is rarely which SDK is best. It is which parts you must still own: the permission rules, the budget, the session log and the checks. Choose the surface that leaves you the parts you need to control, and write those yourself.
Write a sentence or two, then compare it with a good answer in the lesson.
Which part of the harness does the SDK's tool runner provide?
575 lessons in thirteen phases. 176 are free without an account, and a free account opens the rest. See every lesson.
Learn how to build AI agents by building one: tools, the agent loop, MCP, permissions, context management and evals, ending with a coding agent that stops when its tests pass.
Never trained an AI? Teach a small one to write, right in your browser. It takes about 20 seconds and needs no account. Teach it to write