Integración de agentes

Estado: Patrón de arquitectura documentado. NexoRouter no publica todavía un Agent SDK propio.

Un agente combina llamadas de modelo con estado, límites de ejecución y, opcionalmente, herramientas. NexoRouter aporta el endpoint de modelo; tu aplicación o framework sigue controlando el loop, la memoria, la ejecución de herramientas y las aprobaciones.

Qué está disponible hoy

Capa	Estado
Chat Completions no streaming	Estable y documentado.
Historial multi-turn en `messages`	Disponible mediante el request de Chat Completions.
OpenAI SDK con base URL de NexoRouter	Estable para llamadas documentadas.
Tool calling	Depende del modelo y del cliente; requiere verificación.
Streaming	No es una capacidad pública estable verificada.
Responses API y Agent SDKs que la exigen	No soportados por la superficie pública actual.
SDK de agentes de NexoRouter	Todavía no existe.

Arquitectura recomendada

Usuario
  -> tu API
      -> valida identidad, presupuesto y entrada
      -> carga estado de conversación
      -> llama POST /v1/chat/completions
      -> valida la salida
      -> solicita aprobación humana si hay una acción sensible
      -> ejecuta solo herramientas permitidas
      -> guarda resultado y métricas
  <- respuesta

El modelo no debe recibir acceso directo a credenciales, bases de datos o acciones irreversibles.

Loop multi-turn mínimo

Este ejemplo conserva la conversación pero no ejecuta herramientas. Es el punto de partida estable antes de agregar comportamiento agéntico.

import OpenAI from "openai";
import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";

const client = new OpenAI({
  apiKey: process.env.NEXOROUTER_API_KEY,
  baseURL: "https://api.nexorouter.com/v1",
  timeout: 60_000,
  maxRetries: 1,
});

const messages: ChatCompletionMessageParam[] = [
  {
    role: "system",
    content: "You are a support planner. Ask before any action and keep answers concise.",
  },
];

export async function nextTurn(userText: string) {
  messages.push({ role: "user", content: userText });

  const response = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages,
    max_tokens: 400,
  });

  const answer = response.choices[0]?.message?.content ?? "";
  messages.push({ role: "assistant", content: answer });
  return { answer, usage: response.usage };
}

En producción, guarda estado por usuario o conversación en tu backend, no en una variable global.

Antes de agregar herramientas

Elige un modelo desde Models y confirma un request de texto.
Prueba un tool call de solo lectura en un entorno aislado.
Valida nombre de herramienta y argumentos con un schema estricto.
Rechaza cualquier herramienta no incluida en una allowlist.
Agrega aprobación humana para pagos, borrados, mensajes externos y cambios de permisos.
Fija max_steps, timeout total, presupuesto y concurrencia.
Registra cada paso y su request ID.
Solo entonces habilita ese par modelo/framework en producción.

Consulta Tool Calling antes de asumir que un modelo o cliente soporta herramientas.

Guardrails mínimos

Riesgo	Control
Loop infinito	`max_steps` pequeño y deadline total.
Gasto inesperado	Budget por key, límite de tokens y modelo permitido.
Prompt injection	Separa instrucciones, datos y resultados de herramientas; no confíes en texto recuperado.
Herramienta peligrosa	Allowlist, schema estricto, permisos mínimos y aprobación humana.
Reintentos duplicados	Usa operaciones idempotentes en tu propia aplicación.
Fuga de datos	Redacta secretos, limita logs y evita enviar datos innecesarios.
Fallo upstream	Backoff limitado, fallback explícito y trazabilidad por request ID.

Frameworks

Frameworks como LangChain, Vercel AI SDK, LlamaIndex, Cline o Roo Code son integraciones candidatas. Su chat básico puede funcionar con una base URL compatible, pero sus flujos agénticos pueden requerir tool calling, streaming, embeddings o Responses API.

No uses una guía genérica de un framework como prueba de compatibilidad completa. Sigue el checklist de integración candidata.

Checklist de lanzamiento

La key está limitada a este servicio y entorno.
El modelo aparece disponible en Models.
El request básico funciona sin streaming.
Cada herramienta fue probada con entradas válidas e inválidas.
Las acciones sensibles requieren aprobación.
El agente tiene límites de pasos, tiempo, tokens y costo.
Los errores 429, 502 y 504 tienen recuperación limitada.
Usage Logs permite reconstruir el flujo sin guardar secretos.