Agentuity: Posicionamento em Frameworks

Posicionamento no Framework com Agentuity

A Agentuity funciona com a estrutura de arquivos normal do seu framework. Coloque rotas, páginas, funções de servidor e configuração onde o framework espera. Adicione clientes Agentuity apenas em código do lado do servidor.

Frameworks Suportados pelo Comando create

O comando agentuity create pode gerar a estrutura inicial para estes frameworks:

Framework	Localização da Rota de API	Localização da UI do App	Dono do Script de Desenvolvimento
Next.js	src/app/api/<nome>/route.ts	src/app/page.tsx	Next.js
Nuxt	server/api/<nome>.get.ts ou .post.ts	app/app.vue	Nuxt
SvelteKit	src/routes/<caminho>/+server.ts	src/routes/+page.svelte	Vite/SvelteKit
Astro	src/pages/api/<nome>.ts	src/pages/index.astro	Astro
Hono	Manipuladores de rota em src/index.ts	src/landing.tsx (quando gerado)	Servidor Hono

Use o manipulador de rotas do framework para validar a requisição e, em seguida, chame uma função compartilhada para o trabalho real.

Adoção em Aplicações Existentes

Para aplicações que você já possui, instale a CLI e importe o projeto sem alterar a estrutura do app:

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

Localizações úteis de rotas:

Framework	Estrutura da Rota de Servidor
React Router	app/routes/api.agentuity.ts, registrado em app/routes.ts
TanStack Start	src/routes/api.agentuity.tsx com manipuladores de servidor
Vite + React	Um limite de servidor como server.ts; o código do navegador chama esse servidor
Express ou outros roteadores	Módulo de rota existente; importe os clientes Agentuity no lado do servidor

Regra: Apenas Servidor

Não exponha chaves do SDK da Agentuity em bundles do navegador. Os clientes de serviço pertencem a rotas, server actions, workers, scripts ou outros módulos exclusivos do 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 });
}

Os componentes do navegador devem chamar sua rota de servidor:

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

Rota Fina, Função Compartilhada

Prefira esta separação para funcionalidades de IA, trabalhos em segundo plano e chamadas de serviço:

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

// arquivo de rota do 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);
}

Isso mantém o código específico da rota pequeno e permite que a função principal seja movida entre frameworks, testes, filas, agendadores e scripts.

Opção de Middleware para Hono

Em aplicações Hono, use clientes diretos por padrão quando a portabilidade for importante. Use @agentuity/hono quando acessar clientes através do contexto do Hono melhorar a legibilidade:

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, banco de dados, armazenamento de objetos, webhooks e o Coder usam clientes diretos.

Erros Comuns

Erro	Melhor abordagem
Colocar clientes de serviço em componentes do navegador	Chame uma rota de servidor que possua o cliente
Adicionar novas pastas que ignoram as convenções do framework	Use as localizações de rota/página do framework
Duplicar lógica de IA ou serviço em cada rota	Coloque o trabalho compartilhado em uma função simples e importe-a
Supor que todo framework usa o mesmo caminho de rota de API	Verifique a tabela de rotas antes de editar
Colocar chaves SDK em prefixos públicos de env	Mantenha AGENTUITY_SDK_KEY no lado do servidor

Documentação Útil

• Frameworks: https://agentuity.dev/frameworks
• Estrutura de projeto: https://agentuity.dev/get-started/project-structure
• Adicionar a app existente: https://agentuity.dev/get-started/import-existing-app
• Pacotes independentes: https://agentuity.dev/reference/standalone-packages