Working with Agents

Most of the documentation describes one agent — its identity, its tools, what it is allowed to do. This section is about what happens when there is more than one: how you run them together, how they talk, who owns their lifetime, and how you debug a system made of several minds instead of one.

// review.axon.ts
import { Fleet } from "@axon/core"

const { barry, checker } = await Fleet({
    barry:   "../barry",
    checker: "../checker",
})

const review  = await barry.request("review the changes on this branch")
const verdict = await checker.request(`is this review fair?\n\n${review.text}`)

console.log(verdict.text)

Two agents, two policies, two toolsets, two isolated memories, in one ordinary TypeScript file.

Agents are whole, not parts

The single idea this section is built on: an agent is a complete, bounded thing, and the only way in or out is the stimulus protocol.

A mind takes in text, audio, and images. It emits text, audio, images, and actions. That is the entire surface — the same one whether the thing on the other side is a person, a webhook, or another agent. There is no privileged channel between two agents that a user doesn't have.

So agents never reach into each other. One agent does not subscribe to another's hooks, read its session, borrow its tools, or wait on its boot. They boot independently and talk once they are up, the way two machines on a network do — you don't synchronise a computer's startup with its monitor's, you assume both come up and then use them.

This is a constraint, and it is the valuable kind. It means every agent stays independently installable, deployable, and replaceable, because none of them depends on being inside a particular arrangement of others. Fuzzy boundaries would buy convenience now and cost composability permanently.

The Boundary makes the case in full — worth reading before you design anything that spans agents.

Three ways to work with several

A script boots them. A global *.axon.ts file constructs the agents it needs, composes them in plain TypeScript, and exits. This is the scratch form — fast, local, no ceremony. Start here.

An agent orchestrates them. When a workflow is worth keeping — publishing, deploying, running on a schedule — it becomes an agent whose job is coordinating other agents. It gets identity, routes, hooks, and the registry for free, because it is an ordinary agent that happens to delegate.

They run as a fleet. Several agents live on your machine at once, each with its own address. They find each other through the running directory and talk over the protocol — a request, or a stimulus. No orchestrator required.

These are the same primitive at three scales. Everything is built on one call: Axon() boots an agent and hands you a complete handle to it. What you build on top of that — a pipeline, a state machine, a graph engine, a pool — is yours to write.

Where to go next

The Boundary — why agents only talk through stimuli, and what that rules out.

The Agent Handle — Axon(), and everything one instance can do.

Global Scripts — the *.axon.ts file and how it differs from a script inside an agent.

Composing a Fleet — booting several at once.

Resolving Agents — how "../barry" and "@axon/zeno" both become a running agent.

Lifecycle — boot, shutdown, and what survives a run.

Manager Agents — turning a workflow into something you can publish, deploy, and schedule.

The Running Fleet — what's live on the machine, and how agents address each other.

Debugging — tracing work across several agents.

Patterns — the shapes this work tends to take.

Next: The Boundary — the rule everything else follows from.