Project Structure

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

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

* If omitted, the build skips A2A endpoints and only serves tools via MCP.

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.