agentuity/sdk

Colocación en Frameworks de Agentuity

Agentuity funciona con la estructura de archivos normal de tu framework. Coloca rutas, páginas, funciones de servidor y configuración donde el framework lo espera. Añade clientes de Agentuity solo en código del lado del servidor.

Frameworks Soportados por create

agentuity create puede generar la estructura de estos frameworks:

Framework	Ubicación de rutas API	Ubicación de UI de la app	Propietario del script de desarrollo
Next.js	src/app/api/<nombre>/route.ts	src/app/page.tsx	Next.js
Nuxt	server/api/<nombre>.get.ts o .post.ts	app/app.vue	Nuxt
SvelteKit	src/routes/<ruta>/+server.ts	src/routes/+page.svelte	Vite/SvelteKit
Astro	src/pages/api/<nombre>.ts	src/pages/index.astro	Astro
Hono	Manejadores de ruta en src/index.ts	src/landing.tsx al generarse	Script de servidor de Hono

Usa el manejador de rutas del framework para validar la solicitud y luego llama a una función compartida para el trabajo real.

Adopción en una Aplicación Existente

Para aplicaciones que ya tengas, instala la CLI e importa el proyecto sin cambiar la forma de la app:

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

Ubicaciones de rutas útiles:

Framework	Forma de la ruta de servidor
React Router	app/routes/api.agentuity.ts, registrada en app/routes.ts
TanStack Start	src/routes/api.agentuity.tsx con manejadores de servidor
Vite + React	Un límite de servidor como server.ts; el código del navegador llama a ese servidor
Express u otros enrutadores	Módulo de ruta existente; importa clientes de Agentuity del lado del servidor

Regla de Solo Servidor

No expongas las claves del SDK de Agentuity en los paquetes del navegador. Los clientes de servicio pertenecen a rutas, acciones de servidor, trabajadores, scripts u otros módulos solo de servidor.

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

Los componentes del navegador deben llamar a tu ruta de servidor:

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

Ruta Delgada, Función Compartida

Prefiere esta división para funciones de IA, trabajo en segundo plano y llamadas a servicios:

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

// archivo de ruta del 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);
}

Esto mantiene el código específico de la ruta pequeño y permite que la función principal se mueva entre frameworks, pruebas, colas, programaciones y scripts.

Opción de Middleware para Hono

En aplicaciones Hono, usa clientes directos por defecto cuando la portabilidad sea importante. Usa @agentuity/hono cuando acceder a los clientes a través del contexto de Hono mejore la legibilidad:

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, base de datos, almacenamiento de objetos, webhooks y Coder son clientes directos.

Errores Comunes

Error	Enfoque mejor
Poner clientes de servicio en componentes del navegador	Llama a una ruta de servidor que posea el cliente
Añadir nuevas carpetas que omitan las convenciones del framework	Usa las ubicaciones de rutas/páginas del framework
Duplicar lógica de IA o de servicio en cada ruta	Pon el trabajo compartido en una función simple e impórtala
Asumir que todos los frameworks usan la misma ruta de API	Revisa la tabla de rutas antes de editar
Poner claves del SDK en prefijos públicos de entorno	Mantén AGENTUITY_SDK_KEY del lado del servidor

Documentación Útil

• Frameworks: https://agentuity.dev/frameworks
• Estructura del proyecto: https://agentuity.dev/get-started/project-structure
• Añadir a una app existente: https://agentuity.dev/get-started/import-existing-app
• Paquetes independientes: https://agentuity.dev/reference/standalone-packages