Configure agents

An AXL agent is a directory of TOML files that the server reads at startup. One file registers that the agent exists; another gives it an identity, a model, and a list of what it may use. Everything else is optional and can be added later, one capability at a time.

Because an agent is configuration, you can review it in a pull request, diff two versions of its behavior, sign it, and roll it back - none of which is comfortable when an agent's personality is spread across application code.

The two files you need first

axl-config/agents.toml registers the agent directory with the server.
axl-config/agents/<name>/agent.toml describes what the agent is and what it can use.

The directory name is only an organization choice. The key inside agent.toml is the stable name you use to select the agent from the API, a channel, or a workflow.

Create your first agent walks through both files and ends with a working agent you can talk to.

Add behavior as you need it

Optional files sit beside agent.toml, each owning one concern. Keeping them separate is what stops an agent's configuration from becoming an unreadable wall of settings.

File	What it controls	Guide
`intent.toml`	Objective, constraints, autonomy level, stop rules	Create your first agent
`rag.toml`	Which document sets the agent can search	Configure search
`memory.toml`	Long-term recall and how much of it enters a prompt	Give an agent memory
`shield.toml`	Input and output safety behavior	Configure the shield
`compaction.toml`	How long conversations are compressed	Manage long conversations
`voice.toml`	Voice IDs and spoken-response instructions	Design a voice agent
`mcp.toml`	External MCP servers this agent may call	Connect an MCP server
`*.context.md`	Shared context inherited by agents below that directory	Manage long conversations

Which knowledge mechanism do I want?

Four different things put information in front of an agent. They are not interchangeable.

Mechanism	Holds	Scope	Reach for it when
Context files (`*.context.md`)	Stable instructions and background	Every run of every agent beneath that directory	The information is small, durable, and always relevant
Skills	Procedures plus reference material	Loaded during a run, only when relevant	The instructions are detailed but only sometimes needed
RAG	Your document corpus	Searched per question	The answer lives somewhere in a body of documents too large to paste
Memory	Facts about a person or a task	Follows a user or a session	The agent should recall something it learned from a previous conversation

A support agent typically uses all four: a context file for tone, a skill for the escalation procedure, RAG over the product documentation, and memory for what this customer already told it.