Integraciones externas para agentes de IA

Qué permite esta integración

Una Integración externa es una credencial revocable asociada a la cuenta activa de Bulest. Puede limitarse a agentes concretos y a capacidades específicas. La API pública usa como base:

https://bulest.co/api/v1/external

Dependiendo de los permisos concedidos, una herramienta puede:

• Consultar agentes y su configuración pública.
• Explorar productos y variantes de la tienda vinculada a cada agente.
• Leer fragmentos y preparar cambios sin tocar inmediatamente al agente activo.
• Probar un borrador con texto, imágenes, audio, video o archivos en el Chat de pruebas.
• Solicitar aprobación o aplicar un borrador de acuerdo con la política elegida.
• Consultar en la Caja Negra la actividad atribuida a esa integración.

1. Crear el acceso en Bulest

1. Abre Perfil → Integraciones externas.
2. Selecciona Nueva integración y ponle un nombre reconocible, por ejemplo “Codex — conocimiento de ventas”.
3. Elige los permisos y los agentes a los que podrá acceder.
4. Define cómo manejará los cambios: solo borradores, aprobación humana o aplicación directa.
5. Copia el token. Bulest lo muestra completo una sola vez.

Permisos disponibles

2. Autenticación

Envía el token en el encabezado HTTP Authorization con el esquema Bearer:

curl https://bulest.co/api/v1/external/guide \
  -H "Authorization: Bearer BULEST_TOKEN" \
  -H "Accept: application/json"

Para solicitudes con cuerpo añade Content-Type: application/json. El token no se admite en parámetros de consulta ni dentro del JSON.

3. Descubrir capacidades

El primer llamado recomendado es GET /guide. Devuelve los permisos, la política, los agentes visibles y un mapa de las operaciones disponibles para ese token. GET /capabilities es un alias compatible.

{
  "success": true,
  "integration": {
    "id": "INTEGRATION_ID",
    "name": "Codex — conocimiento de ventas",
    "permissions": ["agents.read", "fragments.read", "fragments.draft"],
    "agent_scope_mode": "selected",
    "change_policy": "approval_required"
  },
  "agents": [
    { "id": "AGENT_ID", "name": "Ventas", "revision": "REVISION_SHA256" }
  ],
  "guide": { "base_path": "/api/v1/external", "endpoints": {} }
}

Una herramienta debe tratar esta respuesta como la autoridad del acceso y no intentar operar sobre agentes o capacidades ausentes.

4. Leer agentes y fragmentos

curl https://bulest.co/api/v1/external/agents/AGENT_ID/fragments \
  -H "Authorization: Bearer BULEST_TOKEN"

Comprueba el contexto antes de editar

Con GET /agents/AGENT_ID/configuration-context la integración puede detectar, por ejemplo, una instancia desconectada, una tienda ausente, un calendario eliminado o un departamento sin asesores disponibles. Los IDs se incluyen para operaciones precisas, pero los diagnósticos usan nombres y mensajes legibles.

curl https://bulest.co/api/v1/external/agents/AGENT_ID/configuration-context \
  -H "Authorization: Bearer BULEST_TOKEN"

5. Consultar el catálogo y crear fragmentos de producto

Usa GET /agents/AGENT_ID/catalog para consultar exclusivamente la tienda vinculada al agente. La ruta admite q, limit y cursor; no acepta un store_id elegido por el cliente.

curl "https://bulest.co/api/v1/external/agents/AGENT_ID/catalog?q=camiseta&limit=30" \
  -H "Authorization: Bearer BULEST_TOKEN"

Cada producto distingue claramente sus IDs y entrega una plantilla válida para el endpoint de fragmentos:

{
  "product_id": "9123456789",
  "shopify_product_gid": "gid://shopify/Product/9123456789",
  "title": "Camiseta clásica",
  "variants": [{
    "variant_id": "4987654321",
    "shopify_variant_gid": "gid://shopify/ProductVariant/4987654321",
    "title": "Negra / M",
    "price": "79.90",
    "fragment_meta_patch": {
      "variant_id": "4987654321",
      "variant_title": "Negra / M"
    }
  }],
  "fragment_template": {
    "title": "Camiseta clásica",
    "content": "Camiseta de algodón...",
    "type": "product",
    "active": true,
    "meta": {
      "store_id": "12",
      "store_domain": "tienda.myshopify.com",
      "product_id": "9123456789",
      "product_title": "Camiseta clásica",
      "image_url": "https://cdn.shopify.com/...",
      "product_image": "https://cdn.shopify.com/...",
      "product_url": "https://tienda.myshopify.com/products/camiseta-clasica"
    }
  }
}

Para crear el fragmento, copia fragment_template en el campo fragment y añade la base_revision vigente. Si el fragmento debe representar una variante concreta, combina su fragment_meta_patch con fragment_template.meta.

6. Preparar cambios como borradores

Las operaciones sobre fragmentos nunca cambian por sí solas al agente activo. Construyen un borrador con el snapshot completo resultante. Esto permite probarlo y revisarlo antes de aplicarlo.

Crear un fragmento

{
  "base_revision": "REVISION_SHA256",
  "summary": "Añade la política de envíos nacionales",
  "fragment": {
    "title": "Envíos nacionales",
    "type": "text",
    "content": "Los envíos tardan entre 2 y 5 días hábiles.",
    "active": true,
    "meta": {}
  }
}

Editar o eliminar un fragmento

Snapshot completo

Para cambiar varios fragmentos o también la configuración pública del agente, usa POST /agents/AGENT_ID/drafts:

{
  "base_revision": "REVISION_SHA256",
  "summary": "Reorganiza el conocimiento comercial",
  "agent": {
    "description": "Asistente comercial de la tienda",
    "delay": 2000
  },
  "fragments": [
    {
      "id": "FRAGMENT_ID_EXISTENTE",
      "title": "Envíos nacionales",
      "type": "text",
      "content": "Los envíos tardan entre 2 y 5 días hábiles.",
      "active": true,
      "meta": {}
    }
  ]
}

Cuando envíes un snapshot completo, conserva todos los fragmentos que no deseas eliminar. Bulest fija la cuenta, autoría y fechas; el cliente no debe suplantar esos campos.

7. Probar el borrador en el Chat de pruebas

El envío es asíncrono. La API responde 202 Accepted con un session_id y un message_id.

{
  "agent_id": "AGENT_ID",
  "draft_id": "DRAFT_ID",
  "client_message_id": "scenario-shipping-001",
  "message": {
    "type": "text",
    "content": "¿Cuánto tarda mi envío?"
  }
}

Para continuar, envía el session_id. Bulest recuerda y revalida el mismo borrador; no permite cambiarlo dentro de esa conversación.

{
  "session_id": "SESSION_ID",
  "message": {
    "type": "text",
    "content": "¿Y para Medellín?"
  }
}

Multimedia

Los tipos admitidos son image, audio, video y file. El mensaje puede llevar una leyenda y el archivo en base64:

{
  "agent_id": "AGENT_ID",
  "draft_id": "DRAFT_ID",
  "message": {
    "type": "image",
    "caption": "¿Este producto está disponible?",
    "filename": "producto.jpg",
    "mime_type": "image/jpeg",
    "base64": "/9j/4AAQSkZJRgABAQ..."
  }
}

Consultar respuestas

GET /test-chat/sessions/SESSION_ID/messages?after=0

Usa el cursor devuelto como próximo valor de after. Continúa consultando mientras is_terminal sea falso; estados como waiting_for_tool indican que todavía llegarán resultados. Cada sesión aísla su memoria por integración, agente y session_id.

Las herramientas con posibles escrituras pueden añadir mensajes tool_activity cuando se ejecutan en modo de prueba. Son evidencia creada por Bulest —API alcanzada, datos seguros, validaciones y efectos omitidos— y no forman parte de conversation ni del texto del agente.

{
  "sender": "system",
  "type": "tool_activity",
  "visibility": "tester",
  "tool_activity": {
    "operation": "checkout.create",
    "status": "simulated_success",
    "title": "Checkout simulado",
    "summary": "El checkout fue validado y no se creó un pedido real.",
    "validated": ["Catálogo y precios vigentes"],
    "suppressed_effects": ["Crear el pedido", "Modificar inventario"]
  }
}

POST /test-chat/sessions/SESSION_ID/reset

client_message_id evita duplicados si debes reintentar un envío. Dentro de una sesión se procesa un turno a la vez; sesiones diferentes sí pueden ejecutarse en paralelo.

8. Aplicar o enviar a aprobación

Cuando el resultado sea correcto, llama:

POST /drafts/DRAFT_ID/apply

Las dos últimas políticas requieren el permiso fragments.apply. Un conflicto de revisión debe resolverse leyendo de nuevo al agente y reconstruyendo el borrador; nunca se fuerza la escritura.

9. Actividad y Caja Negra

Consulta la actividad atribuida exclusivamente a la integración:

GET /activity?limit=50

Bulest registra la preparación y aplicación de borradores, creación o archivado de agentes y ejecuciones del Chat de pruebas. La Caja Negra identifica a la integración por nombre, pero no guarda el token ni copia el contenido completo de fragmentos o conversaciones.

Referencia rápida de endpoints

La referencia machine-readable está disponible en /docs/openapi.json.

Errores y reglas de seguridad

• 401: token ausente, inválido, vencido o revocado.
• 403: permiso, agente autorizado o política insuficiente.
• 409: conflicto de revisión, versión, sesión o estado del borrador.
• 410: borrador o sesión de prueba vencida.
• 429: demasiadas solicitudes; respeta el tiempo de espera antes de reintentar.

No reintentes automáticamente una mutación si no sabes si el servidor la alcanzó a procesar. Vuelve a consultar el recurso y decide con su estado actual.