Documentación de COLVO

COLVO prueba los agentes de IA antes del lanzamiento y protege sus acciones reales en producción, verificando el resultado real en lugar de la respuesta del agente. Esta es la documentación para desarrolladores: el contrato HTTP con tu agente, la API que llaman tu backend y tu agente, la CLI y cómo se toman las decisiones y los veredictos.

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

Dos módulos, un solo contrato

• COLVO Test reproduce escenarios en un mundo Stripe simulado y aislado. Tu agente recibe un cliente, sus suscripciones y pagos y un mensaje, y responde como lo haría en producción. Cuando quiere actuar, le propone una operación a COLVO. El veredicto se calcula a partir del estado resultante: PASS, FAIL o INCONCLUSIVE.
• COLVO Guard se coloca delante de tu proveedor real. Tu backend de confianza registra un mandato (quién puede hacer qué y con qué límites); el agente propone; COLVO decide ALLOW / REVIEW / HOLD / DENY, ejecuta una sola vez y verifica contra el proveedor.

El agente usa el mismo contrato pequeño en ambos módulos y nunca tiene credenciales de escritura del proveedor.

Por dónde empezar

1. Primeros pasos: de la invitación a la primera ejecución en verde.
2. Conecta tu agente: la petición que envía COLVO y la respuesta que espera.
3. Mandatos y conexiones y luego la API de Guard: cuando pases a producción.
4. CLI y bloqueo en CI: haz que la build falle ante un FAIL.

URL base y versiones

Todos los endpoints están bajo https://colvo.app/v1. Los cuerpos son JSON. Los cambios incompatibles reciben un nuevo prefijo; pueden aparecer campos nuevos en cualquier momento, así que ignora las claves que no conozcas.

Autenticación

Dos credenciales, ambas enviadas como Authorization: Bearer …:

• Clave de backend (cak_…, scope backend): tu servidor de confianza. Registra mandatos, inicia ejecuciones y gestiona la configuración.
• Clave de agente (cak_…, scope agent): el propio agente. Solo puede proponer operaciones y leer su estado. Durante una ejecución de prueba, COLVO le pasa al agente una clave por intento en la petición, así que un agente en pruebas no necesita ningún secreto guardado.

Los usuarios de la consola actúan con su sesión; el rol en la organización (owner / editor / viewer) decide qué pueden cambiar. Las claves se muestran una sola vez, se guardan como hash y puedes revocarlas o rotarlas desde Ajustes.