API de agentes de IA

La API de agentes de IA gestiona agentes de IA solo de generación: objetos reutilizables que leen un contexto acotado y devuelven datos estructurados validados para que los usen tus journeys y tareas de catálogo. Un agente no tiene herramientas ni acciones: nunca envía, ramifica ni escribe por sí mismo. Consulta los conceptos en la guía del dashboard de agentes de IA.

Esta API refleja la sección Configuración → Agentes de IA del dashboard. Úsala para automatizar la creación de agentes, registrar claves de proveedores propios (BYO), simular un agente con un contexto de ejemplo y consultar los rastros de ejecución.

Todos los endpoints de esta página son relativos a la URL base: https://api-eu1.joryio.com. Consulta el resumen de la API.

Autenticación

Cada solicitud se autentica con una clave de API que tenga el scope correspondiente o con una sesión del dashboard (JWT). Los agentes tienen ámbito de espacio de trabajo: una clave solo puede ver y editar los agentes de su propio espacio de trabajo.

Authorization: Bearer your_api_key_or_jwt
Content-Type: application/json

Scopes por endpoint

Los endpoints de lectura necesitan ai_agents:read y los de escritura, ai_agents:write. Las sesiones del dashboard también pueden usar el scope de rol compartido por las secciones de IA, settings:read / settings:write; cualquiera de ellos concede acceso.

Endpoint	Scope
`POST /ai-agents`	`ai_agents:write` (or `settings:write`)
`GET /ai-agents`	`ai_agents:read` (or `settings:read`)
`GET /ai-agents/{id}`	`ai_agents:read` (or `settings:read`)
`PUT /ai-agents/{id}`	`ai_agents:write` (or `settings:write`)
`POST /ai-agents/{id}/archive`	`ai_agents:write` (or `settings:write`)
`DELETE /ai-agents/{id}`	`ai_agents:write` (or `settings:write`)
`POST /ai-agents/{id}/test`	`ai_agents:write` (or `settings:write`)
`GET /ai-agents/{id}/runs`	`ai_agents:read` (or `settings:read`)
`GET /ai-agents/provider-keys`	`ai_agents:read` (or `settings:read`)
`PUT /ai-agents/provider-keys/{provider}`	`ai_agents:write` (or `settings:write`)
`DELETE /ai-agents/provider-keys/{provider}`	`ai_agents:write` (or `settings:write`)
`POST /ai-agents/enrichment/run`	`ai_agents:write` (or `settings:write`)
`GET /ai-agents/enrichment/jobs`	`ai_agents:read` (or `settings:read`)
`GET /ai-agents/enrichment/jobs/{jobId}`	`ai_agents:read` (or `settings:read`)

Conceptos básicos

Modo de modelo y proveedor

El modelMode de un agente es managed o byo:

managed: modelo Claude alojado por Joryio. El provider es joryio. Se factura un crédito por ejecución.
byo: tu propia clave. El provider es uno de anthropic, openai, google, azure o bedrock. Primero registra la clave mediante los endpoints de claves de proveedor. Se factura una pequeña tarifa plana de plataforma por ejecución.

Esquema de salida

outputSchema.type puede ser string, number, boolean o json. Para json, proporciona una matriz fields de { name, type, description? }, donde type es un valor primitivo. Establece includeExplanation: true para capturar el razonamiento del modelo en un campo explanation.

Selectores de contexto

contextSelectors funciona mediante inclusión explícita: el agente no lee nada que no aparezca aquí. Incluye attributeKeys, segmentIds, catalogFields, requiredCatalogFields (campos de catálogo que deben existir; el enriquecimiento omite, y nunca factura, una fila a la que le falte alguno), includeBrandVoice, includeRecentEngagement y maskPiiKeys (claves que se enmascaran antes de que el contexto llegue al modelo; la información personal marcada globalmente en Atributos personalizados también se enmascara siempre).

Resultados de ejecución

Cada ejecución termina en uno de estos resultados: success, fallback, timeout, rate_limited, invalid_config o budget_exceeded. Consulta el contrato de errores.

Crear un agente

Endpoint

POST /ai-agents

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`name`	cadena	Sí	Nombre legible, máximo 200 caracteres.
`description`	cadena	No	Descripción opcional, máximo 1000 caracteres.
`tags`	cadena[]	No	Nombres de etiquetas del espacio de trabajo para filtrar u organizar, hasta 50 de 60 caracteres como máximo.
`instructions`	cadena	Sí	Objetivo e instrucciones del sistema, con plantilla Liquid; máximo 20 000 caracteres.
`modelMode`	cadena	No	`managed` (predeterminado) o `byo`.
`provider`	cadena	No	`joryio`, `anthropic`, `openai`, `google`, `azure`, `bedrock`. Para managed el predeterminado es `joryio`; para BYO, `anthropic`.
`model`	cadena	No	ID concreto de modelo, por ejemplo `claude-opus-4-8`.
`thinkingLevel`	cadena	No	`minimal`, `low`, `medium` o `high`.
`contextSelectors`	objeto	No	Lo que el agente puede leer, mediante inclusión explícita.
`outputSchema`	objeto	No	Estructura de salida a la que se restringe el modelo. Predeterminado: `{ "type": "string" }`.
`fallbackValue`	cualquiera	No	Valor devuelto cuando una ejecución falla.
`dailyCap`	entero	No	Límite diario de invocaciones por agente, predeterminado 250 000, mínimo 0.
`guardrails`	objeto	No	`maxOutputTokens`, `timeoutMs`, `retryOnTransient`.

Solicitud de ejemplo

curl -X POST https://api-eu1.joryio.com/ai-agents \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cart subject-line writer",
    "instructions": "Write a short, upbeat email subject line for the abandoned cart. Max 60 characters.",
    "modelMode": "managed",
    "contextSelectors": {
      "attributeKeys": ["first_name", "cart_total"],
      "includeBrandVoice": true
    },
    "outputSchema": {
      "type": "json",
      "fields": [{ "name": "subject", "type": "string" }],
      "includeExplanation": true
    },
    "fallbackValue": { "subject": "You left something behind" },
    "dailyCap": 50000,
    "guardrails": { "timeoutMs": 20000, "retryOnTransient": true }
  }'

Respuesta

{
  "id": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "organizationId": "org_123",
  "workspaceId": "ws_456",
  "name": "Cart subject-line writer",
  "description": null,
  "status": "active",
  "instructions": "Write a short, upbeat email subject line for the abandoned cart. Max 60 characters.",
  "modelMode": "managed",
  "provider": "joryio",
  "model": "",
  "thinkingLevel": null,
  "contextSelectors": {
    "attributeKeys": ["first_name", "cart_total"],
    "includeBrandVoice": true
  },
  "outputSchema": {
    "type": "json",
    "fields": [{ "name": "subject", "type": "string" }],
    "includeExplanation": true
  },
  "fallbackValue": { "subject": "You left something behind" },
  "dailyCap": 50000,
  "guardrails": { "timeoutMs": 20000, "retryOnTransient": true },
  "createdBy": "user_789",
  "createdAt": "2026-07-11T09:00:00.000Z",
  "updatedAt": "2026-07-11T09:00:00.000Z"
}

Listar agentes

Endpoint

GET /ai-agents

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`status`	cadena	-	Filtro opcional: `active` o `archived`.

Los agentes se devuelven ordenados por última actualización, del más reciente al más antiguo.

Solicitud de ejemplo

curl -X GET "https://api-eu1.joryio.com/ai-agents?status=active" \
  -H "Authorization: Bearer your_api_key"

Respuesta

[
  {
    "id": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "name": "Cart subject-line writer",
    "status": "active",
    "modelMode": "managed",
    "provider": "joryio",
    "dailyCap": 50000,
    "updatedAt": "2026-07-11T09:00:00.000Z"
  }
]

Obtener un agente

Endpoint

GET /ai-agents/{id}

El parámetro de ruta {id} es el UUID del agente.

Solicitud de ejemplo

curl -X GET https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer your_api_key"

Devuelve el objeto de agente completo, con la misma estructura que la respuesta de creación. Devuelve 404 si el agente no existe en este espacio de trabajo.

Actualizar un agente

Endpoint

PUT /ai-agents/{id}

Actualización parcial: envía solo los campos que quieras cambiar. Se aceptan todos los campos de creación, además de status (active o archived).

Solicitud de ejemplo

curl -X PUT https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyCap": 100000,
    "guardrails": { "timeoutMs": 15000, "retryOnTransient": false }
  }'

Devuelve el objeto de agente actualizado.

Archivar un agente

Archiva un agente de forma reversible: status pasa a archived, lo que detiene su uso pero conserva su historial de ejecuciones.

Endpoint

POST /ai-agents/{id}/archive

Solicitud de ejemplo

curl -X POST https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/archive \
  -H "Authorization: Bearer your_api_key"

Devuelve el objeto de agente archivado ("status": "archived").

Eliminar un agente

Endpoint

DELETE /ai-agents/{id}

Solicitud de ejemplo

curl -X DELETE https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer your_api_key"

Respuesta

{ "success": true }

Probar un agente (vista previa)

Simula el agente con un contexto de ejemplo que proporciones. La ejecución usa una clave de ejecución nueva y la superficie test, de modo que nunca cuenta contra un journey real. Devuelve solo el resultado que verá el cliente, sin campos de medición.

Endpoint

POST /ai-agents/{id}/test

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`attributes`	objeto	No	Atributos de contacto de ejemplo, indexados por nombre.
`segmentMemberships`	cadena[]	No	Pertenencias a segmentos de ejemplo.
`catalogRecord`	objeto	No	Registro de catálogo o entidad de ejemplo que se va a enriquecer.
`engagement`	objeto	No	Resumen de interacción reciente de ejemplo.

Solicitud de ejemplo

curl -X POST https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/test \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": { "first_name": "Dana", "cart_total": 249.90 },
    "segmentMemberships": ["vip"]
  }'

Respuesta

{
  "outcome": "success",
  "output": { "subject": "Dana, your cart misses you" },
  "explanation": "Used the first name and an upbeat tone from the brand voice."
}

outcome es uno de success, fallback, timeout, rate_limited, invalid_config o budget_exceeded. explanation es null cuando el esquema no incluye una explicación.

Listar ejecuciones de un agente

Devuelve los rastros de ejecución recientes de un agente, del más reciente al más antiguo.

Endpoint

GET /ai-agents/{id}/runs

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`limit`	número	`50`	Filas que se devolverán, de 1 a 200.

Solicitud de ejemplo

curl -X GET "https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/runs?limit=25" \
  -H "Authorization: Bearer your_api_key"

Respuesta

{
  "rows": [
    {
      "id": "run_abc123",
      "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
      "surface": "journey",
      "provider": "joryio",
      "model": "claude-opus-4-8",
      "modelMode": "managed",
      "inputTokens": 420,
      "outputTokens": 28,
      "latencyMs": 1180,
      "outcome": "success",
      "output": { "subject": "Dana, your cart misses you" },
      "explanation": "Used the first name and an upbeat tone.",
      "error": null,
      "createdAt": "2026-07-11T09:05:00.000Z"
    }
  ]
}

El rastro solo guarda referencias de entrada (qué ejecución, nodo, registro o usuario), nunca el texto sin procesar del prompt.

Listar claves de proveedores BYO

Devuelve las claves registradas de proveedores propios para el espacio de trabajo. Los valores de las credenciales nunca se devuelven; el objeto credentials siempre está vacío.

Endpoint

GET /ai-agents/provider-keys

Solicitud de ejemplo

curl -X GET https://api-eu1.joryio.com/ai-agents/provider-keys \
  -H "Authorization: Bearer your_api_key"

Respuesta

[
  {
    "id": "key_111",
    "provider": "openai",
    "credentials": {},
    "label": "Production OpenAI",
    "status": "active",
    "lastUsedAt": "2026-07-11T08:00:00.000Z",
    "lastError": null,
    "createdAt": "2026-07-01T00:00:00.000Z",
    "updatedAt": "2026-07-11T08:00:00.000Z"
  }
]

Crear o actualizar una clave de proveedor BYO

Crea o reemplaza la clave de un proveedor. Hay una clave por cada (workspace, provider). El proveedor administrado joryio no acepta clave y se rechaza.

Endpoint

PUT /ai-agents/provider-keys/{provider}

El parámetro de ruta {provider} es uno de anthropic, openai, google, azure o bedrock.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`credentials`	objeto	Sí	Valores de credenciales específicos del proveedor (por ejemplo, `{ "apiKey": "..." }`; Azure y Bedrock requieren más). Se cifran en reposo y nunca se devuelven.
`label`	cadena	No	Etiqueta opcional, máximo 120 caracteres.

Solicitud de ejemplo

curl -X PUT https://api-eu1.joryio.com/ai-agents/provider-keys/openai \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "sk-your-openai-key" },
    "label": "Production OpenAI"
  }'

Respuesta

{
  "id": "key_111",
  "provider": "openai",
  "credentials": {},
  "label": "Production OpenAI",
  "status": "active",
  "lastUsedAt": null,
  "lastError": null,
  "createdAt": "2026-07-11T09:10:00.000Z",
  "updatedAt": "2026-07-11T09:10:00.000Z"
}

Eliminar una clave de proveedor BYO

Endpoint

DELETE /ai-agents/provider-keys/{provider}

Solicitud de ejemplo

curl -X DELETE https://api-eu1.joryio.com/ai-agents/provider-keys/openai \
  -H "Authorization: Bearer your_api_key"

Respuesta

{ "success": true }

Ejecutar enriquecimiento de catálogo

Ejecuta un agente solo de generación sobre los registros de una entidad personalizada y escribe cada salida en un campo de destino: descripciones de producto, etiquetas o una categoría normalizada. El trabajo es asíncrono y en cola: este endpoint crea un trabajo (status: queued), lo encola y devuelve de inmediato; un catálogo grande, de hasta 100 000 filas, se procesa fuera de la ruta de solicitud. Consulta periódicamente obtener un trabajo de enriquecimiento para ver el progreso. El trabajo es idempotente por registro (la clave de ejecución es jobId:recordId), por lo que un reintento nunca vuelve a cobrar un registro ya enriquecido.

Endpoint

POST /ai-agents/enrichment/run

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`agentId`	cadena	Sí	Agente que se ejecutará; debe estar activo en este espacio de trabajo.
`entityDefinitionId`	cadena	Sí	Definición de entidad personalizada cuyos registros se enriquecerán.
`targetField`	cadena	Sí	Campo de registro en el que se escribirá la salida; debe estar declarado en la entidad.
`filter`	objeto	No	Filtro opcional al estilo MongoDB que limita los registros enriquecidos.
`limit`	entero	No	Máximo de registros que procesará el trabajo, hasta 100 000 y limitado estrictamente por el servidor.

Solicitud de ejemplo

curl -X POST https://api-eu1.joryio.com/ai-agents/enrichment/run \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "entityDefinitionId": "product",
    "targetField": "ai_description",
    "filter": { "category": "shoes" },
    "limit": 200
  }'

Respuesta

El trabajo en cola. status es queued al enviarlo; los recuentos se completan mientras se ejecuta. Consulta periódicamente obtener un trabajo de enriquecimiento para seguir su finalización.

{
  "jobId": "job_9a8b7c",
  "status": "queued",
  "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "entityDefinitionId": "product",
  "targetField": "ai_description",
  "counts": {
    "total": 200,
    "processed": 0,
    "succeeded": 0,
    "failed": 0,
    "skipped": 0
  },
  "error": null,
  "createdAt": "2026-07-11T09:20:00.000Z",
  "updatedAt": "2026-07-11T09:20:00.000Z"
}

Obtener un trabajo de enriquecimiento

Consulta el estado y los recuentos de un trabajo de enriquecimiento.

Endpoint

GET /ai-agents/enrichment/jobs/{jobId}

El parámetro de ruta {jobId} es el ID de trabajo devuelto por ejecutar enriquecimiento de catálogo.

Solicitud de ejemplo

curl -X GET https://api-eu1.joryio.com/ai-agents/enrichment/jobs/job_9a8b7c \
  -H "Authorization: Bearer your_api_key"

Respuesta

status es uno de queued, running, completed o failed. error se completa solo cuando el trabajo entero falla.

{
  "jobId": "job_9a8b7c",
  "status": "completed",
  "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "entityDefinitionId": "product",
  "targetField": "ai_description",
  "counts": {
    "total": 200,
    "processed": 200,
    "succeeded": 194,
    "failed": 2,
    "skipped": 4
  },
  "error": null,
  "createdAt": "2026-07-11T09:20:00.000Z",
  "updatedAt": "2026-07-11T09:22:30.000Z"
}

Devuelve 404 si el trabajo no existe en este espacio de trabajo. Requiere ai_agents:read (o settings:read).

Listar trabajos de enriquecimiento

Devuelve los trabajos de enriquecimiento recientes del espacio de trabajo, del más reciente al más antiguo, para consultar el progreso y el historial.

Endpoint

GET /ai-agents/enrichment/jobs

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`limit`	entero	`20`	Filas que se devolverán, de la más reciente a la más antigua.

Solicitud de ejemplo

curl -X GET "https://api-eu1.joryio.com/ai-agents/enrichment/jobs?limit=20" \
  -H "Authorization: Bearer your_api_key"

Respuesta

Una matriz de trabajos, cada uno con la misma estructura que obtener un trabajo de enriquecimiento.

[
  {
    "jobId": "job_9a8b7c",
    "status": "completed",
    "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "entityDefinitionId": "product",
    "targetField": "ai_description",
    "counts": {
      "total": 200,
      "processed": 200,
      "succeeded": 194,
      "failed": 2,
      "skipped": 4
    },
    "error": null,
    "createdAt": "2026-07-11T09:20:00.000Z",
    "updatedAt": "2026-07-11T09:22:30.000Z"
  }
]

Requiere ai_agents:read (o settings:read).

Respuestas de error

Todos los errores comparten la estructura estándar: no existe un vocabulario separado de códigos de error legibles por máquina; usa el estado HTTP junto con el campo message. Consulta respuesta de error en el resumen de la API.

{
  "statusCode": 404,
  "message": "AI agent 8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b not found",
  "timestamp": "2026-07-11T09:20:00.000Z",
  "path": "/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b"
}

Estados destacables de esta API:

Estado	Cuándo
`400`	Configuración no válida; por ejemplo, `"instructions are required"`, `"No BYO key configured for provider 'openai' - add a key before using it in BYO mode"`, `"status must be one of: active, draft, archived"`
`401`	Falta la clave de API o no es válida
`403`	A la clave le falta el scope requerido `ai_agents:read` / `ai_agents:write`
`404`	No se encontró el agente, el trabajo de enriquecimiento o la clave de proveedor BYO

Autenticación​

Scopes por endpoint​

Conceptos básicos​

Modo de modelo y proveedor​

Esquema de salida​

Selectores de contexto​

Resultados de ejecución​

Crear un agente​

Endpoint​

Cuerpo de la solicitud​

Solicitud de ejemplo​

Respuesta​

Listar agentes​

Endpoint​

Parámetros de consulta​

Solicitud de ejemplo​

Respuesta​

Obtener un agente​

Endpoint​

Solicitud de ejemplo​

Actualizar un agente​

Endpoint​

Solicitud de ejemplo​

Archivar un agente​

Endpoint​

Solicitud de ejemplo​

Eliminar un agente​

Endpoint​

Solicitud de ejemplo​

Respuesta​

Probar un agente (vista previa)​

Endpoint​

Cuerpo de la solicitud​

Solicitud de ejemplo​

Respuesta​

Listar ejecuciones de un agente​

Endpoint​

Parámetros de consulta​

Solicitud de ejemplo​

Respuesta​

Listar claves de proveedores BYO​

Endpoint​

Solicitud de ejemplo​

Respuesta​

Crear o actualizar una clave de proveedor BYO​

Endpoint​

Cuerpo de la solicitud​

Solicitud de ejemplo​

Respuesta​

Eliminar una clave de proveedor BYO​

Endpoint​

Solicitud de ejemplo​

Respuesta​

Ejecutar enriquecimiento de catálogo​

Endpoint​

Cuerpo de la solicitud​

Solicitud de ejemplo​

Respuesta​

Obtener un trabajo de enriquecimiento​

Endpoint​

Solicitud de ejemplo​

Respuesta​

Listar trabajos de enriquecimiento​

Endpoint​

Parámetros de consulta​

Solicitud de ejemplo​

Respuesta​

Respuestas de error​

Siguientes pasos​

Autenticación

Scopes por endpoint

Conceptos básicos

Modo de modelo y proveedor

Esquema de salida

Selectores de contexto

Resultados de ejecución

Crear un agente

Endpoint

Cuerpo de la solicitud

Solicitud de ejemplo

Respuesta

Listar agentes

Endpoint

Parámetros de consulta

Solicitud de ejemplo

Respuesta

Obtener un agente

Endpoint

Solicitud de ejemplo

Actualizar un agente

Endpoint

Solicitud de ejemplo

Archivar un agente

Endpoint

Solicitud de ejemplo

Eliminar un agente

Endpoint

Solicitud de ejemplo

Respuesta

Probar un agente (vista previa)

Endpoint

Cuerpo de la solicitud

Solicitud de ejemplo

Respuesta

Listar ejecuciones de un agente

Endpoint

Parámetros de consulta

Solicitud de ejemplo

Respuesta

Listar claves de proveedores BYO

Endpoint

Solicitud de ejemplo

Respuesta

Crear o actualizar una clave de proveedor BYO

Endpoint

Cuerpo de la solicitud

Solicitud de ejemplo

Respuesta

Eliminar una clave de proveedor BYO

Endpoint

Solicitud de ejemplo

Respuesta

Ejecutar enriquecimiento de catálogo

Endpoint

Cuerpo de la solicitud

Solicitud de ejemplo

Respuesta

Obtener un trabajo de enriquecimiento

Endpoint

Solicitud de ejemplo

Respuesta

Listar trabajos de enriquecimiento

Endpoint

Parámetros de consulta

Solicitud de ejemplo

Respuesta

Respuestas de error

Siguientes pasos