Recipes¶
One page per wall you can hit. Each is the same shape: the question in the title, why you'd be here, one runnable script, what's actually happening, and the things that bite people.
Every snippet on these pages runs. Where a specific provider isn't the
point of the page, the model is a FakeLLM from agentkit.core.testing, so
you can paste and run with no API key. Where a key really is required,
the page says so on its first line.
If you want a linear walkthrough instead, use the Tutorial; for the mental model of a primitive, the Concepts; for the tightest possible menu while you're already writing code, the Cheatsheet.
Unfamiliar word? The glossary defines every term these recipes use in a sentence of plain English.
Making the agent do something¶
-
Give an agent a tool
Turn a Python function into something the model can call, and declare up front which calls mutate the world. Schemas,
ctxinjection, result validation, an agent as a tool. -
Answer from my documents
Retrieval and grounding, so the answer comes from your handbook rather than from training data that resembles it. One
MemorySourceProtocol, ten backends that nest. -
Stream a typed object
output=MyModelgives youAgentResult.parsedat the end;StreamEvent.partial_outputgives you the object filling in field by field, on every delta. -
Consume an MCP server
Point at any published MCP server and get its tools, resources, and prompts through agentkit's canonical
Tool,MemorySource, andPromptProtocols. -
Serve your tools to the Claude CLI
The CLI owns its loop, so you hand it a server rather than a function.
serve_registrybuilds one from aToolRegistryyou already have — and the calls come back through your middleware.
Structuring the work¶
-
Run a fixed multi-step pipeline
A
Workflowgraph: declared dependencies, concurrent waves, branching, bounded loop-back, human gates with durable resume. Explicit control, when the order is yours to decide. -
Split work across several agents
Coordinators, the four policies,
Handoffrouting, composable termination conditions. Emergent control, when who-goes-next depends on what was said. -
Run agents in parallel, cancel on failure
run_agentsunder a shared budget and cancel token. One failure stops the siblings;best_effort=Trueisolates failures intoFailureobjects instead.
Keeping a person in the loop¶
-
Pause a tool for approval
Approve, reject, or rewrite the arguments — with the run suspended to a checkpoint so an entirely fresh process can pick it up.
-
Ask a person for a value
Not yes/no: a one-time code, mid-run, nowhere near a tool call. Parkable in place, deadlined, typed, and secret-safe.
Controlling cost and behaviour¶
-
Cap spend
Budgetfor a hard per-run ceiling,Quotafor a rolling per-tenant window, andon_exceeded="stop"to make exhaustion recoverable rather than fatal. -
Keep a long conversation in budget
Four compactors and two places to put them, so turn 40 doesn't cost forty times turn 1 and then stop fitting at all.
-
Pick a provider from config
One model string decides the client, the credential, and whether that model can do the job at all — refused at construction, before any spend.
-
Write a custom middleware
Redact a secret, time a call, cache on your own key. Two shapes:
BaseMiddlewareto transform/guard/observe, raw(call, next)to retry, skip, or wrap.
Running it in production¶
-
Survive a crash
Same
run_id, sameCheckpointPort, hydrated transcript — the next worker continues from the last completed iteration rather than starting over. -
Wire OpenTelemetry
TracePortandMetricsPortinto Tempo, Jaeger, Datadog, Honeycomb — anything that speaks OTLP. One adapter each inarc-agentkit[observability]. -
Test an agentkit app
FakeLLMandmake_test_ctx: offline, deterministic, and able to produce on cue the failures a real provider never will when you want them. -
Use the local
claudeCLI
ClaudeCliCognitionsubprocesses your installed CLI — its auth, its tools, its permission modes — behind a FastAPI endpoint, with the spend still on yourBudget.