Agentuity 框架集成 是做什么的？
Agentuity 与你使用的框架的正常文件布局兼容。将路由、页面、服务器函数和配置放在框架期望的位置。仅在服务器端代码中添加 Agentuity 客户端。
create 支持的框架
agentuity create 可以为以下框架搭建脚手架：
| 框架 | API 路由位置 | 应用 UI 位置 | 开发脚本所有者 |
|---|---|---|---|
| Next.js | src/app/api/<name>/route.ts | src/app/page.tsx | Next.js |
| Nuxt | server/api/<name>.get.ts 或 .post.ts | app/app.vue | Nuxt |
| SvelteKit | src/routes/<path>/+server.ts | src/routes/+page.svelte | Vite/SvelteKit |
| Astro | src/pages/api/<name>.ts | src/pages/index.astro | Astro |
| Hono | src/index.ts 路由处理器 | src/landing.tsx（当使用脚手架时） | Hono 服务器脚本 |
使用框架的路由处理器验证请求，然后调用共享函数执行实际工作。
现有应用集成
对于已有的应用，安装 CLI 并导入项目，无需更改应用结构：
npm install -D @agentuity/cli
agentuity project import --name existing-app --confirm
实用的路由位置：
| 框架 | 服务器路由形态 |
|---|---|
| React Router | app/routes/api.agentuity.ts，并在 app/routes.ts 中注册 |
| TanStack Start | src/routes/api.agentuity.tsx，包含服务器处理器 |
| Vite + React | 一个服务器边界文件，例如 server.ts；浏览器代码调用该服务器 |
| Express 或其他路由器 | 现有的路由模块；在服务器端导入 Agentuity 客户端 |
仅限服务器端规则
不要将 Agentuity SDK 密钥暴露给浏览器打包产物。服务客户端应位于路由、服务器操作、工作线程、脚本或其他仅限服务器端的模块中。
import { KeyValueClient } from '@agentuity/keyvalue';
const kv = new KeyValueClient();
export async function GET(): Promise<Response> {
const result = await kv.get<{ checkedAt: string }>('health', 'latest');
return Response.json({ ok: true, exists: result.exists });
}
浏览器组件应调用你的服务器路由：
const response = await fetch('/api/agentuity-health');
const status = await response.json();
薄路由，共享函数
对于 AI 功能、后台工作和服务调用，推荐这种拆分方式：
// lib/triage.ts
export async function triageMessage(message: string): Promise<{ priority: string }> {
return { priority: message.includes('urgent') ? 'high' : 'normal' };
}
// 框架路由文件
import { triageMessage } from '@/lib/triage';
export async function POST(request: Request): Promise<Response> {
const body = (await request.json()) as { message?: string };
if (!body.message) {
return Response.json({ error: 'message is required' }, { status: 400 });
}
const result = await triageMessage(body.message);
return Response.json(result);
}
这可以使特定于路由的代码保持精简，并让核心函数能够在不同框架、测试、队列、调度任务和脚本之间复用。
Hono 中间件选项
在 Hono 应用中，当可移植性重要时，默认使用直接客户端。当你希望通过 Hono 上下文访问客户端以提升可读性时，可以使用 @agentuity/hono：
import { Hono } from 'hono';
import { agentuity } from '@agentuity/hono';
import type { Services } from '@agentuity/hono';
const app = new Hono<{ Variables: Pick<Services, 'kv'> }>();
app.use('*', agentuity());
app.get('/api/preferences/:userId', async (c) => {
const result = await c.var.kv.get('preferences', c.req.param('userId'));
return c.json({ exists: result.exists });
});
AI 网关、数据库、对象存储、Webhook 和 Coder 均使用直接客户端。
常见错误
| 错误 | 更好的做法 |
|---|---|
| 在浏览器组件中使用服务客户端 | 调用拥有该客户端的服务器路由 |
| 添加违反框架约定的新文件夹 | 使用框架的路由/页面位置 |
| 在每条路由中重复 AI 或服务逻辑 | 将共享工作放入普通函数并导入它 |
| 假设每个框架都使用相同的 API 路由路径 | 在编辑前检查路由表 |
| 将 SDK 密钥放在公共环境变量前缀中 | 将 AGENTUITY_SDK_KEY 保持在服务器端 |