aixyz

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Working with aixyz

使用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

本项目迭代速度较快。请始终通过以下渠道获取最新详情：

文档站点： aixyz.sh — 入门指南、API参考、协议文档及模板
GitHub： github.com/AgentlyHQ/aixyz — 源码、问题反馈及示例
CLI帮助： 所有命令均支持
```
--help
```
参数 — 执行该参数可查看当前可用的标志

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
```

以下规则不会发生变更：

运行时始终为Bun — 使用
```
bun
```
安装、运行及测试（
```
bun test
```
）
Agent逻辑基于Vercel AI SDK（
```
ai
```
包） — 从
```
"ai"
```
中引入
```
ToolLoopAgent
```
、
```
tool()
```
、
```
stepCountIs()
```
— 可访问ai-sdk.dev查看当前版本
大模型提供商使用
@ai-sdk/*
适配器 — 默认使用
```
@ai-sdk/openai
```
，但所有Vercel AI SDK支持的提供商均可兼容（
```
@ai-sdk/anthropic
```
、
```
@ai-sdk/google
```
、
```
@ai-sdk/amazon-bedrock
```
等）
create-aixyz-app
始终用于项目初始化 — 执行
```
bunx create-aixyz-app --help
```
查看所有选项
aixyz
CLI始终可用 — 使用
```
aixyz dev
```
进入开发/测试循环，
```
aixyz build
```
用于构建项目
环境变量遵循Next.js加载顺序 —
```
.env
```
、
```
.env.local
```
（请勿提交至版本库）、
```
.env.<NODE_ENV>
```
、
```
.env.<NODE_ENV>.local
```

Getting Started

快速开始

bash

undefined

bash

undefined

See all scaffolding options (TTY is disabled in AI/CI — every prompt has a flag)

查看所有项目初始化选项（AI/CI环境下TTY已禁用 — 所有交互均有对应标志）

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

cd my-agent && bun run dev # aixyz dev — 在http://localhost:3000实现热重载

Build for deployment

构建用于部署的版本

bun run build # aixyz build

undefined

bun run build # aixyz build

undefined

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

最简启动结构：

my-agent/
  aixyz.config.ts       # Agent身份信息、支付配置、技能声明
  app/
    agent.ts            # 根Agent（来自"ai"的ToolLoopAgent） — 必填
    tools/name.ts       # 工具（可选） — 每个文件自动注册；无需直接导出
    agents/name.ts      # 子Agent（可选） — 每个文件对应/name/agent端点
  package.json
  .env.local            # API密钥 — 切勿提交至版本库

包含可选文件的完整结构：

my-agent/
  aixyz.config.ts
  app/
    agent.ts
    agents/             # 子Agent目录
    tools/              # 工具目录；前缀为_的文件会被忽略
    server.ts           # 自定义服务器（覆盖自动生成的服务器）
    accepts.ts          # 自定义x402支付验证器
    erc-8004.ts         # 链上ERC-8004身份信息
    icon.png            # Agent图标
  package.json
  vercel.json
  .env.local

Getting paid (x402)

收款配置（x402）

Export

accepts

from

app/agent.ts

(gates

/agent

) or from a tool file (gates it on

/mcp

import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = { scheme: "exact", price: "$0.005" };

accepts

export → endpoint is not exposed.

scheme: "free"

→ explicitly free. See aixyz.sh/getting-started/payments for full details.

在

app/agent.ts

中导出

accepts

（用于限制

/agent

端点），或在工具文件中导出（用于限制

/mcp

端点）：

import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = { scheme: "exact", price: "$0.005" };

未导出

accepts

→ 端点不会对外暴露。

scheme: "free"

→ 明确设置为免费。详情请查看aixyz.sh/getting-started/payments。

On-chain identity (ERC-8004)

链上身份（ERC-8004）

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.

通过以下命令在链上注册你的Agent：

bash

aixyz erc-8004 register --help   # 查看所有非TTY交互标志
aixyz erc-8004 register --url https://my-agent.vercel.app --broadcast

详情请查看aixyz.sh/protocols/erc-8004。

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.

测试为可选操作，但推荐进阶用户使用。测试基于Bun内置的测试运行器（

bun:test

）。编写确定性测试（无API调用），并对非确定性测试使用

test.skipIf(!process.env.OPENAI_API_KEY)

。使用

"aixyz/model"

中的

fake()

实现完全离线且CI安全的测试。

bash

bun test                      # 运行所有测试
bun test app/agent.test.ts    # 运行指定文件的测试

详情请查看aixyz.sh/getting-started/testing。

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

每个已部署的Agent会自动暴露以下端点：

端点	协议	描述
`/.well-known/agent-card.json`	A2A	Agent发现卡片
`/agent`	A2A	带有x402支付验证的JSON-RPC端点
`/mcp`	MCP	为MCP客户端提供工具共享服务

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.

github.com/AgentlyHQ/aixyz的

examples/

目录包含了适用于常见场景的可用Agent。如有疑问，可寻找与你的需求匹配的示例。

若你拥有GitHub访问权限，可克隆仓库并直接浏览

examples/

bash

gh repo clone AgentlyHQ/aixyz
ls aixyz/examples/

每个示例均包含

aixyz.config.ts

、

app/agent.ts

及

app/tools/

目录，可供你参考学习。 aixyz.sh的模板页面对每个示例都有详细说明。

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.

若你克隆了仓库，核心目录结构如下：

packages/
  aixyz/              # 框架核心（服务器、适配器、x402模块）
  aixyz-cli/          # CLI工具：dev、build、erc-8004等命令
  aixyz-config/       # 配置加载模块（基于Zod验证aixyz.config.ts）
  aixyz-erc-8004/     # ERC-8004的ABI、地址及 schema
  create-aixyz-app/   # 项目初始化CLI工具
docs/                 # Mintlify文档站点
examples/             # 可用的Agent示例

可对任意CLI命令使用

--help

参数，访问aixyz.sh查看文档，或浏览github.com/AgentlyHQ/aixyz/tree/main/examples中的示例以获取最新信息。