Agentuity フレームワーク配置ガイド

Agentuity フレームワーク配置ガイド は何をしますか？

Agentuityは、お使いのフレームワークの標準的なファイル構成と連携します。ルート、ページ、サーバー関数、設定は、フレームワークが期待する場所に配置してください。Agentuityクライアントはサーバーサイドコードにのみ追加します。

スキャフォールディング対応フレームワーク

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 はサーバーサイドに保持する

参考ドキュメント

• フレームワーク: https://agentuity.dev/frameworks
• プロジェクト構造: https://agentuity.dev/get-started/project-structure
• 既存アプリへの追加: https://agentuity.dev/get-started/import-existing-app
• スタンドアロンパッケージ: https://agentuity.dev/reference/standalone-packages