# AI智能体部署框架

`AI框架` `智能体` `Next.js风格` `MCP` `Web3支付` `A2A协议`

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AgentlyHQ/aixyz/main/docs/logo/dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/AgentlyHQ/aixyz/main/docs/logo/light.svg">
    <img alt="aixyz" src="https://raw.githubusercontent.com/AgentlyHQ/aixyz/main/docs/logo/light.svg" width="auto" height="120px">
  </picture>
</p>

<p></p>

<p align="center"><b>类 Next.js 框架，将 AI 智能体打包为可部署服务，支持 A2A、MCP、x402 支付和 ERC-8004 身份认证。</b></p>

<p align="center">
  <a href="https://aixyz.sh">文档</a> · <a href="#快速开始">快速开始</a> · <a href="#工作原理">工作原理</a> · <a href="#示例">示例</a> · <a href="#cli">CLI</a> · <a href="#协议">协议</a>
</p>

## 文档

完整文档、API 参考和使用指南请访问 **[aixyz.sh](https://aixyz.sh)**。

## 快速开始

```bash
bunx create-aixyz-app my-agent
cd my-agent
bun run dev
```

智能体启动后，将暴露以下端点：

| 端点                           | 协议 | 功能说明                         |
| ------------------------------ | ---- | -------------------------------- |
| `/.well-known/agent-card.json` | A2A  | 智能体发现卡片                   |
| `/agent`                       | A2A  | JSON-RPC 端点，x402 支付网关     |
| `/mcp`                         | MCP  | 与 MCP 客户端共享工具            |

## 工作原理

一个 aixyz 智能体由三部分组成：配置、智能体本体和工具。

### 1. 配置

`aixyz.config.ts` 声明智能体的身份信息和支付地址：

```ts
import type { AixyzConfig } from "aixyz/config";

const config: AixyzConfig = {
  name: "Weather Agent",
  description: "获取全球任意地点的实时天气。",
  version: "0.1.0",
  x402: {
    payTo: "0x...",
    network: "eip155:8453", // Base 主网
  },
};

export default config;
```

### 2. 智能体

`app/agent.ts` 定义智能体及其支付价格：

```ts
import { openai } from "@ai-sdk/openai";
import { stepCountIs, ToolLoopAgent } from "ai";
import type { Accepts } from "aixyz/accepts";
import weather from "./tools/weather";

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

export default new ToolLoopAgent({
  model: openai("gpt-4o-mini"),
  instructions: "你是一个实用的天气助手。",
  tools: { weather },
  stopWhen: stepCountIs(10),
});
```

### 3. 工具

`app/tools/` 目录下每个文件导出一个 Vercel AI SDK `tool`，以及可选的 `accepts` 用于 MCP 支付验证：

```ts
import { tool } from "ai";
import { z } from "zod";
import type { Accepts } from "aixyz/accepts";

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

export default tool({
  description: "获取某城市的当前天气状况。",
  inputSchema: z.object({
    location: z.string().describe("城市名称"),
  }),
  execute: async ({ location }) => {
    // 你的逻辑代码
  },
});
```

就这些。运行 `bun run dev`，aixyz 会自动生成服务器，连接 A2A + MCP + x402，并开始提供服务。

## 示例

| 示例                                                             | 说明                                     |
| ---------------------------------------------------------------- | ---------------------------------------- |
| [`boilerplate`](./examples/boilerplate/)                         | 最小化起步模板（自动生成服务器）         |
| [`chainlink`](./examples/chainlink/)                             | 使用自定义服务器的 Chainlink 数据订阅源  |
| [`flight-search`](./examples/flight-search/)                     | 集成 Stripe 支付的航班搜索               |
| [`local-llm`](./examples/local-llm/)                             | 通过 Docker 运行本地大模型（无需外部 API）|
| [`with-custom-facilitator`](./examples/with-custom-facilitator/) | 使用自定义 x402 促进者                   |
| [`with-custom-server`](./examples/with-custom-server/)           | 自定义服务器配置                         |
| [`with-express`](./examples/with-express/)                       | Express 中间件集成                       |
| [`sub-agents`](./examples/sub-agents/)                           | 单次部署暴露多个 A2A 端点                |
| [`with-tests`](./examples/with-tests/)                           | 包含测试示例的智能体                     |
| [`fake-llm`](./examples/fake-llm/)                               | 使用 `fake()` 模型进行完全确定性测试     |
| [`with-vercel-blob`](./examples/with-vercel-blob/)               | 使用 Vercel Blob 的纯 MCP 文本存储       |

## CLI

```bash
bun add aixyz            # CLI 随 aixyz 包一起安装
bunx aixyz --help        # 或不安装直接运行
```

```bash
aixyz dev                # 带热重载的开发服务器
aixyz build              # 打包以供部署（独立、Vercel 或可执行文件）
aixyz erc-8004 register  # 注册链上智能体身份
aixyz erc-8004 update    # 更新智能体元数据 URI
```

所有选项请参阅 [CLI 参考文档](https://aixyz.sh/packages/aixyz)。

## 协议

**A2A（智能体间通信）** — 智能体发现卡片 + JSON-RPC 端点。其他智能体可以发现你的智能体并发送任务。

**MCP（模型上下文协议）** — 将工具暴露给任意 MCP 客户端（Claude Desktop、VS Code、Cursor）。

**x402** — HTTP 402 微支付。按请求付费，带有密码学证明，可在链上验证。

**ERC-8004** — 以太坊、Base、Polygon、Scroll、Monad、BSC 或 Gnosis 链上的智能体身份标准。

## 贡献

```bash
bun install          # 安装依赖
bun run build        # 构建所有包
bun run test         # 运行测试
bun run format       # 使用 Prettier 格式化代码
```

欢迎提交 PR。提交前请确保 `bun run build && bun run test && bun run format` 均通过。

## 许可证

MIT