Zum Hauptinhalt springen

Agenten-Webhooks

Mit Agenten-Webhooks kann ein externes System einen konfigurierten Agenten starten. Erstelle einen per Webhook ausgelösten Agenten, sende ihm eine Anfrage und Almirant erstellt dafür einen einzigen kanonischen Job.

Schnelleinstieg​

  1. Öffne Agents und wähle Create agent.
  2. Fülle die Schritte Base, Prompt und gegebenenfalls MCP aus.
  3. Wähle unter Trigger die Option Webhook und speichere den Agenten. Almirant zeigt eine Produktions- und eine Test-URL an.
  4. Speichere die Produktions-URL im aufrufenden System als Secret und sende eine POST-Anfrage mit Idempotency-Key.

Die Produktions-URL hat diese Form:

https://<your-almirant-host>/webhooks/agents/<agent-id>?token=<webhook-token>

Das Token ist Teil der Zugangsdaten. Nimm es nicht in Versionskontrolle, Logs oder öffentliche Tickets auf.

POST-Anfrage senden​

POST startet einen Agentenjob mit dem gespeicherten System-Prompt sowie einem optionalen Prompt und Metadaten des Aufrufenden.

curl --request POST \
  --url 'https://almirant.example.com/webhooks/agents/agent_123?token=replace-with-secret-token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-9182-import-v1' \
  --data '{
    "prompt": "Importa el pedido e informa de cualquier error de validación.",
    "metadata": {
      "orderId": "9182",
      "source": "warehouse"
    }
  }'

Die erste erfolgreiche Übermittlung gibt den erstellten Job zurück:

{
  "success": true,
  "data": {
    "jobId": "job_123",
    "status": "queued",
    "created": true,
    "replayed": false
  }
}

Sende denselben Idempotency-Key erneut, wenn ein Netzwerkfehler Zweifel daran lässt, ob Almirant die Anfrage empfangen hat. Eine Wiederholung gibt denselben kanonischen Job zurück, statt einen weiteren zu starten:

{
  "success": true,
  "data": {
    "jobId": "job_123",
    "status": "queued",
    "created": false,
    "replayed": true
  }
}

Anfragevertrag​

TeilAnforderung
URLagent-id und der Abfrageparameter token sind erforderlich. Ungültige oder fehlende Zugangsdaten geben 401 zurück.
Idempotency-KeyIn POST optional; verwende pro logischem Ereignis einen undurchsichtigen, stabilen Wert. Er muss 1 bis 255 UTF-8-Bytes lang sein, darf nicht leer sein und keine Steuerzeichen enthalten. Ungültige Werte geben 400 mit invalid_idempotency_key zurück.
promptOptionale Zeichenfolge, die bei dieser Ausführung als Eingabe des Aufrufenden hinzugefügt wird.
metadataOptionales Objekt. Gespeicherte Agenten-Prompts können Metadatenwerte wie {{metadata.orderId}} interpolieren.
outputBindingOptionale Zeichenfolgenwerte für ein bereits im Agenten konfiguriertes Ausgabeziel. Es kann keine neue Zustell-URL auswählen.

Der Body akzeptiert nur prompt, metadata und outputBinding. Ein vom Aufrufenden gesteuertes deliveryUrl wird abgelehnt.

Verhalten von Test, GET und POST​

Der Test-Endpunkt prüft, ob die URL erreichbar ist. Er reiht keinen Job ein:

POST https://<your-almirant-host>/webhook-test/agents/<agent-id>?token=<webhook-token>

Der Produktionsendpunkt GET startet einen Job mit dem gespeicherten System-Prompt. GET akzeptiert keine Eingabe des Aufrufenden und bietet nicht die idempotente Antwortsemantik von POST. Verwende POST in Integrationen, die Wiederholungen ausführen können.

Webhook-ausgelöste Agenten verwenden eine manuelle Planung, da eingehende Anfragen sie starten, nicht der Planer. Ein Webhook-Agent muss aktiviert und für diesen Auslöser konfiguriert bleiben, andernfalls gibt der Endpunkt 409 zurück.

Fehlerbehebung​

AntwortBedeutungAktion
400 invalid_idempotency_keyDer POST-Schlüssel ist leer, zu lang oder enthält ein Steuerzeichen.Erzeuge eine kurze, stabile Ereignis-ID.
400 invalid_output_bindingDie bereitgestellte Bindung stimmt nicht mit der Ausgabekonfiguration des Agenten überein.Prüfe das konfigurierte Ausgabeziel und die Namen der Bindungsfelder.
401 invalid_webhook_credentialsDas URL-Token fehlt, ist falsch oder nicht mehr gültig.Kopiere die aktuelle URL des Agenten und ersetze das gespeicherte Secret.
409Der Agent kann nicht als Webhook-Agent ausgeführt werden.Aktiviere ihn erneut und bestätige, dass sein Auslöser Webhook ist.

Verwandte Seiten​