Install
AXON is available as a Python package and a Rust-based CLI.
# Install the Python package
pip install axon-dsl
# Verify installation
axon --version
No install required: You can try AXON in the browser playground — no Python, no API key, no setup.
Your First Agent
An AXON agent is defined in a .ax file. Here's the simplest possible agent:
/// hello.ax — A basic agent
agent Hello {
model: @mock/model
fn run(name: Str) -> Str {
"Hello, " + name
}
}
Run it with mock mode (no LLM API key needed):
axon run hello.ax --arg name=World
# Output: Hello, World
Compile & Run
AXON compiles to multiple targets from a single source file:
# Compile to TypeScript
axon compile hello.ax --target ts -o hello.ts
# Compile to Python MCP server
axon compile hello.ax --target mcp -o hello_server.py
# Compile to Go
axon compile hello.ax --target go -o hello.go
# Compile to Rust
axon compile hello.ax --target rust -o hello.rs
# Run with mock mode (no API key)
axon run hello.ax --mock --arg name=World
Syntax Overview
AXON uses a clean, typed syntax where agent primitives are first-class language constructs:
| Construct | Keyword | Description |
|---|---|---|
| Agent | agent | Define an AI agent with model, tools, memory |
| Tool | tool | Declare a callable tool with typed inputs/outputs |
| Flow | flow | Define a multi-step pipeline |
| Memory | memory | Declare episodic or semantic memory |
| RAG | rag | Declare retrieval-augmented generation pipeline |
| Spawn | spawn | Create a new agent instance |
| Pool | pool | Create a pool of parallel agents |
| Permission | @permission | Declare sandbox permissions |
Keywords
| Keyword | Context |
|---|---|
import | Module import |
type | Type alias declaration |
tool | Tool declaration |
prompt | Prompt template declaration |
rag | RAG knowledge base declaration |
flow | Flow orchestration declaration |
agent | Agent declaration |
fn | Method declaration inside agents |
stage | Stage declaration inside flows |
let | Variable binding |
for | Loop |
if | Conditional |
match | Pattern match |
act | Tool invocation |
think | Reasoning trace |
observe | Observation logging |
store | Memory write |
spawn | Agent instantiation |
await | Async wait |
pool | Worker pool creation |
Ok | Success result constructor |
Operators
| Operator | Purpose |
|---|---|
-> | Return type arrow, flow stage connection |
|> | Pipeline forward |
? | Error propagation |
@ | Annotation prefix, model reference |
:: | Namespace / enum access |
| | Union type separator |
Comments
| Syntax | Purpose |
|---|---|
// text | Line comment — ignored by parser |
/// text | Doc comment — attached to declaration as documentation |
String Interpolation
Strings support {variable} interpolation. Prefix with f for explicit interpolation:
"Hello, {name}!"
f"Found {len(results)} results for: {query}"
Agents
Agents are the core construct. They have a model, optional tools, memory, and functions:
agent ResearchBot {
model: @anthropic/claude-4
tools: [WebSearch, DocStore.retrieve]
memory: episodic
fn run(query: Str) -> Result<Report, AgentError> {
let results = await WebSearch.search(query)?
Ok(Report { topic: query, findings: results })
}
}
Tools
Tools are typed functions that agents can call. The compiler validates tool-agent compatibility:
tool WebSearch {
input: { query: Str, max_results: Int }
output: { results: [SearchResult] }
scope: "web:read"
}
Memory & RAG
Memory and RAG are first-class declarations, not imported libraries:
agent SupportAgent {
model: @openai/gpt-4o
memory: episodic
rag: DocStore {
source: "./docs/"
chunk_size: 512
embed: "text-embedding-3-small"
top_k: 5
}
}
Flows
Flows define multi-step pipelines with typed stages:
flow ResearchPipeline {
stage Plan: QueryPlanner.plan
stage Investigate: pool(size: 3, target: ResearchAgent)
stage Summarize: Summarizer.summarize
stage Verify: FactChecker.verify_all
}
Type System
AXON has a static type system. The compiler catches type errors before runtime.
Primitive Types
| Type | Description |
|---|---|
Str | String |
Int | Integer |
Float | Floating-point number |
Bool | Boolean |
() | Unit (no value) |
Composite Types
| Syntax | Description |
|---|---|
List<T> | List of type T |
Result<T, E> | Success (Ok(T)) or error (Err(E)) |
Option<T> | Present or absent |
Dict<K, V> | Key-value mapping |
{ field: T, ... } | Record type |
Union Types
Discriminated unions via |:
type Priority = "low" | "medium" | "high"
type Verdict = "confirmed" | "plausible" | "disputed" | "unverified"
Generic Type Parameters
type PagedList<T> = {
items: List<T>,
total: Int,
page: Int
}
Default Values
Parameters may have default values:
tool Search(query: Str, max_results: Int = 5) -> Result<List<Str>, ToolError> { ... }
Imports
Bring types, tools, or utilities from AXON standard modules into scope:
import { Chunk } from "axon:types"
import { now } from "axon:time"
import { WebSearch, WebFetch } from "axon:tools/web"
CLI Reference
AXON ships with a comprehensive CLI. All commands are available after pip install axon-dsl.
Core Commands
| Command | Description |
|---|---|
axon parse <file> | Parse .ax file and output IR JSON |
axon validate <file> | Validate .ax file and show diagnostics |
axon compile <file> --target <t> | Compile to ts, go, rust, mcp, or python |
axon run <file> --mock | Run agent in mock mode (no LLM API key) |
axon run <file> --arg k=v | Run agent with arguments |
axon repl [file] | Start interactive REPL |
axon eval "<expr>" | Evaluate an expression |
axon test <file> | Run tests for an .ax file |
axon format <file> | Format .ax file |
axon lsp | Start language server for IDE integration |
Agent Lifecycle
| Command | Description |
|---|---|
axon agent spawn <file> --name NAME | Spawn a named agent instance |
axon agent pause NAME | Pause a running agent |
axon agent resume NAME | Resume a paused agent |
axon agent terminate NAME | Terminate an agent |
axon agent status NAME | Check agent status |
axon agent list | List all running agents |
axon agent checkpoint NAME | Save agent state snapshot |
axon agent restore NAME --snapshot FILE | Restore agent from snapshot |
Supervision & Watch
| Command | Description |
|---|---|
axon supervisor start --name NAME --strategy ... | Start a supervisor with restart strategy (one_for_one, one_for_all, rest_for_one) |
axon supervisor stop NAME | Stop a supervisor |
axon supervisor status NAME | Check supervisor status |
axon watch start <file> --name NAME | Start a file watcher agent |
axon watch stop NAME | Stop a watcher |
Governance & Deployment
| Command | Description |
|---|---|
axon govern <file> --mesh-url URL | Submit agent to AgentOps Mesh for governance |
axon deploy --target docker | Deploy agent as Docker container |
axon ci-template | Generate CI/CD pipeline template |
axon serve-api --port PORT | Start AXON as a REST API server |
Secrets & Metrics
| Command | Description |
|---|---|
axon secret list | List configured secrets |
axon secret get KEY | Get a secret value |
axon secret set KEY VALUE | Set a secret |
axon secret delete KEY | Delete a secret |
axon metrics show | Show runtime metrics |
axon metrics export --output FILE | Export metrics to file |
Project & Health
| Command | Description |
|---|---|
axon quickstart [path] | Scaffold a new AXON project |
axon project-info [path] | Show project information |
axon health | Check installation health |
axon deps [path] | Show dependency tree |
axon hygiene [path] | Check project hygiene (gitignore, formatting) |
axon cheatsheet | Print quick reference cheatsheet |
Provider Configuration
Use --provider flag with axon run or axon agent spawn:
| Provider | Flag | Notes |
|---|---|---|
| Mock (default) | --provider mock | No API key needed |
| OpenAI | --provider openai | Requires OPENAI_API_KEY |
| Anthropic | --provider anthropic | Requires ANTHROPIC_API_KEY |
| Groq | --provider groq | Requires GROQ_API_KEY |
Database Configuration
Set AXON_DB_URL for persistent state:
# SQLite (default)
export AXON_DB_URL="sqlite:///path/to/axon.db"
# PostgreSQL
export AXON_DB_URL="postgresql://user:pass@localhost/axon"
Code Generation Targets
One .ax source file compiles to multiple targets:
| Target | Flag | Output |
|---|---|---|
| TypeScript | --target ts | ES module with typed interfaces |
| Python | --target python | Python module with type hints |
| Go | --target go | Go package with interfaces |
| Rust | --target rust | Rust module with traits |
| MCP Server | --target mcp | FastMCP Python server |
Try it in the browser: The playground supports all codegen targets — no install required.
AgentOps Mesh Integration
AXON agents can be submitted to AgentOps Mesh for governance review before production:
# Submit agent for governance review
axon govern research_bot.ax --mesh-url http://localhost:8000
# Or submit from the playground
# Click "Govern" tab → "Submit to Governance"
The governance workflow evaluates the agent through 9 gates: intake, suitability, data, evaluation, policy, approval, runtime, deployment, and launch readiness.
Examples
The playground includes 8 built-in examples:
| Example | What it demonstrates |
|---|---|
hello.ax | Basic agent definition |
hello_run.ax | Agent with tool calls |
permissions.ax | @permission sandbox declarations |
type_alias.ax | Custom type aliases |
flow.ax | Multi-stage flow pipeline |
rag.ax | RAG + prompt declarations |
customer_support.ax | Full production example |
More examples are in the GitHub repository.