Agent and Tools

Agent (`app/agent.ts`)

Your agent is defined using Vercel AI SDK (ai@^6). The file exports a default ToolLoopAgent and an optional accepts for payment pricing.

app/agent.ts

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

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

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

`ToolLoopAgent`

The ToolLoopAgent from Vercel AI SDK handles multi-step tool execution loops automatically. It:

Takes a model, instructions, and a set of tools
Executes tool calls in a loop until the stop condition is met
Returns the final response

`accepts` Export

The optional accepts named export controls x402 payment gating on the A2A /agent endpoint:

Agents with accepts are registered on payment-gated A2A endpoints
Agents without accepts are not registered

You can also pass an array to accept payment on multiple networks:

export const accepts: Accepts = [
  { scheme: "exact", price: "$0.005", network: "eip155:8453" },
  { scheme: "exact", price: "$0.005", network: "eip155:84532" },
];

`capabilities` Export

The optional capabilities named export configures the A2A agent card’s capabilities and controls how the executor runs your agent:

app/agent.ts

import type { Capabilities } from "aixyz/app/plugins/a2a";

export const capabilities: Capabilities = {
  streaming: false,
  pushNotifications: false,
};

streaming (default: true) — When false, the executor uses generate() instead of stream(), returning the full response as a single artifact
pushNotifications (default: false) — Advertises push notification support in the agent card
stateTransitionHistory — Advertises state transition history support in the agent card

If omitted, the agent defaults to { streaming: true, pushNotifications: false }. See the agent.ts reference for details.

Sub-Agents (`app/agents/*.ts`)

Place additional agent files in app/agents/ to expose multiple A2A endpoints from a single deployment. Each file follows the same format as app/agent.ts and is automatically registered on its own path.

app/agents/research.ts

// → /research/agent
import { openai } from "@ai-sdk/openai";
import { stepCountIs, ToolLoopAgent } from "ai";
import type { Accepts } from "aixyz/accepts";

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

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

With the layout below, the build auto-generates three independent A2A endpoints:

Files starting with _ (e.g., _helpers.ts) are ignored by the build pipeline. Use this convention for shared utilities.

Tools (`app/tools/*.ts`)

Each .ts file in app/tools/ exports a Vercel AI SDK tool and an optional accepts for MCP payment gating. Tools are automatically discovered and registered on both A2A and MCP endpoints.

app/tools/weather.ts

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

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

export default tool({
  description: "Get current weather conditions for a city.",
  inputSchema: z.object({
    location: z.string().describe("City name"),
  }),
  execute: async ({ location }) => {
    // your implementation
  },
});

Tool Discovery

The build pipeline automatically discovers all .ts files in app/tools/:

Each file is registered as an MCP tool
Tools with accepts are payment-gated on the /mcp endpoint
Tools without accepts are not registered on MCP

Files starting with _ (e.g., _helpers.ts) are ignored by the build pipeline. Use this convention for shared utilities.

Per-Tool Pricing

Each tool can declare its own price, enabling granular pricing across your agent:

// app/tools/basic-search.ts — free tool (no accepts)
export default tool({ ... });

// app/tools/premium-search.ts — paid tool
export const accepts: Accepts = { scheme: "exact", price: "$0.001" };
export default tool({ ... });

Tools also support multiple payment options via an array of accepts entries.

Custom Server

For full control over endpoint registration and middleware, create app/server.ts. This overrides auto-generation entirely:

app/server.ts

import { AixyzApp } from "aixyz/app";
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
import { A2APlugin } from "aixyz/app/plugins/a2a";
import { MCPPlugin } from "aixyz/app/plugins/mcp";

import * as agent from "./agent";
import * as lookup from "./tools/lookup";

const server = new AixyzApp();

await server.withPlugin(new IndexPagePlugin());
await server.withPlugin(new A2APlugin([{ exports: agent }]));
await server.withPlugin(
  new MCPPlugin([
    {
      name: "lookup",
      exports: {
        default: lookup.default,
        accepts: { scheme: "exact", price: "$0.001" },
      },
    },
  ]),
);

await server.initialize();

export default server;

See the Custom Server template for a working example.

​Agent (app/agent.ts)

​ToolLoopAgent

​accepts Export

​capabilities Export

​Sub-Agents (app/agents/*.ts)

​Tools (app/tools/*.ts)

​Tool Discovery

​Per-Tool Pricing

​Custom Server

Agent (`app/agent.ts`)

`ToolLoopAgent`

`accepts` Export

`capabilities` Export

Sub-Agents (`app/agents/*.ts`)

Tools (`app/tools/*.ts`)

Tool Discovery

Per-Tool Pricing

Custom Server