Skip to content

README.md

Latest commit

 

History

History
182 lines (137 loc) · 6.53 KB

README.md

File metadata and controls

182 lines (137 loc) · 6.53 KB

aixyz

Nextjs-like framework for bundling AI agents into deployable services with A2A, MCP, x402 payments, and ERC-8004 identity.

Documentation · Quick Start · How It Works · Examples · CLI · Protocols

Version MIT License

Documentation

Full documentation, API reference, and guides at aixyz.sh.

Quick Start

bunx create-aixyz-app my-agent
cd my-agent
bun run dev

Your agent is running. It exposes:

Endpoint Protocol What it does
/.well-known/agent-card.json A2A Agent discovery card
/agent A2A JSON-RPC endpoint, x402 payment gate
/mcp MCP Tool sharing with MCP clients

How It Works

An aixyz agent has three parts: a config, an agent, and tools.

1. Config

aixyz.config.ts declares your agent's identity and payment address:

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

const config: AixyzConfig = {
  name: "Weather Agent",
  description: "Get current weather for any location worldwide.",
  version: "0.1.0",
  x402: {
    payTo: "0x...",
    network: "eip155:8453", // Base mainnet
  },
};

export default config;

2. Agent

app/agent.ts defines your agent and its payment price:

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),
});

3. Tools

Each file in app/tools/ exports a Vercel AI SDK tool and an optional accepts for MCP payment gating:

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 logic here
  },
});

That's it. Run bun run dev and aixyz auto-generates the server, wires up A2A + MCP + x402, and starts serving.

Examples

Example Description
boilerplate Minimal starter (auto-generated server)
chainlink Chainlink data feeds with custom server
flight-search Flight search with Stripe payments
local-llm Local LLM via Docker (no external API)
with-custom-facilitator Bring-your-own x402 facilitator
with-custom-server Custom server setup
with-express Express middleware integration
sub-agents Multiple A2A endpoints from one deployment
with-tests Agent with test examples
fake-llm Fully deterministic testing with fake() model

CLI

bun add aixyz            # CLI included with the aixyz package
bunx aixyz --help        # or run without installing
aixyz dev                # Dev server with hot reload
aixyz build              # Bundle for deployment (standalone, Vercel, or executable)
aixyz erc-8004 register  # Register on-chain agent identity
aixyz erc-8004 update    # Update agent metadata URI

See the CLI reference for all options.

Protocols

A2A (Agent-to-Agent) — Agent discovery card + JSON-RPC endpoint. Other agents find yours and send tasks.

MCP (Model Context Protocol) — Expose tools to any MCP client (Claude Desktop, VS Code, Cursor).

x402 — HTTP 402 micropayments. Per-request payment with cryptographic proof, verified on-chain.

ERC-8004 — On-chain agent identity on Ethereum, Base, Polygon, Scroll, Monad, BSC, or Gnosis.

Contributing

bun install          # install dependencies
bun run build        # build all packages
bun run test         # run tests
bun run format       # format with Prettier

PRs welcome. Please ensure bun run build && bun run test && bun run format pass before submitting.

License

MIT