aixyz

Original：🇺🇸 English
Translated

Build, run, and deploy an AI agent using the aixyz framework. Use this skill when creating a new agent, adding tools, wiring up A2A/MCP protocols, configuring x402 micropayments, or deploying to Vercel.

3installs
Sourceagentlyhq/aixyz
Added on

NPX Install

npx skill4agent add agentlyhq/aixyz aixyz

Tags

Translated version includes tags in frontmatter
ai-agent-developmentaixyz-frameworkvercel-deploymentx402-micropaymentsagent-protocols

SKILL.md Content

View Translation Comparison →

Working with aixyz

Where to Find the Latest Information

The project evolves quickly. Always consult these sources for up-to-date details:
  • Docs site: aixyz.sh — Getting Started guides, API reference, protocol docs, and templates
  • GitHub: github.com/AgentlyHQ/aixyz — source, issues, and examples
  • CLI help: every command has 
    --help
    — run it to discover the current flags

Immutable Facts

These things will not change:
  • Runtime is always Bun — install with 
    bun
    , run with 
    bun
    , test with 
    bun test
  • Agent logic uses the Vercel AI SDK (
    ai
    package) — 
    ToolLoopAgent
    , 
    tool()
    , 
    stepCountIs()
    from 
    "ai"
    — check ai-sdk.dev for the current version
  • LLM providers use 
    @ai-sdk/*
    adapters     — 
    @ai-sdk/openai
    is the default but any Vercel AI SDK provider works (
    @ai-sdk/anthropic
    , 
    @ai-sdk/google
    , 
    @ai-sdk/amazon-bedrock
    , etc.)
  • create-aixyz-app
    is always available     for scaffolding — use 
    bunx create-aixyz-app --help
    to see all options
  • aixyz
    CLI is always available     — 
    aixyz dev
    for the dev/test loop, 
    aixyz build
    for building
  • Environment variables follow Next.js load order — 
    .env
    , 
    .env.local
    (don't commit), 
    .env.<NODE_ENV>
    , 
    .env.<NODE_ENV>.local

Getting Started

bash
# See all scaffolding options (TTY is disabled in AI/CI — every prompt has a flag)
bunx create-aixyz-app --help

# Scaffold with defaults
bunx create-aixyz-app my-agent --yes

# Dev/test loop
cd my-agent && bun run dev   # aixyz dev — hot reload at http://localhost:3000

# Build for deployment
bun run build                # aixyz build

Core Concepts

Project layout

Bare minimum to get started:
my-agent/
  aixyz.config.ts       # Agent identity, payment config, skills declaration
  app/
    agent.ts            # Root agent (ToolLoopAgent from "ai") — required
    tools/name.ts       # Tools (optional) — each file auto-registered; not exported directly
    agents/name.ts      # Sub-agents (optional) — each file → /name/agent endpoint
  package.json
  .env.local            # API keys — never commit
Full layout with optional files:
my-agent/
  aixyz.config.ts
  app/
    agent.ts
    agents/             # Sub-agents
    tools/              # Tools; _prefix files are ignored
    server.ts           # Custom server (overrides auto-generation)
    accepts.ts          # Custom x402 facilitator
    erc-8004.ts         # On-chain ERC-8004 identity
    icon.png            # Agent icon
  package.json
  vercel.json
  .env.local

Getting paid (x402)

Export 
accepts
from 
app/agent.ts
(gates 
/agent
) or from a tool file (gates it on 
/mcp
):
ts
import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = { scheme: "exact", price: "$0.005" };
No 
accepts
export → endpoint is not exposed. 
scheme: "free"
→ explicitly free. See aixyz.sh/getting-started/payments for full details.

On-chain identity (ERC-8004)

Register your agent on-chain with:
bash
aixyz erc-8004 register --help   # see all non-TTY flags
aixyz erc-8004 register --url https://my-agent.vercel.app --broadcast
See aixyz.sh/protocols/erc-8004 for full details.

Testing (optional)

Tests are optional but recommended for advanced users. Tests use Bun's built-in runner (
bun:test
). Write deterministic tests (no API calls) and use 
test.skipIf(!process.env.OPENAI_API_KEY)
for non-deterministic ones. Use 
fake()
from 
"aixyz/model"
for fully offline CI-safe tests.
bash
bun test                      # run all tests
bun test app/agent.test.ts    # run a specific file
See aixyz.sh/getting-started/testing for full details.

Protocol Endpoints

Every deployed agent exposes these endpoints automatically:
EndpointProtocolDescription
/.well-known/agent-card.json
A2AAgent discovery card
/agent
A2AJSON-RPC endpoint with x402 payment gate
/mcp
MCPTool sharing with MCP clients

Examples

The 
examples/
directory in github.com/AgentlyHQ/aixyz contains working agents for common patterns. When in doubt, find an example that matches what you need.
If you have GitHub access, clone the repo and explore 
examples/
directly:
bash
gh repo clone AgentlyHQ/aixyz
ls aixyz/examples/
Each example has an 
aixyz.config.ts
, 
app/agent.ts
, and 
app/tools/
you can learn from. The Templates tab on aixyz.sh documents each example.

Repo Structure (for exploration)

If you clone the repo, the key areas are:
packages/
  aixyz/              # Framework core (server, adapters, x402)
  aixyz-cli/          # CLI: dev, build, erc-8004 commands
  aixyz-config/       # Config loading (Zod-validated aixyz.config.ts)
  aixyz-erc-8004/     # ERC-8004 ABIs, addresses, schemas
  create-aixyz-app/   # Scaffolding CLI
docs/                 # Mintlify docs
examples/             # Working agent examples
Use 
--help
on any CLI command, read the docs at aixyz.sh, or browse examples in github.com/AgentlyHQ/aixyz/tree/main/examples for the most current information.