Collega il tuo agente

COLVO parla al tuo agente con un piccolo contratto HTTP: una POST con cliente, contesto e conversazione; una risposta JSON con quello che dice l’agente. Per agire, l’agente propone un’operazione a COLVO usando la chiave inclusa nella richiesta.

Scritto a partire dal codice · aggiornato il 26 set 2026 · Manca qualcosa o c’è un errore? Scrivici

La richiesta che COLVO invia

POST al tuo URL dell’endpoint, content-type: application/json, più l’header di autenticazione che hai configurato sulla build (inviato così com’è come authorization). Timeout di 30 secondi. Il body:

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

In produzione (Guard) è il tuo backend a costruire questa richiesta; la forma è la stessa, con un vero id di mandato e la tua chiave agente.

La risposta che COLVO si aspetta

{ "reply": "Done — I refunded €50 to your card and your plan stays active until 31 October.", "done": true, "notes": "optional" }
  • reply — il testo che vedrebbe il cliente. Massimo 4.000 caratteri.
  • done — true (predefinito) quando il turno è completo. false permette agli scenari a più turni di continuare.
  • Una risposta non 2xx, un body oltre i 64 KB o l’assenza di testo utilizzabile fanno fallire il tentativo con un motivo chiaro; non contano mai come PASS.

Percorso della risposta (va bene qualsiasi forma JSON)

Se il tuo agente restituisce una forma diversa, imposta un percorso della risposta sulla build: punti e parentesi quadre, ad es. data.answer, choices[0].message.content, messages[-1].content. Senza percorso COLVO riconosce in automatico queste chiavi, in quest’ordine:

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

Sono accettati anche array di blocchi di testo ([{"type":"text","text":"…"}]) e body che sono semplici stringhe.

Agire: proporre un’operazione

Quando l’agente decide di rimborsare o disdire, non chiama Stripe. Chiama 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 risponde 202 con l’operazione e la sua decisione. L’agente deve riportare la decisione con onestà nella sua risposta: DENY significa che non è successo nulla; REVIEW significa che deciderà una persona. Riferimento completo: API di Guard.

Regole di rete

  • Il tuo endpoint deve essere raggiungibile da COLVO via HTTPS su un host pubblico. Localhost, reti private e indirizzi di metadati cloud sono rifiutati dalla policy di egress; il DNS è fissato e i redirect vengono ricontrollati.
  • Tieni la latenza p95 sotto qualche secondo; il timeout massimo è di 30 s per chiamata.
  • L’header di autenticazione è salvato cifrato e non viene più mostrato dopo il salvataggio.

Prova prima di salvare

Il pulsante Test connection nella pagina del progetto invia esattamente la richiesta qui sopra (con un cliente di esempio) e mostra: stato HTTP, latenza, la risposta estratta e il percorso che l’ha trovata, i primi 4 KB del body grezzo e uno di questi errori specifici: egress bloccato, timeout, non 2xx, body né JSON né testo, nessun testo al percorso indicato, risposta troppo lunga. Non viene salvato nulla finché non salvi la build.

Preset: Flowise e Voiceflow

Per gli agenti costruiti su Flowise o Voiceflow, scegli la piattaforma in Connect your agent e COLVO usa l’API di quella piattaforma — non devi implementare il contratto qui sopra. L’agente comunque non possiede mai chiavi del provider: COLVO passa gli stessi valori colvo come variabili e l’agente propone con quelli.

  • Flowise — POST {flowise}/api/v1/prediction/{chatflow_id} con question e overrideConfig: { sessionId, vars }; una nuova sessione per ogni tentativo; la risposta è text. Crea le quattro variabili Flowise colvo_* e consenti l’override config per sessionId e vars. Guida: Testa un agente di rimborsi Flowise.
  • Voiceflow — Dialog API con la tua chiave VF.DM.: PATCH /state/user/{attempt}/variables (i valori colvo_*, colvo_customer, colvo_context), launch al primo turno, poi un’azione text per ogni messaggio del cliente; la risposta è l’unione delle trace di testo. Guida: Collega un assistente Voiceflow.

Per impostazione predefinita COLVO aggiunge sotto ogni messaggio del cliente i dati del suo account (id, importi), così il modello può usarli; disattiva l’opzione sulla build se il tuo flow legge invece colvo_context.

Controlli passo per passo (OpenTelemetry)

I controlli di stato dicono cosa è successo in Stripe; i controlli sui passi dicono come ci è arrivato l’agente. Aggiungili su uno scenario (apri un qualsiasi tentativo → Step checks): uno strumento viene chiamato prima di un altro, al massimo N volte, mai, l’agente risponde solo dopo la decisione di COLVO, nessun passo è terminato con un errore. Sono deterministici e possono solo aggiungere un FAIL — mai trasformare un FAIL in PASS.

Le proposte vengono sempre contate da COLVO stesso. Per i controlli sui tuoi strumenti, esporta la trace del tuo agente durante il test con la chiave del test:

POST {app}/v1/otel/traces          (also /v1/otel/v1/traces)
Authorization: Bearer {agent_key}
Content-Type: application/json      // OTLP/HTTP JSON; protobuf not yet
  • Segui le convenzioni OpenTelemetry GenAI: span chat … per le chiamate al modello, execute_tool {name} (o gen_ai.tool.name) per gli strumenti. Sulla chiamata di proposta imposta colvo.action.
  • COLVO conserva nomi degli span, tempi, modelli, conteggi di token e stato di errore — mai prompt, risposte o argomenti degli strumenti. Fino a 500 span per tentativo, 1 MiB per batch.
  • Nessuna trace? I controlli sui tuoi strumenti risultano non verificati, mai FAIL. Con il preset OpenAI COLVO registra ogni passo da solo.

Esempio: n8n

  1. Nodo Webhook (POST) — questo è il tuo URL dell’endpoint.
  2. I tuoi nodi di modello e logica, che usano {{ $json.messages }} e {{ $json.context }}.
  3. Nodo HTTP Request → {{ $json.colvo.operations_url }} con header Authorization: Bearer {{ $json.colvo.agent_key }} quando serve un’azione.
  4. Nodo Respond to Webhook → { "reply": "…" }.
← Porta il tuo agente su GuardMandati e connessioni →
Collega il tuo agente · Docs · COLVO