What do you want to build?

The rest of the docs are organised by primitive — MCP, skills, suspension, sub-agents. This section is organised by what you’re trying to build. Each scenario page takes one real, production-shaped agent and wires it end to end in the seven published languages, including the parts that are not included and why. Every scenario on this page carries all seven — JavaScript, Python, Go, Java, C#, Elixir and Clojure. Clojure ships the agent layer too: the §7D runtime (sub-agents, the task tool, hierarchical budgets), §7E personas (from-dir, the memory tool, the heartbeat) and §7F compaction, alongside MCP, skills, native/HTTP/built-in tools, conversation memory, suspension and A2A serve (see the Clojure API page). Its shapes are native — an AgentDef is a plain map, and you run one with rt/run-agent or expose it with rt/agent-tool — but the behavior is the same contract as the other six.

New here? Start with the quickstart

If you have not run toolnexus yet, do zero to agent in 3 steps first (about five minutes). These pages assume you already have a toolkit and a client in your hands.

Pick your goal

Your goal	Scenario	Core primitives
“An assistant that works on my codebase” — reads files, runs the test suite, proposes an edit, and delegates the boring parts	Coding assistant	built-in tools (bash, file read/write) · agent skills · agent() + team + the task tool · budgets
“An assistant that remembers me” — an identity in files, notes it updates over weeks, acts on its own clock	Personal assistant	fromDir · the memory tool · startAgent heartbeat · compactor
“Research five things at once and merge the findings” — a coordinator fanning out to isolated workers	Research orchestrator	agent() + team · parallel task calls · maxConcurrent · usage roll-up
“An agent over my real systems, with a human on the risky bits” — orders/CRM over MCP, policy as skills, refunds gated by approval, served to a web app	Support / ops agent	mcpConfig + per-server allowlist · skills · pending/waitFor · serve · budgets
“An agent that gets better over time” — records what worked, folds it back into its own instructions	Self-improving agent	memory tool · heartbeat consolidation · onTask/metrics · skills as the editable policy layer
“Output that must be right before it ships” — a worker produces, an independent adversarial verifier must pass it before the result leaves the agent	Verify-before-commit gate	agent() + task isolation (final-text-only) · adversarial verifier soul · scoped uses · bounded retry loop · budget

Nothing here is mutually exclusive. A support agent that remembers a customer is the support scenario plus fromDir; a coding assistant that asks before force-pushing is the coding scenario plus waitFor. The primitives compose because they are all the same two nouns underneath — a Tool and a loop.

Primitives cheat sheet

One line each.

Primitive	What it gives you
createToolkit	The aggregator: MCP servers + skills + your functions + HTTP + built-ins + A2A agents behind one Tool interface.
createClient / run / ask	The host loop — tool calling, retries, streaming, conversation memory — against any OpenAI- or Anthropic-style endpoint.
agent()	An agent is a tool: system prompt × a filtered toolkit view × the loop. .run() for one-shot, .asTool() to drop it into any toolkit.
team + task	Listing agents in team is the sub-agent wiring — they become the only targets of the child-facing task tool. No team ⇒ no delegation (opt-in, non-recursive by default).
Budget	maxTurns/maxTokens/maxToolCalls/maxWallMs/maxChildren/maxConcurrent/maxDepth, carved at spawn and re-walked live before every turn. Any stop is loud: status:"incomplete" with the limit named.
pending / waitFor	A tool returns Pending(request) instead of an answer; the host resolves it. Inline with a waitFor, or durably as status:"pending" you persist and resume later.
fromDir	The directory is the agent: AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, HEARTBEAT.md, MEMORY.md compose the system prompt at session start.
memory	An opt-in, file-backed tool with three actions (add/replace/remove) over MEMORY.md or USER.md. Writes hit disk now; they load into the prompt at the next session (frozen-snapshot rule).
startAgent heartbeat	Gives a persona its own clock: each everyMs it posts a tick to its own inbox and wakes it to read HEARTBEAT.md. A HEARTBEAT_OK reply is silent.
compactor	A beforeLLM hook that summarizes the older transcript and keeps a recent tail — tool-pair safe, system prompt preserved. Below maxTokens it is a byte-identical no-op.
serve	The inbound direction: expose the toolkit as an A2A agent (Agent Card + JSON-RPC, skills-based) and/or as an MCP server (POST /mcp, tools-based). No auth in core.
Hooks	beforeLLM / afterLLM / beforeTool / afterTool — guardrails, redaction, caching, cost tracking. beforeTool can deny or rewrite a call before it runs.

How to read a scenario page

Each one follows the same spine, so you can skim to the part you need:

1. The scenario and a when to reach for this table — including when not to.
2. The wiring at a glance — layer → primitive → SPEC section.
3. Step-by-step build, with the full example in JavaScript, Python, Go, Java, C#, Elixir and Clojure.
4. Honest limits — what the library deliberately leaves to you (auth, UI, storage, policy).

Seven ports, one behavior

Every scenario is expressible in all seven languages because parity is the product: the same mcp.json and the same SKILL.md folder produce the same tools and the same byte-exact skill output in JavaScript, Python, Go, Java, C#, Elixir and Clojure. Pick the language your service is already written in.

Zero to agent in 3 stepsCore concepts