agentuity/sdk

Placement dans le Framework Agentuity

Agentuity fonctionne avec la structure de fichiers normale de votre framework. Placez les routes, pages, fonctions serveur et configuration là où le framework les attend. Ajoutez les clients Agentuity uniquement dans le code côté serveur.

Frameworks Supportés par create

agentuity create peut générer ces frameworks :

Framework	Emplacement de la route API	Emplacement UI de l'application	Propriétaire du script de développement
Next.js	src/app/api/<name>/route.ts	src/app/page.tsx	Next.js
Nuxt	server/api/<name>.get.ts ou .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	Gestionnaires de route dans src/index.ts	src/landing.tsx (lors de la génération)	Script serveur Hono

Utilisez le gestionnaire de route du framework pour valider la requête, puis appelez une fonction partagée pour le travail réel.

Adoption d'une Application Existante

Pour les applications que vous possédez déjà, installez la CLI et importez le projet sans modifier la structure de l'application :

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

Emplacements de routes utiles :

Framework	Forme de la route serveur
React Router	app/routes/api.agentuity.ts, enregistrée dans app/routes.ts
TanStack Start	src/routes/api.agentuity.tsx avec gestionnaires serveur
Vite + React	Une limite serveur telle que server.ts ; le code navigateur appelle ce serveur
Express ou autres routeurs	Module de route existant ; importez les clients Agentuity côté serveur

Règle Serveur Uniquement

N'exposez pas les clés du SDK Agentuity dans les bundles navigateur. Les clients de service appartiennent aux routes, actions serveur, workers, scripts ou autres modules exclusivement serveur.

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

Les composants navigateur doivent appeler votre route serveur :

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

Route Fine, Fonction Partagée

Privilégiez cette séparation pour les fonctionnalités IA, les tâches d'arrière-plan et les appels de service :

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

// fichier de route du framework
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);
}

Cela permet de garder le code spécifique à la route petit et de déplacer la fonction principale entre les frameworks, tests, files d'attente, planifications et scripts.

Option Middleware Hono

Dans les applications Hono, utilisez les clients directs par défaut lorsque la portabilité est importante. Utilisez @agentuity/hono lorsque l'accès aux clients via le contexte Hono améliore la lisibilité :

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

La passerelle IA, la base de données, le stockage d'objets, les webhooks et Coder utilisent des clients directs.

Erreurs Courantes

Erreur	Meilleure approche
Placer les clients de service dans les composants navigateur	Appeler une route serveur qui possède le client
Ajouter de nouveaux dossiers qui contournent les conventions du framework	Utiliser les emplacements de route/page du framework
Dupliquer la logique IA ou de service dans chaque route	Placer le travail partagé dans une fonction simple et l'importer
Supposer que tous les frameworks utilisent le même chemin de route API	Vérifier le tableau des routes avant de modifier
Placer les clés SDK dans des préfixes d'environnement publics	Garder AGENTUITY_SDK_KEY côté serveur

Documentation Utile

• Frameworks : https://agentuity.dev/frameworks
• Structure du projet : https://agentuity.dev/get-started/project-structure
• Ajouter à une application existante : https://agentuity.dev/get-started/import-existing-app
• Paquets autonomes : https://agentuity.dev/reference/standalone-packages