aixyz

使用 aixyz

获取最新信息

项目迭代很快。请始终查阅以下来源，获取最新信息：

• 文档站点： aixyz.sh — 入门指南、API 参考、协议文档和模板
• GitHub： github.com/AgentlyHQ/aixyz — 源码、问题和示例
• CLI 帮助： 每条命令都有 --help — 运行它以了解当前标志

不变的事实

以下内容不会改变：

• 运行时始终是 Bun — 使用 bun 安装、使用 bun 运行、使用 bun test 测试
• Agent 逻辑使用 Vercel AI SDK（ai 包）— ToolLoopAgent、tool()、stepCountIs() 来自 "ai" — 请查看 ai-sdk.dev 了解当前版本
• 大模型提供商使用 @ai-sdk/* 适配器 — 默认使用 @ai-sdk/openai，但任何 Vercel AI SDK 提供商均可使用（@ai-sdk/anthropic、@ai-sdk/google、@ai-sdk/amazon-bedrock 等）
• 必须使用 create-aixyz-app 搭建新 Agent — 见下文
• 始终可用 aixyz CLI — 使用 aixyz dev 进行开发/测试循环，使用 aixyz build 进行构建
• 环境变量遵循 Next.js 加载顺序 — .env、.env.local（不要提交）、.env.<NODE_ENV>、.env.<NODE_ENV>.local

入门

重要：必须使用 create-aixyz-app 创建新的 Agent 项目。 请勿手动创建 aixyz.config.ts、package.json、app/agent.ts 或任何其他项目文件。 手动创建这些文件会导致构建失败、缺少依赖项以及配置错误。 请始终先使用 bunx create-aixyz-app 搭建项目，然后再修改生成的文件。

# 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

核心概念

项目布局

入门所需的最精简结构：

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

包含可选文件的完整布局：

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

收款（x402）

从 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。

A2A 功能

从 app/agent.ts 导出 capabilities，以配置 A2A Agent 卡片和执行器行为：

import type { Capabilities } from "aixyz/app/plugins/a2a";

export const capabilities: Capabilities = { streaming: false, pushNotifications: false };

默认值为 { streaming: true, pushNotifications: false }。当 streaming: false 时，执行器会使用 generate() 而不是 stream()。

链上身份（ERC-8004）

使用以下方式在链上注册你的 Agent：

aixyz erc-8004 register --help   # see all non-TTY flags
aixyz erc-8004 register --url https://my-agent.vercel.app --broadcast

完整详情请参阅 aixyz.sh/protocols/erc-8004。

测试（可选）

测试是可选的，但建议高级用户编写。测试使用 Bun 内置的运行器（bun:test）。编写 确定性测试（不调用 API），并对非确定性测试使用 test.skipIf(!process.env.OPENAI_API_KEY)。使用 "aixyz/model" 中的 fake() 编写完全离线且适合 CI 的测试。

bun test                      # run all tests
bun test app/agent.test.ts    # run a specific file

完整详情请参阅 aixyz.sh/getting-started/testing。

协议端点

每个已部署的 Agent 都会自动公开以下端点：

端点	协议	描述
/.well-known/agent-card.json	A2A	Agent 发现卡片
/agent	A2A	带有 x402 付款门槛的 JSON-RPC 端点
/mcp	MCP	与 MCP 客户端共享工具

示例

github.com/AgentlyHQ/aixyz 中的 examples/ 目录包含适用于常见模式的可运行 Agent。如有疑问，请查找符合需求的示例。

如果你可以访问 GitHub，请克隆仓库并直接查看 examples/：

gh repo clone AgentlyHQ/aixyz
ls aixyz/examples/

每个示例都包含一个 aixyz.config.ts、app/agent.ts 和 app/tools/，可供你参考。 aixyz.sh 上的 Templates 标签页介绍了每个示例。

仓库结构（供探索）

如果你克隆了仓库，以下是值得关注的关键目录：

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

在任何 CLI 命令上使用 --help，阅读 aixyz.sh 上的文档，或浏览 github.com/AgentlyHQ/aixyz/tree/main/examples 中的示例， 以获取最新信息。