Documentação

Como a PROMIVO funciona

Os conceitos necessários para ativar um agente, montar um fluxo de trabalho e chamar a plataforma a partir dos seus próprios sistemas.

Agentes e versões

Um agente é um registro no catálogo mais uma ou mais versões imutáveis. Uma versão carrega o prompt de sistema, a configuração do modelo, as ferramentas que ele pode chamar, os esquemas de entrada e saída, os limites de execução e o seu limite de risco automático.

Publicar uma atualização cria uma nova versão e move o ponteiro atual. Uma versão existente nunca é modificada, então uma execução em andamento mantém o comportamento com que começou.

Permissões e risco

Cada ferramenta declara um nível de risco. Uma versão de agente declara o nível mais alto que pode executar sem uma pessoa.

READBusca, pesquisa, resume. Não altera nada.
WRITEEnvia um e-mail, publica uma atualização, cria ou atualiza um registro.
DESTRUCTIVEExclui dados ou gasta dinheiro.

Uma chamada de ferramenta acima do limite é recusada, registrada como uma tarefa aguardando aprovação e informada ao modelo como não executada. A execução continua; o efeito colateral não acontece.

Nós do fluxo de trabalho

Nó	O que faz
`TRIGGER`	Ponto de entrada. Manual, webhook, agendamento ou evento.
`AI`	Executa um agente com um modelo de entrada interpolado.
`HTTP`	Chama um endpoint HTTP público. Faixas privadas são bloqueadas.
`CONDITION`	Ramifica com base em um valor do contexto da execução.
`TRANSFORM`	Remodela os dados em um novo objeto.
`EMAIL`	Envia um e-mail pelo provedor configurado.
`WEBHOOK`	Envia para fora um payload JSON assinado, por POST.
`DELAY`	Espera até 300 segundos dentro de uma execução.
`DATABASE`	Registra uma nota ou lê as execuções recentes.
`OUTPUT`	Define o resultado final do fluxo de trabalho.

Templates

A configuração de um nó interpola valores do contexto da execução. Não há avaliação de expressões, então um template nunca pode executar código.

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

API pública

Crie uma chave com escopo definido na página de chaves de API. O segredo é mostrado uma única vez; apenas o hash dele é guardado.

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

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

Toda resposta usa a mesma estrutura:

{ "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

Gatilhos por webhook

Um fluxo acionado por webhook recebe um token público e um segredo de assinatura, mostrado uma única vez na criação. Assine o corpo bruto com esse segredo.

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": "…" }