Install to Claude Code
npx -y skills add https://github.com/agentlyhq/aixyz --skill aixyzDescription
aixyz
SKILL.md
---
name: aixyz
description: >-
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.
license: MIT
metadata:
framework: aixyz
runtime: bun
---
# 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](https://aixyz.sh) — Getting Started guides, API reference, protocol docs, and templates
- **GitHub:** [github.com/AgentlyHQ/aixyz](https://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](https://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.)
- **MUST use `create-aixyz-app` to scaffold new agents** — see below
- **`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
> **CRITICAL: You MUST use `create-aixyz-app` to create new agent projects.**
> Do NOT manually create `aixyz.config.ts`, `package.json`, `app/agent.ts`, or any other project files by hand.
> Manually creating these files WILL result in broken builds, missing dependencies, and incorrect configurations.
> Always scaffold with `bunx create-aixyz-app` first, then modify the generated files.
```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](https://aixyz.sh/getting-started/payments) for full details.
### A2A capabilities
Export `capabilities` from `app/agent.ts` to configure the A2A agent card and executor behavior:
```ts
import type { Capabilities } from "aixyz/app/plugins/a2a";
export const capabilities: Capabilities = { streaming: false, pushNotifications: false };
```
Defaults to `{ streaming: true, pushNotifications: false }`. When `streaming: false`, the executor uses `generate()` instead of `stream()`.
### 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](https://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](https://aixyz.sh/getting-started/testing) for full details.
## Protocol Endpoints
Every deployed agent exposes these endpoints automatically:
| Endpoint | Protocol | Description |
| ------------------------------ | -------- | ---------------------------------------- |
| `/.well-known/agent-card.json` | A2A | Agent discovery card |
| `/agent` | A2A | JSON-RPC endpoint with x402 payment gate |
| `/mcp` | MCP | Tool sharing with MCP clients |
## Examples
The `examples/` directory in [github.com/AgentlyHQ/aixyz](https://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](https://aixyz.sh/templates/overview) 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](https://aixyz.sh), or browse examples in
[github.com/AgentlyHQ/aixyz/tree/main/examples](https://github.com/AgentlyHQ/aixyz/tree/main/examples)
for the most current information.