Approvals (HITL)

Geschützte Tool-Aufrufe erfordern eine menschliche Freigabe. Der Run pausiert, bis ein Teammitglied die Aktion genehmigt oder ablehnt. Approval-Gates gelten je Tool; Webhooks binden externe Systeme ein.

So funktioniert es

Füge einen approval-Block zur Agent-YAML hinzu, um bestimmte Tools durch eine menschliche Freigabe abzusichern. Ruft der Agent ein geschütztes Tool auf, pausiert der Run und das Projekt-Team wird benachrichtigt.

Quickstart

Füge einer beliebigen Agent-YAML einen approval-Block hinzu, um bestimmte Tools zu schützen:

approval:
  tools:
    - order_tools.delete_order
    - db_delete
  timeout: 3600
  message: "Diese Aktion erfordert eine menschliche Freigabe."

Definiere bei einem LLM-Agenten unter approval.inputs einen benannten Input, um Texte wie einen MFA-Code abzufragen. connic erstellt daraus automatisch ein Tool für den Agenten und gibt den eingegebenen Text als dessen Ergebnis zurück.

approval:
  inputs:
    - get_mfa:
        prompt: Use this tool to request a 2FA code when needed.
        params:
          - reason: str
          - account_email: str
        label: MFA code
        sensitive: true
  timeout: 300

Input-Namen müssen ASCII-Bezeichner mit höchstens 64 Zeichen sein, zum Beispiel get_mfa. Die Namen müssen eindeutig sein, dürfen keine reservierten Namen der Tool-Suche verwenden und nicht mit tools, discoverable_tools oder approval.tools kollidieren. Der Agent sieht den Namen unverändert. connic erstellt das Tool ohne Python-Modulauflösung, Python-Funktion oder Eintrag im obersten tools-Abschnitt. Generierte Eingabe-Tools zählen zum Limit von 100 Tools pro Agent. prompt beschreibt dem Agenten, wann er das Tool aufrufen soll; label beschriftet das Eingabefeld für den Menschen. Referenzen auf bestehende Tools dürfen unter tools und approval.tools weiterhin Punkte enthalten.

Der optionale Abschnitt params legt fest, welchen Kontext der Agent bei jedem Aufruf mitgeben muss. Parameternamen müssen eindeutige ASCII-Bezeichner sein; Python-Schlüsselwörter und context sind nicht erlaubt. Im Beispiel erscheinen reason und account_email über dem Eingabefeld. Alle definierten Parameter sind Pflichtfelder; zusätzliche Argumente werden abgelehnt. Unterstützt werden str, int, float und bool. Ohne params nimmt das Tool keine Argumente entgegen.

Mit sensitive: true erscheint die Eingabe verdeckt. connic verschlüsselt die gespeicherte Antwort und betroffene Session-Daten und maskiert den unveränderten Antworttext in erfassten Logs und Traces. Das KI-Modell erhält den Text weiterhin als Tool-Ergebnis. Veränderte Kopien und Daten, die eigene Tools an externe Systeme senden, sind davon nicht erfasst. Ohne sensitive bleibt die Eingabe sichtbar.

Nach dem Deployment pausieren Aufrufe der konfigurierten Tools den Run und benachrichtigen das Projekt-Team. In der vollständigen Referenz zur Agent-Konfiguration stehen alle verfügbaren Optionen.

Vollständiges Beispiel

Ein vollständiger Agent mit einem ungeschützten und zwei freigabepflichtigen Tools:

version: "1.0"
name: order-manager
type: llm
model: connic/gpt-5.6-luna
description: "Verwaltet Bestellungen mit freigabepflichtigen destruktiven Aktionen"

system_prompt: |
  Du bist ein Assistent für die Bestellverwaltung.
  Verwende lookup_order, um Bestellungen zu finden, process_refund für Rückerstattungen
  und cancel_order für Stornierungen.

  Wenn ein Tool mit "awaiting_approval" antwortet, teile dem Nutzer mit,
  dass die Aktion auf eine menschliche Prüfung wartet.

temperature: 0.3

tools:
  - order_tools.lookup_order
  - order_tools.process_refund
  - order_tools.cancel_order

approval:
  tools:
    - order_tools.cancel_order
    - order_tools.process_refund
  timeout: 600
  message: "Diese Bestellaktion erfordert die Freigabe eines Managers."

In diesem Beispiel wird lookup_order ohne Einschränkung ausgeführt. Nur cancel_order und process_refund sind geschützt. Der Agent kann zunächst Bestelldetails abrufen und pausiert erst, wenn er eine destruktive Aktion ausführen will.

Bedingte Approvals

Approval-Tools unterstützen Bedingungsausdrücke mit derselben Syntax wie bedingte Tools. Ist eine Bedingung gesetzt, ist die Freigabe nur erforderlich, wenn der Ausdruck zu true ausgewertet wird. So lassen sich die tatsächlichen Parameter des Tool-Aufrufs und Kontext-Werte aus der Middleware berücksichtigen.

approval:
  tools:
    - order_tools.cancel_order                                          # erfordert immer eine Freigabe
    - order_tools.process_refund: param.amount > 50 and not context.is_admin  # bedingt
  timeout: 600
  message: "Diese Bestellaktion erfordert die Freigabe eines Managers."

Verhalten bei Ablehnung

Standardmäßig beendet eine abgelehnte Freigabe den Run mit dem Status FAILED. Setze on_rejection: continue, damit der Agent sich stattdessen anpassen kann. Der Tool-Aufruf gibt eine Ablehnung an das LLM zurück; der Agent kann einen alternativen Ansatz versuchen, den Nutzer informieren oder die Aktion überspringen.

approval:
  tools:
    - order_tools.cancel_order
    - order_tools.process_refund: param.amount > 50
  timeout: 600
  message: "Diese Bestellaktion erfordert die Freigabe eines Managers."
  on_rejection: continue   # der Agent passt sich an, statt fehlzuschlagen

Approvals verwalten

Die Seite Approvals in der Sidebar zeigt alle Approval-Anfragen für das aktuelle Environment. Ausstehende Approvals stehen oben.

Anfragen lassen sich auch im Run-Detail-Drawer genehmigen oder ablehnen. Klicke auf eine beliebige Zeile in der Approvals-Tabelle oder öffne auf der Seite Agent Runs einen Run mit dem Status „Awaiting Approval“. Die Approval Card zeigt Tool-Name, Parameter und Aktionsbuttons.

Benötigt das Tool eine Eingabe, öffnet Provide response das Eingabefeld im Drawer. Submit and continue sendet den Text und setzt den Run fort. Leere Eingaben oder reine Leerzeichen sind nicht zulässig. Führende Nullen und umgebende Leerzeichen bleiben erhalten.

approvals.view gewährt Zugriff auf Approval-Anfragen, approvals.decide erlaubt Genehmigen und Ablehnen und approvals.configure erlaubt die Konfiguration des Weiterleitung von Benachrichtigungen.

Benachrichtigungen

Wenn ein Approval erforderlich ist, erhalten Projektmitglieder mit der Berechtigung approvals.view standardmäßig eine E-Mail und eine In-App-Benachrichtigung. Jedes Mitglied kann diese Einstellungen in den Benachrichtigungseinstellungen des Projekts ändern. Der Drawer Notification Config auf der Seite Approvals konfiguriert das Routing über Projekt Channels:

• Approvals für bestimmte Agenten (oder alle Agenten) an Projekt Channels weiterleiten

Channel-Integration

Enterprise-Projekte können wiederverwendbare Channels für Benachrichtigungen, Approvals sowie Audit- oder Log-Drains nutzen. So werden Approval-Anfragen an einen Channel weitergeleitet:

1. 1
   Öffne Projekt-Settings → Notifications und füge einen Channel hinzu.
2. 2
   Konfiguriere den HTTPS-Endpoint des Webhooks und optional ein Signing Secret.
3. 3
   Wähle auf der Seite Approvals ein Environment aus und öffne Notification Config.
4. 4
   Aktiviere den Channel und wähle aus, für welche Agenten er Approvals erhält. Lass die Auswahl für alle Agenten leer.

Webhook Channels senden die folgende Payload an einen HTTPS-Endpoint. Ein optionales Signing Secret fügt die Header X-Connic-Signature und X-Connic-Timestamp hinzu, damit der Empfänger jeden Request verifizieren kann. Die zuständigen Personen genehmigen oder lehnen in connic oder über die REST API ab.

{
  "type": "approval_requested",
  "approval_id": "a1b2c3d4-...",
  "run_id": "e5f6a7b8-...",
  "agent_name": "order-manager",
  "tool_name": "order_tools.cancel_order",
  "tool_params": {
    "order_id": "ORD-1234",
    "reason": "Kunde hat die Stornierung angefordert"
  },
  "message": "Diese Bestellaktion erfordert die Freigabe eines Managers.",
  "timeout": 600,
  "environment_id": "f9e8d7c6-...",
  "environment_name": "Produktion",
  "project_id": "b4c3d2e1-...",
  "channel_id": "c5d4e3f2-...",
  "channel_name": "Bereitschafts-Approvals",
  "created_at": "2026-04-05T10:30:00Z"
}

Mehrere Approvals

Ruft ein Agent mehrere geschützte Tools nacheinander auf, löst jedes einen eigenen Ablauf mit Pause und Freigabe aus. Der Run durchläuft folgende Status:

Bei jeder Fortsetzung werden der gespeicherte Gesprächsverlauf und Tool-Zustand geladen, ohne abgeschlossene Tool-Aufrufe erneut auszuführen.

API

Approvals können über die REST API verwaltet werden. API Keys verwenden approvals.view zum Auflisten von Anfragen, approvals.decide zum Genehmigen oder Ablehnen und approvals.configure zur Verwaltung des Weiterleitung von Benachrichtigungen.

Anfragen mit response_label benötigen beim Genehmigen über POST /projects/{project_id}/approvals/{approval_id}/decide einen nicht leeren String in response. reason bleibt für die Begründung der Entscheidung vorgesehen. Bei normalen Freigaben und Ablehnungen entfällt response.

{"status": "approved", "response": "001234"}

Über connic MCP übergibst du einen nicht leeren String in response an approve_tool_call, wenn die aufgelistete Anfrage ein response_label enthält. Lass response bei normalen Freigaben weg; reject_tool_call akzeptiert das Feld nicht.

Audit Trail

Jede Approval-Entscheidung wird mit Aktion, entscheidender Person, Tool-Name und Parametern im Audit Log erfasst. Approval-Traces erscheinen außerdem in der Trace-Ansicht des Runs und zeigen Wartezeit und Angaben zur prüfenden Person.