Documentación

Cómo funciona PROMIVO

Los conceptos que necesitas para desplegar un agente, construir un flujo de trabajo y llamar a la plataforma desde tus propios sistemas.

Agentes y versiones

Un agente es una ficha del catálogo más una o más versiones inmutables. Cada versión lleva el prompt de sistema, la configuración del modelo, las herramientas que puede llamar, sus esquemas de entrada y salida, los límites de ejecución y su techo de riesgo automático.

Publicar una actualización crea una versión nueva y mueve el puntero actual. Una versión existente nunca se modifica, así que una ejecución en curso conserva el comportamiento con el que empezó.

Permisos y riesgo

Cada herramienta declara un nivel de riesgo. Cada versión de agente declara el nivel máximo que puede ejecutar sin una persona.

READObtiene, busca, resume. No cambia nada.
WRITEEnviar un correo, publicar una actualización, crear o actualizar un registro.
DESTRUCTIVEBorrar datos o gastar dinero.

Una llamada a herramienta por encima del techo se rechaza, se registra como tarea pendiente de aprobación y se le informa al modelo como no realizada. La ejecución continúa; el efecto no ocurre.

Nodos de flujo

Nodo	Qué hace
`TRIGGER`	Punto de entrada. Manual, webhook, programado o por evento.
`AI`	Ejecuta un agente con una plantilla de entrada interpolada.
`HTTP`	Llama a un endpoint HTTP público. Los rangos privados están bloqueados.
`CONDITION`	Bifurca según un valor del contexto de ejecución.
`TRANSFORM`	Reorganiza los datos en un objeto nuevo.
`EMAIL`	Envía un correo a través del proveedor configurado.
`WEBHOOK`	Envía hacia fuera una carga JSON firmada.
`DELAY`	Espera hasta 300 segundos dentro de una ejecución.
`DATABASE`	Registra una nota o lee las ejecuciones recientes.
`OUTPUT`	Define el resultado final del flujo.

Plantillas

La configuración del nodo interpola valores del contexto de ejecución. No hay evaluación de expresiones, así que una plantilla nunca puede ejecutar código.

{{trigger.email}}                  → the trigger payload
{{steps.qualify.output.score}}     → an earlier node result
{{workflow.name}}                  → workflow metadata

API pública

Crea una clave con alcance limitado en la Página de claves de API. El secreto se muestra una sola vez; solo se guarda su hash.

POST /api/agents/run
Authorization: Bearer pmv_live_…
Content-Type: application/json

{ "agentId": "<uuid>", "input": { "topic": "Q4 planning" } }

Toda respuesta usa el mismo sobre:

{ "ok": true,  "data": { … } }
{ "ok": false, "error": { "code": "…", "message": "…" } }

Endpoints

GET /api/agents
POST /api/agents/run
GET /api/workflows
POST /api/workflows
POST /api/workflows/:id/run
GET /api/executions
GET /api/executions/:id
GET /api/usage

Disparadores de webhook

Un flujo con webhook recibe un token público y un secreto de firma que se muestra una sola vez al crearlo. Firma el cuerpo en bruto con ese secreto.

POST /api/webhooks/workflow/<token>
x-promivo-secret:    <signing secret>
x-promivo-signature: <hex HMAC-SHA256 of the raw body>
x-idempotency-key:   <optional; makes redelivery safe>

{ "email": "lead@example.com", "message": "…" }