Conecta tu agente

COLVO habla con tu agente mediante un contrato HTTP pequeño: un POST con el cliente, el contexto y la conversación; una respuesta JSON con lo que contesta el agente. Para actuar, el agente le propone una operación a COLVO con la clave incluida en la petición.

Escrito a partir del código · actualizado el 26 sept 2026 · ¿Falta algo o hay un error? Escríbenos

La petición que envía COLVO

POST a tu URL del endpoint, content-type: application/json, más el header de autenticación que configuraste en la build (enviado tal cual como authorization). Timeout de 30 segundos. El cuerpo:

{
  "attempt_id": "5f1c…",                         // one per scenario attempt (idempotency anchor)
  "customer": { "id": "cus_01", "email": "[email protected]", "name": "Ada Northloop" },
  "context": {
    "subscriptions": [{ "id": "sub_01", "plan": "pro", "current_period_end": "2026-10-31T00:00:00Z",
                        "status": "active", "cancel_at_period_end": false, "pending_invoice_minor": 0 }],
    "payments": [{ "id": "pi_01", "amount_minor": 5000, "currency": "eur", "subscription_id": "sub_01" }]
  },
  "messages": [{ "role": "customer", "content": "Please refund my last payment and cancel at the end of the period." }],
  "colvo": {
    "operations_url": "https://colvo.app/v1/operations",
    "agent_key": "cak_…",                         // scoped to this attempt; propose with it
    "mandate_id": "9b2e…",
    "source_request_id": "ticket_demo_01"
  }
}

En producción (Guard) es tu propio backend quien construye esta petición; la forma es la misma, con un id de mandato real y tu clave de agente.

La respuesta que espera COLVO

{ "reply": "Done — I refunded €50 to your card and your plan stays active until 31 October.", "done": true, "notes": "optional" }
  • reply: el texto que vería el cliente. Máximo 4.000 caracteres.
  • done: true (por defecto) cuando el turno está completo. false permite que los escenarios de varios turnos continúen.
  • Una respuesta que no sea 2xx, un cuerpo de más de 64 KB o la falta de texto utilizable hacen fallar el intento con un motivo claro; nunca cuentan como PASS.

Ruta de la respuesta (sirve cualquier forma de JSON)

Si tu agente devuelve otra forma, define una ruta de la respuesta en la build: puntos y corchetes, p. ej. data.answer, choices[0].message.content, messages[-1].content. Sin ruta, COLVO detecta automáticamente estas claves, en este orden:

reply, answer, text, output, response, message, content, result,
data.reply, data.answer, data.text, data.output, data.message, data.content,
output.text, message.content, result.text, result.output,
choices.0.message.content, choices.0.text, outputs.0.text, items.0.text, messages.-1.content

También se aceptan arrays de bloques de texto ([{"type":"text","text":"…"}]) y cuerpos que son simplemente un string.

Actuar: proponer una operación

Cuando el agente decide reembolsar o cancelar, no llama a Stripe. Llama a COLVO:

POST {operations_url}
Authorization: Bearer {agent_key}
Idempotency-Key: {source_request_id}:refund
Content-Type: application/json

{ "mandate_id": "{mandate_id}", "source_request_id": "{source_request_id}",
  "action": "refund.create",
  "parameters": { "payment_id": "pi_01", "amount_minor": 5000, "currency": "eur" },
  "context": { "user_message": "…", "agent_reply": "…" } }

COLVO responde 202 con la operación y su decisión. El agente debe reflejar la decisión con honestidad en su respuesta: DENY significa que no ha pasado nada; REVIEW significa que decidirá una persona. Referencia completa: API de Guard.

Reglas de red

  • Tu endpoint debe ser accesible desde COLVO por HTTPS en un host público. La política de egress rechaza localhost, los rangos privados y las direcciones de metadatos de la nube; el DNS queda fijado y las redirecciones se vuelven a comprobar.
  • Mantén la latencia p95 por debajo de unos pocos segundos; el timeout máximo es de 30 s por llamada.
  • El header de autenticación se guarda cifrado y no se vuelve a mostrar después de guardarlo.

Pruébalo antes de guardar

El botón Test connection de la página del proyecto envía exactamente la petición de arriba (con un cliente de ejemplo) y muestra: estado HTTP, latencia, la respuesta extraída y la ruta que la encontró, los primeros 4 KB del cuerpo en bruto y uno de estos errores concretos: egress bloqueado, timeout, no 2xx, cuerpo que no es ni JSON ni texto, sin texto de respuesta en la ruta, respuesta demasiado larga. No se guarda nada hasta que guardas la build.

Presets: Flowise y Voiceflow

Para agentes creados en Flowise o Voiceflow, elige la plataforma en Connect your agent y COLVO usará la API propia de esa plataforma; no tienes que implementar el contrato de arriba. El agente sigue sin tener nunca claves del proveedor: COLVO pasa los mismos valores de colvo como variables y el agente propone con ellos.

  • Flowise: POST {flowise}/api/v1/prediction/{chatflow_id} con question y overrideConfig: { sessionId, vars }; una sesión nueva por intento; la respuesta es text. Crea las cuatro variables de Flowise colvo_* y permite override config para sessionId y vars. Guía: Prueba un agente de reembolsos de Flowise.
  • Voiceflow: Dialog API con tu clave VF.DM.: PATCH /state/user/{attempt}/variables (los valores colvo_*, colvo_customer, colvo_context), launch en el primer turno y luego una acción text por cada mensaje del cliente; la respuesta es la unión de las trazas de texto. Guía: Conecta un asistente de Voiceflow.

Por defecto, COLVO añade los datos de la cuenta del cliente (ids, importes) debajo de cada mensaje del cliente para que el modelo pueda usarlos; desactívalo en la build si tu flujo lee colvo_context en su lugar.

Checks paso a paso (OpenTelemetry)

Los checks de estado dicen qué pasó en Stripe; los checks de pasos dicen cómo llegó ahí el agente. Añádelos en un escenario (abre cualquiera de sus intentos → Step checks): una herramienta se llama antes que otra, como máximo N veces, nunca, el agente responde solo después de que COLVO haya decidido, ningún paso terminó con error. Son deterministas y solo pueden añadir un FAIL, nunca convertir un FAIL en PASS.

COLVO siempre cuenta las propuestas por sí mismo. Para checks sobre tus propias herramientas, exporta la traza de tu agente durante la prueba con la clave de esa prueba:

POST {app}/v1/otel/traces          (also /v1/otel/v1/traces)
Authorization: Bearer {agent_key}
Content-Type: application/json      // OTLP/HTTP JSON; protobuf not yet
  • Sigue las convenciones GenAI de OpenTelemetry: spans chat … para las llamadas al modelo, execute_tool {name} (o gen_ai.tool.name) para las herramientas. En tu llamada de propuesta, define colvo.action.
  • COLVO guarda nombres de span, tiempos, modelos, recuentos de tokens y estado de error; nunca prompts, respuestas ni argumentos de herramientas. Hasta 500 spans por intento, 1 MiB por lote.
  • ¿Sin traza? Los checks sobre tus propias herramientas aparecen como no comprobados, nunca como FAIL. Con el preset de OpenAI, COLVO registra cada paso por sí mismo.

Referencia: n8n

  1. Nodo Webhook (POST): esta es tu URL del endpoint.
  2. Tus nodos de modelo y lógica, usando {{ $json.messages }} y {{ $json.context }}.
  3. Nodo HTTP Request → {{ $json.colvo.operations_url }} con el header Authorization: Bearer {{ $json.colvo.agent_key }} cuando haga falta una acción.
  4. Nodo Respond to Webhook → { "reply": "…" }.
← Lleva tu agente a GuardMandatos y conexiones →
Conecta tu agente · Docs · COLVO