Agentuity 框架整合指南 是做什麼的？
Agentuity 與你使用的框架正常檔案佈局相容。請將路由、頁面、伺服器函式和設定放在框架預期的位置。僅在伺服器端程式碼中加入 Agentuity 客戶端。
支援 Scaffold 的框架
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（若以 Scaffold 建立） | 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 金鑰暴露給瀏覽器捆綁包。服務客戶端應屬於路由、伺服器動作、Worker、指令碼或其他僅限伺服器的模組。
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 Gateway、資料庫、物件儲存、Webhook 和 Coder 都是直接客戶端。
常見錯誤
| 錯誤做法 | 更好的做法 |
|---|---|
| 在瀏覽器元件中放置服務客戶端 | 呼叫擁有該客戶端的伺服器路由 |
| 新增繞過框架慣例的新資料夾 | 使用框架的路由/頁面位置 |
| 在每個路由中重複 AI 或服務邏輯 | 將共享工作放在純函式中並匯入 |
| 假設每個框架使用相同的 API 路由路徑 | 在編輯之前先檢查路由表 |
| 將 SDK 金鑰放在公共環境變數前綴中 | 將 AGENTUITY_SDK_KEY 保留在伺服器端 |