Integración de agente: enrutamiento tipado

Usa el SDK de TypeScript de System One y la API alojada de decisiones para enrutar la petición de un agente hacia una herramienta con nombre o un paso de revisión. Esta guía construye un enrutador de solicitudes de soporte: el modelo elige una opción y tu aplicación decide si esa opción se ejecuta y cómo. La API System One devuelve una decisión estructurada; la ejecución y las comprobaciones de permisos se quedan en el runtime de tu agente.

Preguntas frecuentes

Q: How do I integrate System One with an AI agent for tool routing?
A: Llama a Choice con el state del agente y una lista permitida de herramientas; usa la selección tipada en tu código. System One decide; tu app conserva permisos y ejecución.

Q: Does System One execute tools for me?
A: No. La API System One devuelve una decisión estructurada. Ejecución y permisos siguen en tu runtime de agente.

Preguntas frecuentes

¿Cómo integro System One con un agente de IA para enrutar herramientas?
Llama a Choice con el state del agente y una lista permitida de herramientas; usa la selección tipada en tu código. System One decide; tu app conserva permisos y ejecución.

¿System One ejecuta las herramientas por mí?
No. La API System One devuelve una decisión estructurada. Ejecución y permisos siguen en tu runtime de agente.

Por qué enrutamiento tipado de herramientas

Usa la interfaz de decisión cuando tu aplicación puede enunciar la pregunta y los resultados posibles: enrutar un mensaje, elegir entre los siguientes pasos permitidos, calificar una respuesta según una rúbrica o estimar si se cumple una condición. Varias preguntas pueden inspeccionar de forma independiente un mismo contexto compartido.

System One no reúne la información que falta, no emite reembolsos, no envía respuestas y no invoca herramientas por ti. La planificación abierta corresponde a otro paso de razonamiento o a una persona. Incluye resultados explícitos de think o review cuando corresponda.

El código siguiente devuelve uno de estos nombres; no implementa la búsqueda de documentos, no envía un mensaje y no crea un ticket de revisión. Nunca dejes que un nombre, una URL o un comando de shell generado por el modelo se salte la lista permitida.

Elige un ID exacto del directorio actual de modelos. Evalúa la calidad de la tarea, la latencia, el precio y los límites en casos representativos, incluyendo redacción ambigua, información ausente y errores con consecuencias. No trates un nombre de modelo ni un resultado rápido como una garantía. Vuelve a evaluar cuando cambien el modelo, las instrucciones, las opciones o la rúbrica.

Patrón con Choice

Instala los paquetes del lado del servidor:

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

Este es el stack de cliente alojado actual. Para decisiones de agente basadas en imágenes, elige un modelo con capacidad de imagen (Clef, Clef Flash o Clef Omni) y usa el ejemplo alojado con Fetch; systemOneAdapter no codifica imágenes en evaluate(). Conserva la representación exacta de la imagen y el orden del array junto con la operación, incluye el base64 en la estimación de créditos y revisa el contenido de la imagen en busca de información sensible. Para extracción tipada desde texto o imágenes, usa Clairic extract().

Usa la configuración de entorno del inicio rápido alojado: solo clave de API, URL base y modelo. Sustituye YOUR_MODEL_ID por el ID elegido del directorio. El ejemplo crea una clave de operación nueva en el código, una vez por cada decisión nueva, no en configuración compartida ni en una función de reintento.

Este ejemplo de TypeScript selecciona una herramienta propuesta; no la ejecuta:

import { createSystemOne, choice } from '@system-one-ai/core';
import { createFetchTransport } from '@system-one-ai/transport-fetch';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('Set the API key, base URL, and catalog model.');
}

const client = createSystemOne({
  apiKey,
  baseURL,
  model,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const operation = {
  idempotencyKey: crypto.randomUUID(),
  request: {
    model,
    state: { message: 'Can you explain how credits are calculated?' },
    questions: {
      tool: choice('Choose the next support tool. Do not execute it.', {
        search_docs: 'A product or usage question can be answered from documentation',
        ask_user: 'Essential details are missing; ask the user before proceeding',
        human_review: 'A payment dispute, sensitive action, or policy exception needs review',
      }),
    },
  },
};

const result = await client.evaluate(operation.request, {
  headers: { 'Idempotency-Key': operation.idempotencyKey },
  signal: AbortSignal.timeout(30_000),
});
const proposedTool: 'search_docs' | 'ask_user' | 'human_review' = result.answers.tool.choice;
console.log({ proposedTool, requestId: result.response.requestId });

Para ejecutarlo, guárdalo como agent-decision.mts y usa node --env-file=.env agent-decision.mts con Node.js 22.18+. Cada ejecución del script inicia una nueva operación facturable, aunque la entrada sea la misma. Este ejemplo en memoria no es una recuperación segura ante reinicios.

Crear y reintentar son pasos separados: un reintento dentro del proceso llama a evaluate() con el mismo operation.request y el mismo operation.idempotencyKey, sin volver a ejecutar el bloque de creación de la operación. En un sistema de trabajos real, guarda de forma durable la operación completa en el registro del trabajo de tu aplicación antes de llamar a evaluate(), incluyendo su clave, el modelo seleccionado y la petición completa. Tras un fallo o un reinicio, carga ese registro en lugar de generar un UUID o reconstruir la petición a partir de un prompt más nuevo o de la selección de modelo actual. El inicio rápido no ofrece ese almacenamiento durable. Cada decisión realmente nueva obtiene una clave nueva, incluida una reevaluación intencionada de una entrada idéntica. Define tu propio plazo total, límite de intentos y política de gasto; un timeout o una cancelación no prueba que el servicio no haya terminado.

El state debe contener solo la información necesaria, nunca secretos ni historial privado ajeno. Un array de state es una entrada compartida, no un lote de evaluaciones separadas. Las preguntas no consumen las respuestas de otras; si un juicio posterior depende de uno anterior, revísalo y envía una petición aparte. Consulta primitives para la distinción entre boolean y noul en el SDK y en la API nativa.

Autentica fuera del contexto del modelo. Crea una clave de plataforma en la consola con sesión iniciada y guárdala en una variable de entorno del servidor o en un ajuste privado de credenciales de confianza. Las llamadas usan Authorization: Bearer contra https://system-one.dev/v1; el host de documentación no sirve inferencia. Mantén las claves fuera de los prompts, de las descripciones de herramientas, de los bundles del navegador, de las URLs y de los logs. Revoca una clave cuando ya no necesites su conexión. GET /v1/models es público y no requiere la clave de plataforma. Las claves de una misma cuenta comparten saldo, límite de tasa y espacio de idempotencia: no des claves distintas a agentes distintos esperando saldos aislados.

Los permisos se quedan en tu app

Empieza con una lista permitida pequeña, no con todas las herramientas a las que tu agente puede acceder. Para un asistente de soporte, search_docs recupera la guía del producto, ask_user pide la información que falta y human_review entrega una solicitud con consecuencias o en disputa a una persona. Las descripciones de las herramientas deben indicar cuándo elegir cada opción y no deben contener credenciales ni instrucciones que concedan permisos.

Un resultado del modelo no es una autorización. Comprueba fuera del modelo la identidad y los permisos del usuario que actúa, las listas permitidas de acciones y las aprobaciones requeridas. Detectar una solicitud de reembolso no establece la elegibilidad. Los pagos, los cambios de acceso y los mensajes externos deben conservar las confirmaciones que exige tu política. Una herramienta que no está en la lista permitida no se puede seleccionar, y un nombre, una URL o un comando de shell generado por el modelo nunca debe saltarse esa lista.

Empieza con sugerencias en lugar de ejecución automática. Define una ruta de revisión para las pruebas ambiguas, contradictorias o incompletas. Elige los umbrales a partir de tus propios casos de evaluación y de sus consecuencias, no a partir de un porcentaje universal. Las respuestas ausentes o las peticiones fallidas están sin resolver, no son un sí, un no o la puntuación más baja automáticos. Mantén los permisos de cada conexión limitados a lo que necesita.

Evalúa el enrutador antes de habilitar herramientas. Construye un conjunto etiquetado a partir de tus propios casos de soporte. Los siguientes son objetivos de revisión para este ejemplo, no salidas medidas del modelo:

Incluye peticiones ambiguas e instrucciones que intentan forzar otra herramienta. Mide por separado las selecciones de la herramienta equivocada y los casos de revisión omitidos; ni una respuesta HTTP correcta ni una probabilidad alta del modelo prueban un enrutamiento seguro. Empieza en modo de solo sugerencias y decide después qué acciones de solo lectura pueden ejecutarse bajo tu política actual. Registra el modelo, las descripciones de las opciones, los request IDs y las etiquetas de resultado sin registrar claves ni datos personales innecesarios.

Score y Noul en paralelo

Choice encaja con esta decisión de siguiente paso mutuamente excluyente. Si necesitas ordenar varios documentos recuperados o evaluar condiciones independientes, usa Score o Noul en su lugar. Si el modelo necesita un resultado de búsqueda antes de emitir otro juicio, ejecuta primero la búsqueda permitida y envía una evaluación aparte con ese resultado como contexto.

El SDK expone el resultado de Noul con probability, mientras que en el cable la misma respuesta usa type: 'noul'. Consulta primitives para la diferencia entre la forma nativa y la forma normalizada del SDK.

Atajo para agentes de código

Para enseñar a Cursor, Claude Code o Codex a escribir esta integración, instala el skill en Usar System One con agentes de código. El SDK independiente también puede conectarse directamente a otros servicios con sus propias credenciales y su propia facturación; consulta instalación del SDK y conexiones a proveedores.

Referencia HTTP completa

Sigue el inicio rápido del SDK alojado para la conexión y los metadatos de respuesta, y la API para el contrato completo de la interfaz HTTP. Cada evaluación nueva es una operación de decisión separada.

Empieza con maxRetries: 0. APIError del core ofrece statusCode, requestId y retryAfterMs, pero no todas las cabeceras de clasificación de la plataforma. Un controlador de recuperación puede usar Fetch directamente, o APIError.headers del cliente oficial TypeSafe, para inspeccionar X-System-One-Error-Code, X-System-One-Error-Source, X-Request-Id, Retry-After y X-System-One-Credits. No clasifiques los fallos por texto arbitrario del cuerpo.

Retry-After puede ser segundos o una fecha HTTP. Limita los reintentos con un plazo y un número de intentos de la aplicación, y usa backoff con jitter cuando no se indique demora. Conserva el modelo efectivo, el orden de la rúbrica, las extensiones y los valores numéricos. No caigas silenciosamente en otro modelo durante la recuperación. Una clave nueva puede generar otro cargo; un cuerpo modificado con la clave antigua entra en conflicto.

Las claves completadas y las respuestas se conservan durante 24 horas desde la creación de la petición. Tras la caducidad, la misma clave puede iniciar una operación nueva; no es deduplicación permanente. Consulta idempotencia y reintentos, errores y versionado para el contrato completo.

La recuperación de una decisión no evita una acción de herramienta duplicada. Tu aplicación necesita estado de ejecución durable e idempotencia aparte para enviar una respuesta, realizar un pago o asignar trabajo. Si el resultado o el cargo siguen siendo inciertos, pausa e inspecciona el uso; escribe a support@system-one.dev con el request ID, nunca con la clave de API.

Para los precios de los paquetes de créditos, consulta la precios de la API y revisa la facturación antes de ejecutar un conjunto grande de evaluaciones.

Consulta también agentes de código, primitives, inicio rápido, la referencia de la API y el SDK para el resto del flujo.