Skip to main content
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

my-agent/
  aixyz.config.ts       # Agent identity, payment config, and skills
  app/
    agent.ts            # Agent definition (required if no server.ts)
    agent.test.ts       # Agent tests (optional)
    server.ts           # Custom server (optional, overrides auto-generation)
    accepts.ts          # Custom x402 facilitator (optional)
    erc-8004.ts         # ERC-8004 identity registration (optional)
    tools/
      weather.ts        # Tool implementations
      search.ts
      _helpers.ts       # Ignored — files starting with _ are skipped
    icon.png            # Agent icon (served as a static asset)
  package.json
  tsconfig.json
  vercel.json           # Vercel deployment config
  .env.local            # API keys and environment variables

​
Key Files

FileRequiredDescription
aixyz.config.tsYesAgent metadata, payment config, and skills
app/agent.tsYes*Agent definition using Vercel AI SDK
app/tools/*.tsNoTool implementations, auto-discovered by the build
app/server.tsNoCustom server — overrides auto-generation entirely
app/accepts.tsNoCustom x402 facilitator for payment verification
app/erc-8004.tsNoERC-8004 identity registration and trust config
app/agent.test.tsNoAgent tests using bun:test
app/icon.pngNoAgent icon served as a static asset
vercel.jsonNoVercel deployment configuration
* Required if no app/server.ts is provided.

​
How It Works

The build pipeline scans the app/ directory to auto-generate a server:
  1. Reads aixyz.config.ts for agent metadata and skills
  2. Imports app/agent.ts for the agent definition
  3. Discovers all .ts files in app/tools/ (excluding _ prefixed files)
  4. Wires up A2A, MCP, and x402 endpoints automatically
The result is a server exposing:
  • A2A at /agent and /.well-known/agent-card.json
  • 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.