API de Jev AI y agentes de IA: guía práctica para flujos de trabajo fiables

Un agente de IA necesita algo más que un modelo de lenguaje capaz de generar una respuesta convincente. También debe decidir a qué modelo llamar, si es seguro utilizar una herramienta, cuándo hace falta más contexto y cuándo debería intervenir una persona. La API de Jev AI está diseñada para esa capa de decisión: envía un State y preguntas tipadas, y después utiliza las respuestas estructuradas en el código de la aplicación.

Esta guía explica cómo conectar la API de Jev AI a un agente, desde una sola decisión acotada hasta el enrutamiento, las protecciones antes de llamar a herramientas y la revisión humana. Si todavía no conoces el modelo, lee primero la guía para usar el modelo Jev AI antes de aplicar los patrones para agentes.

Índice

• Por qué Jev AI encaja en una arquitectura de agentes
• Una arquitectura mínima
• Paso 1: define las decisiones antes que las herramientas
• Paso 2: estructura el State y las preguntas
• Paso 3: llama a la API de Jev AI
• Paso 4: conecta las respuestas al ciclo del agente
• Paso 5: añade Jev Agent Skill
• Protecciones para llamadas a herramientas
• Revisión humana y evaluación
• Lista de comprobación para producción
• Preguntas frecuentes

Por qué Jev AI encaja en una arquitectura de agentes

Un flujo de agente suele incluir al menos dos trabajos distintos:

1. Generación y razonamiento — interpretar una solicitud, redactar contenido, resumir información o planificar una secuencia de acciones.
2. Decisiones acotadas — elegir una ruta, puntuar un riesgo, comprobar una condición o decidir si una llamada a una herramienta necesita aprobación.

Los LLM generativos son útiles para el primer trabajo. Jev lo es para el segundo. Devuelve decisiones tipadas que la aplicación puede consumir directamente, en vez de pedir al código que analice un párrafo o que confíe en una respuesta JSON sin restricciones.

La distinción importa porque un agente no debería permitir que el mismo modelo abierto redacte un plan y autorice de forma implícita todas las acciones del plan. Una capa de decisión separada hace explícitos los límites:

• el agente puede proponer una acción;
• Jev puede evaluar una condición acotada;
• el código de la aplicación puede aplicar los permisos y elegir la acción final.

No se trata de añadir una llamada al modelo en cada paso, sino de aislar las decisiones en las que una acción incorrecta sería costosa, insegura o difícil de auditar.

Una arquitectura mínima para agentes con Jev AI

Un agente práctico basado en Jev puede organizarse en cinco componentes:

Componente	Responsabilidad
Orquestador del agente	Mantiene el ciclo, el contexto y el plan del siguiente paso
API de Jev AI	Responde preguntas tipadas sobre el State actual
Modelo generativo	Escribe, resume, razona o crea un plan
Permisos de la aplicación	Deciden qué herramientas y acciones se permiten
Revisión humana	Atiende los casos inciertos o de gran impacto

El orquestador debe enviar a Jev el State más pequeño que resulte útil. Puede incluir la solicitud del usuario, los argumentos de una herramienta, las políticas de la cuenta, los resultados de verificaciones anteriores o el paso actual del flujo. Jev no necesita recibir toda la transcripción del agente si puede responder a partir de un objeto más específico.

Paso 1: define las decisiones antes que las herramientas

Antes de integrar la API, enumera las decisiones que el agente toma de forma repetida. Los mejores primeros casos de uso tienen un espacio de respuestas claro y una siguiente acción definida.

Enrutamiento de modelos

Usa Choice para decidir si una solicitud debe ir a un modelo rápido, uno con razonamiento más profundo, un flujo de recuperación de información o una ruta alternativa. Después, el agente puede llamar al modelo seleccionado desde el código.

Riesgo de una llamada a una herramienta

Usa Noul para preguntar si una acción propuesta es sensible o requiere aprobación. Algunos ejemplos son eliminar registros, enviar mensajes externos, cambiar la configuración de una cuenta o iniciar un pago.

Gravedad y prioridad de la tarea

Usa Score cuando el agente necesite un nivel ordenado, como bajo, medio, alto o crítico. La puntuación puede determinar la prioridad de una cola sin pedir al modelo generativo que invente un valor numérico.

Comprobaciones de finalización y contexto

Usa una pregunta tipada para decidir si el State actual contiene pruebas suficientes para continuar, si conviene conservar el resultado de una sesión larga o si el agente debe pedir una aclaración al usuario.

Evita empezar con «¿Qué debería hacer el agente?». La respuesta es demasiado abierta para aplicarla de forma segura. Es mejor preguntar «¿Qué ruta autorizada corresponde?» o «¿Esta llamada concreta a la herramienta requiere aprobación humana?».

Paso 2: estructura el State y las preguntas

La API de Jev acepta como State texto, un objeto JSON o un array de texto. Para los agentes, un objeto JSON suele ser el punto de partida más claro, porque separa la solicitud del usuario, la acción propuesta, las políticas y las pruebas.

{
  "state": {
    "user_request": "Please remove all duplicate contacts from the workspace.",
    "proposed_tool": "delete_contacts",
    "record_count": 1842,
    "has_backup": false,
    "policy": "Destructive bulk actions require approval"
  },
  "model": "jev-latest",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which execution path is appropriate?",
      "criteria": {
        "proceed": "The action is allowed and can run automatically",
        "confirm": "Ask the user or an operator for confirmation",
        "reject": "The action violates policy or is not supported"
      }
    },
    "needs_human": {
      "type": "noul",
      "instructions": "Does this proposed action require human approval?"
    }
  }
}

Mantén cada pregunta atómica. Varias preguntas pueden compartir el mismo State y evaluarse en paralelo; así, una sola solicitud puede devolver una ruta, una señal de riesgo y otra de revisión, sin encadenar tres llamadas independientes.

Usa los tres tipos de pregunta de forma deliberada:

• Choice selecciona una opción de una lista predefinida.
• Score puntúa el State según una escala ordenada de menor a mayor.
• Noul devuelve la probabilidad de que sea cierta una afirmación concreta.

La aplicación elige la clave de cada pregunta y esta se reutiliza en answers. Mantén las claves estables para que sea fácil comparar registros, métricas y código posterior entre versiones.

Paso 3: llama a la API de Jev AI

Cuando el State y las preguntas funcionen en el entorno de pruebas de Jev AI, conéctalos a tu servidor. El endpoint de evaluación es:

POST https://thejevai.com/v1/systemone

La solicitud requiere una clave API Bearer, el tipo de contenido application/json y tres campos principales: state, model y questions. La referencia actual de la API usa jev-latest como nombre del modelo insignia.

curl -X POST https://thejevai.com/v1/systemone \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": {
      "user_request": "Please remove all duplicate contacts from the workspace.",
      "proposed_tool": "delete_contacts",
      "has_backup": false,
      "policy": "Destructive bulk actions require approval"
    },
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which execution path is appropriate?",
        "criteria": {
          "proceed": "Allowed and safe to run automatically",
          "confirm": "Needs user or operator confirmation",
          "reject": "Not allowed or not supported"
        }
      },
      "needs_human": {
        "type": "noul",
        "instructions": "Does this proposed action require human approval?"
      }
    }
  }'

Guarda JEV_API_KEY en una variable de entorno del servidor. Nunca la pongas en código del navegador, transcripciones del agente, prompts públicos ni repositorios. La respuesta de la API incluye una respuesta tipada por cada clave de pregunta y los campos de probabilidad y confianza compatibles con su tipo.

Paso 4: conecta las respuestas al ciclo del agente

Jev devuelve una señal; el orquestador y los permisos de la aplicación siguen controlando la ejecución. Un límite sencillo de enrutamiento podría tener este aspecto:

const route = result.answers.route.choice;
const humanProbability = result.answers.needs_human.noul;

if (route === 'reject') {
  return respondSafely('This action is not allowed.');
}

if (route === 'confirm' || humanProbability >= 0.8) {
  return queueForHumanReview({ ticketId, result });
}

if (route === 'proceed') {
  return executeAllowedTool({ name: proposedTool, args, requestId });
}

return askForMoreContext();

Mantén la llamada final a la herramienta detrás de comprobaciones deterministas. Valida en el código de la aplicación el nombre de la herramienta, sus argumentos, los permisos del usuario, el alcance del recurso y el ID de solicitud, incluso cuando Jev devuelva una aprobación muy probable.

Paso 5: añade Jev Agent Skill

Para agentes de programación y entornos compatibles, el Jev Agent Skill oficial ofrece una forma reutilizable de pedir decisiones acotadas y mantener la ejecución dentro de la aplicación anfitriona. Instálalo así:

npx skills add jev-ai/jev-agent-skill

Configura la clave y el idioma en el entorno:

export JEV_API_KEY="sk_your_key_here"
export JEV_LANGUAGE="en-US"

El Skill puede guiar al agente para elegir Choice, Score o Noul, enviar el State mínimo útil e interpretar el resultado estructurado. No concede a Jev permiso para ejecutar un pago, eliminar datos ni eludir el sistema de aprobación del host.

Consulta la documentación de Jev AI para conocer los campos actuales de la API, la configuración inicial de Agent Skill, el formato de respuesta y el comportamiento de los errores. Considera el Skill una interfaz para tomar decisiones, no un sustituto de la autenticación y los permisos de la aplicación.

Protecciones para llamadas a herramientas

Un agente no debería deducir una autorización a partir de texto generado. Antes de ejecutar una herramienta, comprueba la intención propuesta, la política, el alcance y el riesgo. Jev puede aportar una señal tipada para esa comprobación, mientras que la aplicación aplica las reglas.

Una cadena de protección útil es:

1. Normalizar el nombre propuesto de la herramienta y sus argumentos.
2. Formular a Jev una pregunta concreta sobre el riesgo o la aprobación.
3. Aplicar listas de autorización y comprobaciones deterministas de permisos.
4. Enviar los casos dudosos a confirmación o revisión humana.
5. Ejecutar la herramienta con una clave de idempotencia y un registro de auditoría.

Para acciones destructivas o externas, exige que coincidan varios controles en vez de confiar en un único umbral de probabilidad. La capa de políticas debe poder rechazar una acción aunque la señal del modelo parezca segura.

Revisión humana y evaluación

La probabilidad y la confianza son señales útiles para el enrutamiento, no garantías de precisión empresarial. Usa ejemplos históricos para elegir los umbrales y, tras el lanzamiento, supervisa los falsos positivos, los falsos negativos y el volumen de revisiones.

Una política práctica podría ser:

• casos de alta confianza y bajo impacto → continuar automáticamente;
• casos ambiguos o desconocidos → pedir más contexto;
• acciones de gran impacto o destructivas → exigir aprobación;
• entradas no compatibles o mal formadas → fallar de forma segura.

Guarda suficientes metadatos para reproducir una decisión: versión de las preguntas, versión del esquema State, respuesta seleccionada, probabilidades, confianza, acción final y si una persona cambió el resultado. No registres claves API ni datos personales innecesarios.

Lista de comprobación para producción

Antes de publicar una integración de la API de Jev AI con un agente, comprueba lo siguiente:

• Las decisiones del agente tienen espacios de respuesta acotados.
• El State solo contiene el contexto que necesita cada pregunta.
• Choice, Score y Noul se usan para las formas de decisión adecuadas.
• La clave API está en el servidor y fuera de las transcripciones del agente.
• Los tiempos de espera, reintentos, límites de solicitudes y errores de API tienen alternativas seguras.
• Los nombres y argumentos de las herramientas se validan fuera del modelo.
• Las operaciones de gran impacto requieren permisos y, cuando corresponda, aprobación humana.
• Cada llamada a una herramienta tiene una estrategia de idempotencia y una pista de auditoría.
• Los umbrales se prueban con ejemplos representativos y adversariales.
• Los datos de evaluación están separados de los secretos de producción y los datos personales.
• Los registros permiten relacionar la respuesta de Jev con la acción final de la aplicación.

Preguntas frecuentes

¿La API de Jev AI es otra API de chat completions?

No. La API evalúa un State frente a preguntas tipadas y devuelve respuestas estructuradas. Está pensada para convertirse en una decisión dentro de una aplicación, no en una transcripción de chat que deba interpretar una persona.

¿Debería Jev sustituir al LLM de mi agente?

Normalmente, no. Usa un modelo generativo para tareas intensivas en lenguaje y Jev para clasificaciones, enrutamientos, puntuaciones y decisiones de seguridad acotadas. Ambos pueden colaborar en un flujo orquestado.

¿Agent Skill ejecuta las herramientas por mí?

No. Ayuda a los agentes de programación compatibles a plantear preguntas acotadas a Jev. El host del agente, los permisos de la aplicación, las comprobaciones deterministas de políticas y las aprobaciones humanas deben conservar el control de la acción final.

¿Puedo hacer varias preguntas para el agente en una solicitud?

Sí. Varias preguntas pueden leer el mismo State y evaluarse en paralelo. Es útil cuando el agente necesita una ruta, una puntuación de riesgo y una señal de revisión humana antes de decidir qué hacer.

Conclusión

La mejor forma de combinar la API de Jev AI y un agente es asignar una responsabilidad clara a cada componente. El agente y el LLM se encargan de interpretar y planificar. Jev responde preguntas pequeñas y tipadas, respaldadas por probabilidades. El código de la aplicación aplica los permisos y ejecuta la acción final.

Empieza con un flujo de bajo riesgo, valídalo en el entorno de pruebas, conéctalo mediante /v1/systemone y añade el enrutamiento, las protecciones de herramientas y la revisión humana paso a paso. Así obtendrás un agente más fácil de probar, más seguro de operar y más predecible en producción.