170 lines
6.0 KiB
Markdown
170 lines
6.0 KiB
Markdown
# 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 |