Agent

An agent is a TypeScript project with a shape Axon knows how to read. You author four things: identity, tools, scripts, and policy. The loop, context assembly, tool dispatch, session persistence, stop conditions — you write none of it.

Boot it in the TUI on your laptop, run it headless in CI, deploy it as a live cloud service with a public URL and API key. The folder is the same in every case.

Create one

axon init my-agent
cd my-agent

That scaffolds the project, installs the framework, and generates its types — you can open src/boot.vue and start writing immediately.

Agents are the default project kind, so this is axon init with no noun in the middle. Every other kind names itself: axon module init, axon cognet init, axon bench init.

Here's what you get:

my-agent/
├── src/
│   └── boot.vue     # who the agent is
├── tests/           # boot test to prove it runs
├── axon.config.ts   # engine, modules, policy, environment
└── package.json

The rest of the shape is opt-in: src/tools/ when it needs to do something, src/scripts/ to orchestrate work, src/prompts/ for context it can load, server/ for HTTP routes, data/ for durable storage. Axon discovers whatever is there at boot, so folders you do not use simply do not exist. Modules are the exception — they are declared in axon.config.ts rather than dropped in a folder, which keeps an agent's dependencies readable in one place.

Run it

axon dev

The agent boots as a local HTTP server and watches your files. Edit boot.vue, a tool or a prompt and it hot-reloads in place — the session survives, so you are not restarting a conversation to see a change. The banner tells you what actually loaded, which is the fastest way to notice a tool that failed to register.

See axon dev.

The build journey

The Build section walks the authoring surface in the order you'll actually use it:

Identity — src/boot.vue is the standing system prompt. Edit it, save, and the running agent hot-reloads in ~40ms. This is where the agent gets its character.

Tools — export a function from src/tools/ and the agent can call it. Signatures and JSDoc become the model's documentation. No registration, no schemas.

Scripts — TypeScript files that orchestrate work: load context, call the agent, process results. One script runs identically from the terminal, the TUI, an HTTP route, or another script.

Routes & Hooks — server/api/ makes the agent addressable; hooks let it react when the outside world does something. This is how an agent becomes a service instead of a session.

Policy — declare what the agent may read, write, run, and reach. Enforced structurally on every call, before the function runs. Not a prompt hint.

Testing — boot the full runtime with a deterministic mock engine. Test tools, prompts, and hook flows — the parts with correct answers.

Capabilities you don't write

axon install @axon/github
axon install @axon/linear

Modules contribute typed tools, prompts, webhook routes, and boot-time setup. The integration work is already done. See Modules.

When something surprises you

Understand holds the mental models — what the runtime owns, how state and memory work, what the kernel enforces. Reach for it when you want to know why the agent behaved the way it did.

Agent Structure is the folder reference — every file, what it does, what Axon does with it.

Internals is how it actually works under the hood. None of it is required reading — that's the point of the platform.