Connecter votre agent

COLVO parle à votre agent avec un petit contrat HTTP : un POST avec le client, le contexte et la conversation ; une réponse JSON contenant ce que dit l’agent. Pour agir, l’agent propose une opération à COLVO avec la clé incluse dans la requête.

Rédigé à partir du code · mis à jour le 26 sept. 2026 · Une erreur ou un oubli ? Écrivez-nous

La requête qu’envoie COLVO

POST vers votre URL d’endpoint, content-type: application/json, plus l’en-tête d’authentification que vous avez configuré sur le build (envoyé tel quel en tant que authorization). Délai d’expiration : 30 secondes. Le corps :

{
  "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 production (Guard), c’est votre propre backend qui construit cette requête ; la forme est identique, avec un véritable identifiant de mandat et votre clé agent.

La réponse attendue par COLVO

{ "reply": "Done — I refunded €50 to your card and your plan stays active until 31 October.", "done": true, "notes": "optional" }
  • reply — le texte que verrait le client. 4 000 caractères maximum.
  • done — true (par défaut) lorsque le tour est terminé. false permet aux scénarios à plusieurs tours de se poursuivre.
  • Une réponse non 2xx, un corps de plus de 64 Ko ou l’absence de texte exploitable font échouer la tentative avec un motif explicite ; cela ne compte jamais comme un PASS.

Chemin de la réponse (toute forme JSON convient)

Si votre agent renvoie une forme différente, définissez un chemin de réponse sur le build : points et crochets, par ex. data.answer, choices[0].message.content, messages[-1].content. Sans chemin, COLVO détecte automatiquement ces clés, dans cet ordre :

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

Les tableaux de blocs de texte ([{"type":"text","text":"…"}]) et les corps constitués d’une simple chaîne sont également acceptés.

Agir : proposer une opération

Lorsque l’agent décide de rembourser ou de résilier, il n’appelle pas Stripe. Il appelle 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 répond 202 avec l’opération et sa décision. L’agent doit refléter honnêtement la décision dans sa réponse : un DENY signifie que rien ne s’est produit ; un REVIEW signifie qu’une personne va trancher. Référence complète : API Guard.

Règles réseau

  • Votre endpoint doit être joignable depuis COLVO en HTTPS sur un hôte public. Localhost, les plages privées et les adresses de métadonnées cloud sont refusés par la politique d’egress ; le DNS est épinglé et les redirections sont revérifiées.
  • Maintenez la latence p95 sous quelques secondes ; le délai d’expiration strict est de 30 s par appel.
  • L’en-tête d’authentification est stocké chiffré et n’est plus jamais affiché après l’enregistrement.

Testez avant d’enregistrer

Le bouton Test connection de la page du projet envoie exactement la requête ci-dessus (avec un client d’exemple) et affiche : le statut HTTP, la latence, la réponse extraite et le chemin qui l’a trouvée, les 4 premiers Ko du corps brut, et l’une de ces erreurs précises : egress bloqué, délai dépassé, réponse non 2xx, corps ni JSON ni texte, aucun texte au chemin indiqué, réponse trop longue. Rien n’est enregistré tant que vous n’avez pas enregistré le build.

Préréglages : Flowise et Voiceflow

Pour les agents construits sur Flowise ou Voiceflow, choisissez la plateforme dans Connect your agent et COLVO utilise l’API propre à cette plateforme — vous n’avez pas à implémenter le contrat ci-dessus. L’agent ne détient toujours aucune clé du fournisseur : COLVO transmet les mêmes valeurs colvo sous forme de variables, et l’agent propose avec elles.

  • Flowise — POST {flowise}/api/v1/prediction/{chatflow_id} avec question et overrideConfig: { sessionId, vars } ; une nouvelle session par tentative ; la réponse est text. Créez les quatre variables Flowise colvo_* et autorisez l’override config pour sessionId et vars. Guide : Tester un agent de remboursement Flowise.
  • Voiceflow — Dialog API avec votre clé VF.DM. : PATCH /state/user/{attempt}/variables (les valeurs colvo_*, colvo_customer, colvo_context), launch au premier tour, puis une action text par message du client ; la réponse est la concaténation des traces de texte. Guide : Connecter un assistant Voiceflow.

Par défaut, COLVO ajoute sous chaque message du client les données de son compte (identifiants, montants) afin que le modèle puisse les utiliser ; désactivez cette option sur le build si votre flow lit plutôt colvo_context.

Contrôles étape par étape (OpenTelemetry)

Les contrôles d’état disent ce qui s’est passé dans Stripe ; les contrôles d’étapes disent comment l’agent y est parvenu. Ajoutez-les sur un scénario (ouvrez n’importe laquelle de ses tentatives → Step checks) : un outil est appelé avant un autre, au plus N fois, jamais, l’agent ne répond qu’après la décision de COLVO, aucune étape ne s’est terminée par une erreur. Ils sont déterministes et ne peuvent qu’ajouter un FAIL — jamais transformer un FAIL en PASS.

Les propositions sont toujours comptées par COLVO lui-même. Pour les contrôles portant sur vos propres outils, exportez la trace de votre agent pendant le test avec la clé propre au 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
  • Suivez les conventions OpenTelemetry GenAI : des spans chat … pour les appels au modèle, execute_tool {name} (ou gen_ai.tool.name) pour les outils. Sur votre appel de proposition, définissez colvo.action.
  • COLVO conserve les noms des spans, les durées, les modèles, les nombres de tokens et le statut d’erreur — jamais les prompts, les réponses ni les arguments des outils. Jusqu’à 500 spans par tentative, 1 Mio par lot.
  • Pas de trace ? Les contrôles portant sur vos propres outils apparaissent comme non vérifiés, jamais comme un FAIL. Avec le préréglage OpenAI, COLVO enregistre lui-même chaque étape.

Exemple : n8n

  1. Nœud Webhook (POST) — c’est votre URL d’endpoint.
  2. Vos nœuds de modèle et de logique, utilisant {{ $json.messages }} et {{ $json.context }}.
  3. Nœud HTTP Request → {{ $json.colvo.operations_url }} avec l’en-tête Authorization: Bearer {{ $json.colvo.agent_key }} lorsqu’une action est nécessaire.
  4. Nœud Respond to Webhook → { "reply": "…" }.
← Passer votre agent sur GuardMandats et connexions →
Connecter votre agent · Docs · COLVO