An aixyz agent is defined by a small set of files in a standard layout. Run aixyz dev and the framework auto-generates a server from them.
Directory Layout
requiredMust be providedoptional overrideProvide to override auto-generated behavior
Key Files
| File | Required | Description |
|---|
aixyz.config.ts | Yes | Agent metadata, payment config, and skills |
app/agent.ts | No* | Agent definition using Vercel AI SDK |
app/agents/*.ts | No | Sub-agent definitions, each gets its own endpoint |
app/tools/*.ts | No | Tool implementations, auto-discovered by the build |
app/server.ts | No | Custom server — overrides auto-generation entirely |
app/accepts.ts | No | Custom x402 facilitator for payment verification |
app/session.ts | No | Custom session store override for SessionPlugin |
app/erc-8004.ts | No | ERC-8004 identity registration and trust config |
app/agent.test.ts | No | Agent tests using bun:test |
app/icon.svg | No | Agent icon served as a static asset |
vercel.json | No | Vercel deployment configuration |
How It Works
The build pipeline scans the app/ directory to auto-generate a server:
- Reads
aixyz.config.ts for agent metadata and skills
- Imports
app/agent.ts for the main agent definition (if present)
- Discovers all
.ts files in app/agents/ for sub-agents (each gets its own A2A endpoint)
- Discovers all
.ts files in app/tools/ (excluding _ prefixed files)
- Registers
SessionPlugin (with custom store from app/session.ts if present)
- Wires up A2A (when agents exist), MCP (when tools exist), and x402 endpoints automatically
The result is a server exposing:
- A2A at
/agent and /.well-known/agent-card.json (main agent)
- A2A at
/{name}/agent and /{name}/.well-known/agent-card.json (per sub-agent in app/agents/)
- MCP at
/mcp
- x402 payment verification on gated endpoints
For full control, provide app/server.ts to override auto-generation. See the Custom Server template for an example. 
