Agentuity Framework Placement

Was macht Agentuity Framework Placement?

Agentuity arbeitet mit der normalen Dateistruktur Ihres Frameworks. Platzieren Sie Routen, Seiten, Serverfunktionen und Konfiguration dort, wo das Framework sie erwartet. Fügen Sie Agentuity-Clients nur im serverseitigen Code hinzu.

Erstellen-unterstützte Frameworks

Mit agentuity create können diese Frameworks gerüstet werden:

Framework	API-Routenort	App-UI-Ort	Entwicklungs-Script-Eigentümer
Next.js	src/app/api/<name>/route.ts	src/app/page.tsx	Next.js
Nuxt	server/api/<name>.get.ts oder .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 Routen-Handler	src/landing.tsx wenn gerüstet	Hono Server-Script

Verwenden Sie den Routen-Handler des Frameworks, um die Anfrage zu validieren, und rufen Sie dann eine gemeinsam genutzte Funktion für die eigentliche Arbeit auf.

Integration in bestehende Apps

Für Apps, die Sie bereits haben, installieren Sie die CLI und importieren Sie das Projekt, ohne die App-Form zu ändern:

npm install -D @agentuity/cli
agentuity project import --name existing-app --confirm

Nützliche Routenorte:

Framework	Server-Routenform
React Router	app/routes/api.agentuity.ts, registriert in app/routes.ts
TanStack Start	src/routes/api.agentuity.tsx mit Server-Handlern
Vite + React	Eine Server-Grenze wie server.ts; Browser-Code ruft diesen Server auf
Express oder andere Router	Vorhandenes Routenmodul; importieren Sie Agentuity-Clients serverseitig

Nur-Server-Regel

Setzen Sie Agentuity SDK-Schlüssel keinen Browser-Bundles aus. Service-Clients gehören in Routen, Server-Aktionen, Worker, Scripts oder andere nur-Server-Module.

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 });
}

Browser-Komponenten sollten Ihre Server-Route aufrufen:

const response = await fetch('/api/agentuity-health');
const status = await response.json();

Dünne Route, gemeinsam genutzte Funktion

Bevorzugen Sie diese Aufteilung für KI-Funktionen, Hintergrundarbeit und Service-Aufrufe:

// lib/triage.ts
export async function triageMessage(message: string): Promise<{ priority: string }> {
  return { priority: message.includes('urgent') ? 'high' : 'normal' };
}

// Framework-Routendatei
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);
}

Dies hält routenspezifischen Code klein und ermöglicht es der Kernfunktion, zwischen Frameworks, Tests, Warteschlangen, Zeitplänen und Scripts zu wechseln.

Hono Middleware-Option

Verwenden Sie in Hono-Apps standardmäßig direkte Clients, wenn Portabilität wichtig ist. Verwenden Sie @agentuity/hono, wenn der Zugriff auf Clients über den Hono-Kontext die Lesbarkeit verbessert:

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, Datenbank, Objektspeicher, Webhooks und Coder sind direkte Clients.

Häufige Fehler

Fehler	Bessere Vorgehensweise
Service-Clients in Browser-Komponenten platzieren	Rufen Sie eine Server-Route auf, die den Client besitzt
Neue Ordner hinzufügen, die Framework-Konventionen umgehen	Verwenden Sie die Routen-/Seitenorte des Frameworks
KI- oder Service-Logik in jeder Route duplizieren	Teilen Sie die Arbeit in eine einfache Funktion und importieren Sie sie
Annahme, dass jedes Framework denselben API-Routenpfad verwendet	Überprüfen Sie die Routentabelle vor dem Bearbeiten
SDK-Schlüssel in öffentlichen Umgebungsvariablen-Präfixen platzieren	Halten Sie AGENTUITY_SDK_KEY serverseitig

Nützliche Dokumentationen

• Frameworks: https://agentuity.dev/frameworks
• Projektstruktur: https://agentuity.dev/get-started/project-structure
• Zu bestehender App hinzufügen: https://agentuity.dev/get-started/import-existing-app
• Eigenständige Pakete: https://agentuity.dev/reference/standalone-packages