Index Ai Academy
Phase 10 · Scaling & shipping

The same agent on the real SDKs

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.

About 35 minutes · Model names and API rules checked November 2026 · A free account opens the whole lesson.
Already have an account? Sign in to open this lesson

What it covers6

Why it matters

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.

What you'll be able to do

  • Match each part of the harness you built to the real tool that provides it: the manual loop, the SDK's tool runner and the Agent SDK
  • Take the tools of an MCP server into a registry, with prefixed names, one permission rule per server and a capped result
  • Choose the surface for a job: who writes the loop, who hosts it, and where a check can go
  • Read the SDK lines you will write at work as the parts you already built
Quick check
Your capstone harness and a framework's agent both run a model, tools and a loop. What is the useful first question when you meet the framework?
  1. Does it use a different model?
  2. How many stars does it have?
  3. Which language is it written in?
  4. Which of my parts does it provide
Show the answer

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.

The idea: the same parts, on three surfaces

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 builtmanual looptool runnerAgent SDK
the loop over stop_reasonyour whileclient.beta.messages.tool_runner(...)query(...)
tools and schemasyour registry@beta_tool functionsbuilt-in tools plus your own
permissionsyour policya check in your functionpermission mode, rules, can_use_tool
hooksyour hook busper-turn code you addhooks= by event
contextyour managerrequest optionshandled for you
subagentsyour functionyou start themagents= definitions
sessionsyour JSONL logyou keep itresume and fork by id
Try it now

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.

What the table hides

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.

Quick check
Recall: Capstone: build a coding agent ended a run only when the harness's own test run passed. Which part of a harness does that stop check belong to?
  1. The session log
  2. The model, which says when it is done
  3. Hooks: code the harness runs at a fixed moment
  4. The tool registry
Show the answer

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.

Quick check
What does this print?
name = 'shop__get_campaign'
server, _, raw = name.partition('__')
print(server, raw)
  1. shop get
  2. get_campaign shop
  3. shop get_campaign
  4. shop__get_campaign
Show the answer

shop get_campaign

partition splits at the first __ and returns the pieces on either side of it.

Quick check
Which of these is yours to write when you use the SDK's tool runner? to write when you use the SDK's tool runner?
  1. The tool schemas, which it makes from your functions' signatures
  2. The permission check and the session log
  3. The retry of a rate limit
  4. The loop over stop_reason
Show the answer

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.

In your own words
A framework's docs say it "manages the agent loop, tools and sessions". What do you ask before choosing it?

Write a sentence or two, then compare it with a good answer in the lesson.

In code: take a server's tools into the registry

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.

Worked example

A registry that takes a server's tools

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.

Setup (runs before every cell) · 14 lines

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"}))
In the lesson you can change this and run it.

Reading what it printed

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.

Quick check
What does this print?
from fnmatch import fnmatchcase

print(fnmatchcase('shop__get_campaign', 'shop__get_*'),
      fnmatchcase('docs__get_page', 'shop__get_*'))
  1. False False
  2. False True
  3. True True
  4. True False
Show the answer

True False

The first name matches the pattern shop__get_*. The second belongs to another server, so it does not.

Drill

Split a prefixed name

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"))
In the lesson, your code is checked as you write it.
Drill

One rule for a whole server

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_*"]))
In the lesson, your code is checked as you write it.
Quick check
A server's tool returns 2 MB of text. What should the registry do before the model sees it?
  1. Cap it and say how much was cut
  2. Summarize it with a second model first, always
  3. Drop the call
  4. Send it all, since the server is trusted
Show the answer

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.

In your own words
Why prefix every server tool's name with the server's name?

Write a sentence or two, then compare it with a good answer in the lesson.

In a production harness: the real lines

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.

Choosing the surface

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.

In your own words
A teammate wants to replace your harness with the Agent SDK. What do you check first?

Write a sentence or two, then compare it with a good answer in the lesson.

Practice what you just read

  • 1 code example you can edit and run
  • a practice exercise that checks your code
  • a 5-question quiz
  • 6 review cards for spaced repetition

Try a quiz question

Which part of the harness does the SDK's tool runner provide?

  1. The loop over stop_reason
  2. Permissions and hooks
  3. Sessions and subagents
  4. A sandbox container

Answer it at the end of the lesson to see if you're right, and why.

Before this lesson

Keep learning

Where this lesson leads.

575 lessons in thirteen phases. 176 are free without an account, and a free account opens the rest. See every lesson.

Phase 10 · about 20 hours of study

Agent harnesses

Build the software around a model that turns it into a capable, safe agent 24 lessons 1 free
  1. What an agent harness is FreeThe software around a model that turns it into an agent.35 min
  2. The core loop, built properlyStop reasons, parallel tool calls, errors and turn budgets.40 min
  3. A tool registry for agentsSchemas from functions, validation, output limits and helpful errors.40 min
  4. File and search toolsRead, write, edit by exact replacement, glob and grep inside one folder.45 min
  5. Running code safelyExecution tools, step limits, output caps and real sandboxes.45 min
  6. Giving an agent a databaseSchema as context, a query tool with caps and readable errors, guards in layers, and execution accuracy.45 min
  7. Permissions and approvalsRules, modes and approval prompts that keep a person in control.40 min
  8. Hooks and skillsExtend a harness at lifecycle events, and load know-how on demand.40 min
  9. Multi-agent systemsCoordinating many agents on one large job.35 min
  10. Managing the context windowBudgets, clearing old tool results, compaction and a cacheable prefix.45 min
  11. Memory, plans and long tasksTo-do lists, progress notes, memory files and checkpoints.45 min
  12. SubagentsHand a focused task to a fresh context with fewer tools.40 min
  13. Streaming, interrupts and sessionsLive output, stopping safely, and saving and resuming transcripts.40 min
  14. Agents as graphsState, reducers and routing, a checkpoint after every step, and pausing for a person's approval.45 min
  15. Evaluation harnessesRun agents on tasks in fresh environments and grade what they leave behind.45 min
  16. Tracing, budgets and guardrailsSee what an agent did, cap what it spends, and stop it when it loops.40 min
  17. Attack your own harnessRun fourteen attacks against a harness with switches, read which layer stops each one, score attacks stopped against ordinary tasks done, and keep every finding as a release test.40 min
  18. Capstone: build a coding agentA harness that edits a project, runs its tests and stops when they pass.45 min
  19. The same agent on the real SDKsPut 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.35 min
  20. Agents that use a computerAn agent with a screen, a mouse and a keyboard: the observe-decide-act loop, what a click lands on, why a wrong hit is worse than a miss, what happens when the screen changes under a plan, and what screenshots cost.45 min
  21. Sandboxes for agents that browseTreat every page as untrusted input: check hosts properly, gate actions by their effect, and layer the defenses.45 min
  22. Protocols between agentsHand a task to an agent someone else built: agent cards, the life of a task, the messages on the wire, safe retries, and whom to trust.45 min
  23. Tracing a run end to endFollow one run across an orchestrator, subagents and tool servers: trace ids, the traceparent header, the critical path, tokens by branch, and which traces to keep.45 min
  24. Retrieval over a graphAnswer questions that hop between documents: facts as triples, a walk out from the entities a question names, and the hubs and missed facts that limit it.45 min
Part of a free course 29 lessons

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.

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