Build an Agent with aixyz

When to Use

Use this skill when:

• Scaffolding a new AI agent project from scratch
• Adding a new tool to an existing agent
• Configuring x402 micropayments for an agent or tool
• Wiring up A2A and MCP protocol endpoints
• Deploying an agent to Vercel

Instructions

1. Scaffold a new project

bunx create-aixyz-app my-agent
cd my-agent

This creates the standard project layout:

my-agent/
  aixyz.config.ts     # Agent metadata and skills
  app/
    agent.ts          # Agent definition
    tools/            # One file per tool
    icon.png          # Agent icon (optional)
  package.json
  vercel.json

2. Configure the agent (

aixyz.config.ts

)

Every agent needs a config file at the project root. Declare identity, payment address, and skills:

import type { AixyzConfig } from "aixyz/config";

const config: AixyzConfig = {
  name: "My Agent",
  description: "A short description of what this agent does.",
  version: "0.1.0",
  x402: {
    payTo: process.env.X402_PAY_TO!,
    network: process.env.NODE_ENV === "production" ? "eip155:8453" : "eip155:84532",
  },
  skills: [
    {
      id: "my-skill",
      name: "My Skill",
      description: "What this skill does for callers.",
      tags: ["example"],
      examples: ["Do something with my skill"],
    },
  ],
};

export default config;

3. Payment:

accepts

export (

aixyz/accepts

)

Every agent and tool controls whether it requires payment by exporting

accepts

aixyz/accepts

import type { Accepts } from "aixyz/accepts";

// Require x402 micropayment
export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.001", // USD-denominated
  network: "eip155:8453", // optional — defaults to config.x402.network
  payTo: "0x...", // optional — defaults to config.x402.payTo
};

// Or make the endpoint free
export const accepts: Accepts = {
  scheme: "free",
};

Export

accepts

app/agent.ts

4. Write a tool (

app/tools/<name>.ts

)

Each file in

app/tools/

tool

import { tool } from "ai";
import { z } from "zod";
import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = { scheme: "exact", price: "$0.001" };

export default tool({
  description: "A short description of what this tool does.",
  inputSchema: z.object({
    query: z.string().describe("Input to the tool"),
  }),
  execute: async ({ query }) => {
    // your logic here
    return { result: query };
  },
});

Files prefixed with

_

_helpers.ts

5. Define the agent (

app/agent.ts

)

import { openai } from "@ai-sdk/openai";
import { stepCountIs, ToolLoopAgent } from "ai";
import type { Accepts } from "aixyz/accepts";
import myTool from "./tools/my-tool";

export const accepts: Accepts = { scheme: "exact", price: "$0.005" };

export default new ToolLoopAgent({
  model: openai("gpt-4o-mini"),
  instructions: "You are a helpful assistant.",
  tools: { myTool },
  stopWhen: stepCountIs(10),
});

6. Environment variables (

.env

files)

Environment variables are loaded in the same priority order as Next.js:

1. .env.<NODE_ENV>.local

   (highest priority; not loaded when

   NODE_ENV=test

   )

2. .env.local

3. .env.<NODE_ENV>

   (e.g.

   .env.production

   ,

   .env.development

   )

4. .env

Common variables:

X402_PAY_TO

X402_NETWORK

eip155:8453

X402_FACILITATOR_URL

https://x402.agently.to/facilitator

OPENAI_API_KEY

7. Agent icon (

app/icon.png

)

Place an icon file at

app/icon.png

.svg

.jpeg

.jpg

aixyz build

• Copied to the output as

  icon.png

• Converted to a

  favicon.ico

  (32×32) and placed in

  public/

No configuration needed — the build step auto-detects and processes the icon.

8. Custom facilitator (

app/accepts.ts

)

By default, aixyz uses

https://x402.agently.to/facilitator

app/accepts.ts

facilitator

import { HTTPFacilitatorClient } from "aixyz/accepts";

export const facilitator = new HTTPFacilitatorClient({
  url: process.env.X402_FACILITATOR_URL ?? "https://www.x402.org/facilitator",
});

9. Run the dev server

bun run dev      # aixyz dev — starts at http://localhost:3000 with hot reload
bun run dev -- -p 4000  # custom port

Endpoints served automatically:

/.well-known/agent-card.json

/agent

/mcp

10. (Optional) Custom server (

app/server.ts

)

For full control, create

app/server.ts

accepts

mcp.register

import { AixyzServer } from "aixyz/server";
import { useA2A } from "aixyz/server/adapters/a2a";
import { AixyzMCP } from "aixyz/server/adapters/mcp";
import * as agent from "./agent";
import myTool from "./tools/my-tool";

const server = new AixyzServer();
await server.initialize();
server.unstable_withIndexPage();

useA2A(server, agent);

const mcp = new AixyzMCP(server);
await mcp.register("myTool", {
  default: myTool,
  // accepts is optional — omit to expose without payment
  accepts: { scheme: "exact", price: "$0.001" },
});
await mcp.connect();

export default server;

11. Build and deploy to Vercel

bun run build    # aixyz build — outputs Vercel Build Output API v3 to .vercel/output/
vercel deploy

Examples

Working examples in the repo:

examples/agent-boilerplate

examples/agent-price-oracle

examples/agent-byo-facilitator

Common Edge Cases

• Missing

  x402.network

  — always provide

  x402.network

  ; it has no fallback.
• Missing

  x402.payTo

  — set

  X402_PAY_TO

  in

  .env.local

  or provide it directly in config.
• Tool file ignored — files prefixed with

  _

  are excluded; rename to remove the prefix.
• Agent card missing skills —

  skills

  defaults to

  []

  ; add at least one entry to be discoverable.
• Free endpoint — export

  accepts: { scheme: "free" }

  to expose an endpoint without payment.
• Port conflict in dev — use

  aixyz dev -p <port>

  to change the default port (3000).