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 게이트웨이, 데이터베이스, 객체 스토리지, 웹훅 및 Coder는 직접 클라이언트입니다.
일반적인 실수
| 실수 | 더 나은 방법 |
|---|---|
| 브라우저 컴포넌트에 서비스 클라이언트 배치 | 클라이언트를 소유한 서버 라우트 호출 |
| 프레임워크 관례를 무시하는 새 폴더 추가 | 프레임워크의 라우트/페이지 위치 사용 |
| 모든 라우트에서 AI 또는 서비스 로직 중복 | 공유 작업을 일반 함수에 넣고 가져오기 |
| 모든 프레임워크가 동일한 API 라우트 경로를 사용한다고 가정 | 편집 전에 라우트 표 확인 |
| SDK 키를 공개 env 접두사에 배치 | AGENTUITY_SDK_KEY를 서버 측에 유지 |