Skip to main content
Working examples are in the examples/ directory. Each example follows the standard aixyz app/ directory structure and can be run locally.

​
Running an Example

cd examples/agent-boilerplate
bun install
bun run dev
The agent starts at http://localhost:3000 with all protocol endpoints enabled.

​
Auto-Generated Server Examples

These agents use app/agent.ts + app/tools/ only. No app/server.ts — the server is auto-generated by the build pipeline.
ExampleDescription
agent-boilerplateUnit conversion agent (length, weight, temperature) with three tools
agent-price-oracleCoinGecko price feeds — token prices, new listings, top gainers/losers
agent-chainlinkChainlink price feeds on Ethereum mainnet
agent-job-hunterRemote job search via Jobicy API

​
Custom Server Examples

These use app/server.ts to manually wire up A2A, MCP, and x402.
ExampleDescription
agent-with-custom-serverMinimal custom server reference
agent-travelFlight search with Stripe payments integration
agent-byo-facilitatorBring-your-own x402 facilitator via app/accepts.ts

​
Testing Example

ExampleDescription
agent-with-testsTesting patterns with bun:test — deterministic and non-deterministic tests

​
Test Pattern

The agent-with-tests example demonstrates how to test agents: 
import { describe, expect, test } from "bun:test";
import { ToolLoopAgent } from "ai";
import { loadEnv } from "aixyz/test";
import agent, { accepts } from "./agent";

test("default export is a ToolLoopAgent", () => {
  expect(agent).toBeInstanceOf(ToolLoopAgent);
});

test("has convertTemperature tool registered", () => {
  expect(agent.tools).toHaveProperty("convertTemperature");
});

test("accepts config uses exact scheme", () => {
  expect(accepts.scheme).toBe("exact");
});

describe("non deterministic agent test", () => {
  loadEnv();

  test.skipIf(!process.env.OPENAI_API_KEY)("agent can convert temperature", async () => {
    const result = await agent.generate({
      prompt: "convert 100 degrees celsius to fahrenheit",
    });
    expect(result.text).toContain("212");
  });
});

​
Custom Server Pattern

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 * as lookup from "./tools/lookup";

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

useA2A(server, agent);

const mcp = new AixyzMCP(server);
await mcp.register("lookup", lookup);
await mcp.connect();

export default server;

Getting Started

Set up your own agent from scratch.

Agent Structure

Understand the app/ directory convention.