Agenten verbinden

COLVO spricht mit Ihrem Agenten über einen kleinen HTTP-Vertrag: ein POST mit Kunde, Kontext und Gesprächsverlauf; eine JSON-Antwort mit der Antwort des Agenten. Um zu handeln, schlägt der Agent COLVO eine Operation vor – mit dem Schlüssel, der in der Anfrage enthalten ist.

Direkt aus dem Code geschrieben · aktualisiert am 26 Sept. 2026 · Fehlt etwas oder ist etwas falsch? Schreib uns

Die Anfrage, die COLVO sendet

POST an Ihre Endpunkt-URL, content-type: application/json, plus den Auth-Header, den Sie am Build konfiguriert haben (unverändert als authorization gesendet). Timeout 30 Sekunden. Der 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 der Produktion (Guard) baut Ihr eigenes Backend diese Anfrage; die Form ist dieselbe, mit einer echten Mandats-ID und Ihrem Agenten-Schlüssel.

Die Antwort, die COLVO erwartet

{ "reply": "Done — I refunded €50 to your card and your plan stays active until 31 October.", "done": true, "notes": "optional" }
  • reply – der Text, den der Kunde sehen würde. Maximal 4.000 Zeichen.
  • done – true (Standard), wenn der Gesprächszug abgeschlossen ist. false lässt mehrstufige Szenarien weiterlaufen.
  • Ein Nicht-2xx-Status, ein Body über 64 KB oder fehlender verwertbarer Text lassen den Versuch mit einem klaren Grund scheitern; sie zählen nie als PASS.

Antwortpfad (jede JSON-Form funktioniert)

Liefert Ihr Agent eine andere Form, legen Sie am Build einen Antwortpfad fest: Punkte und eckige Klammern, z. B. data.answer, choices[0].message.content, messages[-1].content. Ohne Pfad erkennt COLVO automatisch diese Schlüssel, in dieser Reihenfolge:

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

Arrays aus Textblöcken ([{"type":"text","text":"…"}]) und reine String-Bodys werden ebenfalls akzeptiert.

Handeln: eine Operation vorschlagen

Entscheidet der Agent, zu erstatten oder zu kündigen, ruft er nicht Stripe auf. Er ruft COLVO auf:

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 antwortet mit 202, der Operation und ihrer Entscheidung. Der Agent sollte die Entscheidung in seiner Antwort ehrlich wiedergeben: DENY bedeutet, dass nichts passiert ist; REVIEW bedeutet, dass ein Mensch entscheidet. Vollständige Referenz: Guard-API.

Netzwerkregeln

  • Ihr Endpunkt muss für COLVO per HTTPS auf einem öffentlichen Host erreichbar sein. Localhost, private Adressbereiche und Cloud-Metadaten-Adressen werden von der Egress-Richtlinie abgelehnt; DNS wird fixiert, Weiterleitungen werden erneut geprüft.
  • Halten Sie die p95-Latenz unter wenigen Sekunden; das harte Timeout beträgt 30 s pro Aufruf.
  • Der Auth-Header wird verschlüsselt gespeichert und nach dem Speichern nie wieder angezeigt.

Vor dem Speichern testen

Test connection auf der Projektseite sendet genau die obige Anfrage (mit einem Beispielkunden) und zeigt: HTTP-Status, Latenz, die ermittelte Antwort und den Pfad, über den sie gefunden wurde, die ersten 4 KB des Roh-Bodys sowie einen dieser konkreten Fehler: Egress blockiert, Timeout, Nicht-2xx, Body weder JSON noch Text, kein Antworttext am Pfad, Antwort zu lang. Gespeichert wird erst, wenn Sie den Build speichern.

Presets: Flowise und Voiceflow

Für Agenten, die auf Flowise oder Voiceflow gebaut sind, wählen Sie die Plattform unter Connect your agent, und COLVO spricht die eigene API dieser Plattform – Sie implementieren den obigen Vertrag nicht. Der Agent besitzt trotzdem nie Provider-Schlüssel: COLVO übergibt dieselben colvo-Werte als Variablen, und der Agent schlägt damit vor.

  • Flowise – POST {flowise}/api/v1/prediction/{chatflow_id} mit question und overrideConfig: { sessionId, vars }; eine neue Sitzung pro Versuch; die Antwort ist text. Legen Sie die vier Flowise-Variablen colvo_* an und erlauben Sie Override-Config für sessionId und vars. Anleitung: Einen Flowise-Erstattungsagenten testen.
  • Voiceflow – Dialog API mit Ihrem VF.DM.-Schlüssel: PATCH /state/user/{attempt}/variables (die colvo_*-Werte, colvo_customer, colvo_context), launch beim ersten Zug, dann eine text-Aktion pro Kundennachricht; die Antwort sind die zusammengefügten Text-Traces. Anleitung: Einen Voiceflow-Assistenten verbinden.

Standardmäßig fügt COLVO unter jeder Kundennachricht die Kontodaten des Kunden (IDs, Beträge) hinzu, damit das Modell sie nutzen kann; deaktivieren Sie das am Build, wenn Ihr Flow stattdessen colvo_context liest.

Schrittweise Prüfungen (OpenTelemetry)

Zustandsprüfungen sagen, was in Stripe passiert ist; Schrittprüfungen sagen, wie der Agent dorthin gelangt ist. Fügen Sie sie an einem Szenario hinzu (beliebigen Versuch öffnen → Step checks): ein Tool wird vor einem anderen aufgerufen, höchstens N-mal, nie, der Agent antwortet erst nach der Entscheidung von COLVO, kein Schritt endete mit einem Fehler. Sie sind deterministisch und können nur ein FAIL hinzufügen – nie ein FAIL in ein PASS verwandeln.

Vorschläge zählt COLVO immer selbst. Für Prüfungen Ihrer eigenen Tools exportieren Sie den Trace Ihres Agenten während des Tests mit dem Schlüssel des Tests:

POST {app}/v1/otel/traces          (also /v1/otel/v1/traces)
Authorization: Bearer {agent_key}
Content-Type: application/json      // OTLP/HTTP JSON; protobuf not yet
  • Folgen Sie den OpenTelemetry-GenAI-Konventionen: chat …-Spans für Modellaufrufe, execute_tool {name} (oder gen_ai.tool.name) für Tools. Setzen Sie bei Ihrem Vorschlagsaufruf colvo.action.
  • COLVO speichert Span-Namen, Zeiten, Modelle, Token-Zahlen und Fehlerstatus – nie Prompts, Antworten oder Tool-Argumente. Bis zu 500 Spans pro Versuch, 1 MiB pro Batch.
  • Kein Trace? Prüfungen Ihrer eigenen Tools erscheinen als nicht geprüft, nie als FAIL. Mit dem OpenAI-Preset zeichnet COLVO jeden Schritt selbst auf.

Referenz: n8n

  1. Webhook-Node (POST) – das ist Ihre Endpunkt-URL.
  2. Ihre Modell- und Logik-Nodes, die {{ $json.messages }} und {{ $json.context }} verwenden.
  3. HTTP-Request-Node → {{ $json.colvo.operations_url }} mit Header Authorization: Bearer {{ $json.colvo.agent_key }}, wenn eine Aktion nötig ist.
  4. Respond-to-Webhook-Node → { "reply": "…" }.
← Agenten auf Guard umstellenMandate und Verbindungen →
Agenten verbinden · Docs · COLVO