create-aixyz-app 0.24.0 → 0.26.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +302 -0
- package/package.json +2 -2
- package/templates/default/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
# aixyz
|
|
2
|
+
|
|
3
|
+
Framework for bundling AI agents into deployable services with A2A, MCP, x402 payments, and ERC-8004 identity.
|
|
4
|
+
|
|
5
|
+
Write your agent logic. aixyz wires up the protocols, payments, and deployment.
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
Install [Bun](https://bun.sh) if you don't have it:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
curl -fsSL https://bun.sh/install | bash
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Quick Start
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
bunx create-aixyz-app my-agent
|
|
19
|
+
cd my-agent
|
|
20
|
+
bun install
|
|
21
|
+
bun run dev
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Your agent is running. It exposes:
|
|
25
|
+
|
|
26
|
+
| Endpoint | Protocol | What it does |
|
|
27
|
+
| ------------------------------ | -------- | ------------------------------------ |
|
|
28
|
+
| `/.well-known/agent-card.json` | A2A | Agent discovery card |
|
|
29
|
+
| `/agent` | A2A | JSON-RPC endpoint, x402 payment gate |
|
|
30
|
+
| `/mcp` | MCP | Tool sharing with MCP clients |
|
|
31
|
+
|
|
32
|
+
## How It Works
|
|
33
|
+
|
|
34
|
+
An aixyz agent has three parts: a config, an agent, and tools.
|
|
35
|
+
|
|
36
|
+
### 1. Config
|
|
37
|
+
|
|
38
|
+
`aixyz.config.ts` declares your agent's identity, payment address, and skills:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import type { AixyzConfig } from "aixyz/config";
|
|
42
|
+
|
|
43
|
+
const config: AixyzConfig = {
|
|
44
|
+
name: "Weather Agent",
|
|
45
|
+
description: "Get current weather for any location worldwide.",
|
|
46
|
+
version: "0.1.0",
|
|
47
|
+
x402: {
|
|
48
|
+
payTo: "0x...",
|
|
49
|
+
network: "eip155:8453", // Base mainnet
|
|
50
|
+
},
|
|
51
|
+
skills: [
|
|
52
|
+
{
|
|
53
|
+
id: "get-weather",
|
|
54
|
+
name: "Get Weather",
|
|
55
|
+
description: "Get current weather conditions for any city or location",
|
|
56
|
+
tags: ["weather"],
|
|
57
|
+
examples: ["What's the weather in Tokyo?"],
|
|
58
|
+
},
|
|
59
|
+
],
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
export default config;
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### 2. Agent
|
|
66
|
+
|
|
67
|
+
`app/agent.ts` defines your agent, its payment price, and A2A capabilities:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
import { openai } from "@ai-sdk/openai";
|
|
71
|
+
import { stepCountIs, ToolLoopAgent } from "ai";
|
|
72
|
+
import type { Accepts } from "aixyz/accepts";
|
|
73
|
+
import type { Capabilities } from "aixyz/app/plugins/a2a";
|
|
74
|
+
import weather from "./tools/weather";
|
|
75
|
+
|
|
76
|
+
export const accepts: Accepts = {
|
|
77
|
+
scheme: "exact",
|
|
78
|
+
price: "$0.005",
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
export const capabilities: Capabilities = {
|
|
82
|
+
streaming: true, // default: true — set to false to use generate() instead of stream()
|
|
83
|
+
pushNotifications: false, // default: false
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
export default new ToolLoopAgent({
|
|
87
|
+
model: openai("gpt-4o-mini"),
|
|
88
|
+
instructions: "You are a helpful weather assistant.",
|
|
89
|
+
tools: { weather },
|
|
90
|
+
stopWhen: stepCountIs(10),
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 3. Tools
|
|
95
|
+
|
|
96
|
+
Each file in `app/tools/` exports a Vercel AI SDK `tool` and an optional `accepts` for MCP payment gating:
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
import { tool } from "ai";
|
|
100
|
+
import { z } from "zod";
|
|
101
|
+
import type { Accepts } from "aixyz/accepts";
|
|
102
|
+
|
|
103
|
+
export const accepts: Accepts = {
|
|
104
|
+
scheme: "exact",
|
|
105
|
+
price: "$0.0001",
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
export default tool({
|
|
109
|
+
description: "Get current weather conditions for a city.",
|
|
110
|
+
inputSchema: z.object({
|
|
111
|
+
location: z.string().describe("City name"),
|
|
112
|
+
}),
|
|
113
|
+
execute: async ({ location }) => {
|
|
114
|
+
// your logic here
|
|
115
|
+
},
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
That's it. Run `bun run dev` and aixyz auto-generates the server, wires up A2A + MCP + x402, and starts serving.
|
|
120
|
+
|
|
121
|
+
## Custom Server
|
|
122
|
+
|
|
123
|
+
For full control, create `app/server.ts` instead. This takes precedence over auto-generation:
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
import { AixyzApp } from "aixyz/app";
|
|
127
|
+
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
|
|
128
|
+
import { A2APlugin } from "aixyz/app/plugins/a2a";
|
|
129
|
+
import { MCPPlugin } from "aixyz/app/plugins/mcp";
|
|
130
|
+
|
|
131
|
+
import * as agent from "./agent";
|
|
132
|
+
import lookup from "./tools/lookup";
|
|
133
|
+
|
|
134
|
+
const server = new AixyzApp();
|
|
135
|
+
|
|
136
|
+
// Index page: human-readable agent info
|
|
137
|
+
await server.withPlugin(new IndexPagePlugin());
|
|
138
|
+
|
|
139
|
+
// A2A: agent discovery + JSON-RPC endpoint
|
|
140
|
+
await server.withPlugin(new A2APlugin(agent));
|
|
141
|
+
|
|
142
|
+
// MCP: expose tools to MCP clients
|
|
143
|
+
await server.withPlugin(
|
|
144
|
+
new MCPPlugin([
|
|
145
|
+
{
|
|
146
|
+
name: "lookup",
|
|
147
|
+
exports: {
|
|
148
|
+
default: lookup,
|
|
149
|
+
accepts: { scheme: "exact", price: "$0.001" },
|
|
150
|
+
},
|
|
151
|
+
},
|
|
152
|
+
]),
|
|
153
|
+
);
|
|
154
|
+
|
|
155
|
+
await server.initialize();
|
|
156
|
+
|
|
157
|
+
export default server;
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Configuration
|
|
161
|
+
|
|
162
|
+
| Field | Type | Required | Description |
|
|
163
|
+
| -------------- | -------------- | -------- | -------------------------------------------------- |
|
|
164
|
+
| `name` | `string` | Yes | Agent display name |
|
|
165
|
+
| `description` | `string` | Yes | What the agent does |
|
|
166
|
+
| `version` | `string` | Yes | Semver version |
|
|
167
|
+
| `url` | `string` | No | Agent base URL. Auto-detected on Vercel |
|
|
168
|
+
| `x402.payTo` | `string` | Yes | EVM address to receive payments |
|
|
169
|
+
| `x402.network` | `string` | Yes | Payment network (`eip155:8453` for Base) |
|
|
170
|
+
| `skills` | `AgentSkill[]` | No | Skills your agent exposes (used in A2A agent card) |
|
|
171
|
+
|
|
172
|
+
Environment variables are loaded in the same order as Next.js: `.env`, `.env.local`, `.env.$(NODE_ENV)`,
|
|
173
|
+
`.env.$(NODE_ENV).local`.
|
|
174
|
+
|
|
175
|
+
### Payment (Accepts)
|
|
176
|
+
|
|
177
|
+
Each agent and tool declares an `accepts` export to control payment:
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
// Require x402 payment
|
|
181
|
+
export const accepts: Accepts = {
|
|
182
|
+
scheme: "exact",
|
|
183
|
+
price: "$0.005", // USD-denominated
|
|
184
|
+
network: "eip155:8453", // optional, defaults to config.x402.network
|
|
185
|
+
payTo: "0x...", // optional, defaults to config.x402.payTo
|
|
186
|
+
};
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Agents and tools without an `accepts` export are not registered.
|
|
190
|
+
|
|
191
|
+
## CLI
|
|
192
|
+
|
|
193
|
+
### `aixyz dev`
|
|
194
|
+
|
|
195
|
+
Starts a local dev server with hot reload. Watches `app/` and `aixyz.config.ts` for changes.
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
aixyz dev # default port 3000
|
|
199
|
+
aixyz dev -p 4000 # custom port
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### `aixyz build`
|
|
203
|
+
|
|
204
|
+
Bundles your agent for deployment. Default output goes to `.aixyz/output/server.js`.
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
aixyz build # standalone (default), outputs to .aixyz/output/server.js
|
|
208
|
+
bun .aixyz/output/server.js # run the standalone build
|
|
209
|
+
|
|
210
|
+
aixyz build --output vercel # Vercel Build Output API v3, outputs to .vercel/output/
|
|
211
|
+
vercel deploy # deploy the Vercel build
|
|
212
|
+
|
|
213
|
+
aixyz build --output executable # self-contained binary, no Bun runtime required
|
|
214
|
+
./.aixyz/output/server # run directly
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### `aixyz erc-8004 register`
|
|
218
|
+
|
|
219
|
+
Register your agent's on-chain identity (ERC-8004). Creates
|
|
220
|
+
`app/erc-8004.ts` if it doesn't exist, asks for your deployment URL, and writes the registration back to the file after a successful on-chain transaction.
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
aixyz erc-8004 register --url "https://my-agent.vercel.app" --chain base-sepolia --broadcast
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### `aixyz erc-8004 update`
|
|
227
|
+
|
|
228
|
+
Update the metadata URI of a registered agent. Reads registrations from
|
|
229
|
+
`app/erc-8004.ts` and lets you select which one to update.
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
aixyz erc-8004 update --url "https://new-domain.example.com" --broadcast
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
## Protocols
|
|
236
|
+
|
|
237
|
+
**A2A (Agent-to-Agent)** — Generates an agent card at `/.well-known/agent-card.json` and a JSON-RPC endpoint at
|
|
238
|
+
`/agent`. Protocol version 0.3.0. Other agents discover yours and send tasks via JSON-RPC.
|
|
239
|
+
|
|
240
|
+
**MCP (Model Context Protocol)** — Exposes your tools at `/mcp` using
|
|
241
|
+
`WebStandardStreamableHTTPServerTransport`. Any MCP client (Claude Desktop, VS Code, Cursor) can connect and call your tools.
|
|
242
|
+
|
|
243
|
+
**x402** — HTTP 402 micropayments. Clients pay per-request with an
|
|
244
|
+
`X-Payment` header containing cryptographic payment proof. No custodial wallets, no subscriptions. Payments are verified on-chain via a facilitator.
|
|
245
|
+
|
|
246
|
+
**ERC-8004** — On-chain agent identity. Register your agent on Ethereum, Base, Polygon, Scroll, Monad, BSC, or Gnosis so other agents and contracts can reference it.
|
|
247
|
+
|
|
248
|
+
## Agent File Structure
|
|
249
|
+
|
|
250
|
+
```
|
|
251
|
+
my-agent/
|
|
252
|
+
aixyz.config.ts # Agent config (required)
|
|
253
|
+
app/
|
|
254
|
+
agent.ts # Agent definition (required if no server.ts)
|
|
255
|
+
server.ts # Custom server (optional, overrides auto-generation)
|
|
256
|
+
erc-8004.ts # ERC-8004 identity registration (optional)
|
|
257
|
+
tools/
|
|
258
|
+
weather.ts # Tool exports (files starting with _ are ignored)
|
|
259
|
+
icon.png # Agent icon (served as static asset)
|
|
260
|
+
public/ # Static assets
|
|
261
|
+
vercel.json # Vercel deployment config
|
|
262
|
+
.env.local # Local environment variables
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
## Environment Variables
|
|
266
|
+
|
|
267
|
+
| Variable | Description |
|
|
268
|
+
| ---------------------- | ------------------------------------------------------------------------ |
|
|
269
|
+
| `X402_PAY_TO` | Default payment recipient address |
|
|
270
|
+
| `X402_NETWORK` | Default payment network (e.g. `eip155:8453`) |
|
|
271
|
+
| `X402_FACILITATOR_URL` | Custom facilitator (default: `https://x402.use-agently.com/facilitator`) |
|
|
272
|
+
| `CDP_API_KEY_ID` | Coinbase CDP API key ID (uses Coinbase facilitator) |
|
|
273
|
+
| `CDP_API_KEY_SECRET` | Coinbase CDP API key secret |
|
|
274
|
+
| `STRIPE_SECRET_KEY` | Enable experimental Stripe payment adapter |
|
|
275
|
+
| `OPENAI_API_KEY` | OpenAI API key (for agents using OpenAI models) |
|
|
276
|
+
|
|
277
|
+
## Examples
|
|
278
|
+
|
|
279
|
+
| Example | Description |
|
|
280
|
+
| ------------------------- | ----------------------------------------------- |
|
|
281
|
+
| `boilerplate` | Minimal starter (auto-generated server) |
|
|
282
|
+
| `chainlink` | Chainlink data feeds with custom server |
|
|
283
|
+
| `flight-search` | Flight search with Stripe payments |
|
|
284
|
+
| `local-llm` | Local LLM via Docker (no external API) |
|
|
285
|
+
| `with-custom-facilitator` | Bring-your-own x402 facilitator |
|
|
286
|
+
| `with-custom-server` | Custom server setup |
|
|
287
|
+
| `with-express` | Express middleware integration |
|
|
288
|
+
| `sub-agents` | Multiple A2A endpoints from one deployment |
|
|
289
|
+
| `with-tests` | Agent with test examples |
|
|
290
|
+
| `fake-llm` | Fully deterministic testing with `fake()` model |
|
|
291
|
+
|
|
292
|
+
## Contributing
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
bun install
|
|
296
|
+
bun run build
|
|
297
|
+
bun run format
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
## License
|
|
301
|
+
|
|
302
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-aixyz-app",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.26.0",
|
|
4
4
|
"description": "Payment-native SDK for AI Agent",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"@types/bun": "^1.3.9",
|
|
35
35
|
"@types/node": "^22",
|
|
36
36
|
"ai": "^6",
|
|
37
|
-
"aixyz": "0.
|
|
37
|
+
"aixyz": "0.26.0",
|
|
38
38
|
"typescript": "^5",
|
|
39
39
|
"zod": "^4"
|
|
40
40
|
}
|