HTTP-Tools testen und im Voice-Agenten freigeben

Ein Tool enthält die Konfiguration eines externen HTTP-Aufrufs. Über POST /api/tools/{id}/execute lässt es sich manuell ausführen. Im LiveKit-Voice-Worker kann das Modell aktive Tools nach zusätzlicher ausdrücklicher Freigabe aufrufen; Textchat nutzt weiterhin den manuellen Pfad.

Ein Tool konfigurieren

Trage Zieladresse, Methode und gegebenenfalls den Namen einer Betreiber-Umgebungsvariable für Zugangsdaten ein. Beispielkonfiguration:

{
  "name": "CRM-Kontaktprüfung",
  "status": "active",
  "data": {
    "url": "https://crm.example.at/api/contacts/search",
    "method": "POST",
    "secret_env": "AIHUB_TOOL_SECRET_CRM"
  }
}

secret_env ist ein Variablenname, kein Passwort. Er muss mit AIHUB_TOOL_SECRET_ beginnen. Den tatsächlichen Schlüssel richtet der Betreiber in der Prozessumgebung ein; der Executor sendet ihn als Bearer-Header. Der Zielhost muss ausdrücklich in AIHUB_TOOL_HOSTS freigegeben sein. Zusätzlich bindet AIHUB_TOOL_SECRET_BINDINGS den Schlüssel an genau den autorisierten Arbeitsbereich und erlaubte Hosts. Ein fremder Arbeitsbereich darf nicht durch Erraten des Variablennamens auf Betreibercredentials zugreifen.

AIHUB_TOOL_HOSTS=crm.example.at
AIHUB_TOOL_SECRET_CRM=BETREIBERSECRET_HIER_SETZEN
AIHUB_TOOL_SECRET_BINDINGS='{"AIHUB_TOOL_SECRET_CRM":{"workspace_id":"WORKSPACE_ID","hosts":["crm.example.at"]}}'

Ersetze WORKSPACE_ID durch die tatsächliche ID aus manage.py list-workspaces. Der Executor erlaubt ausschließlich öffentliche HTTPS-Ziele auf Port 443, prüft DNS-Adressen und folgt keinen Redirects. Die Allowlist ist keine allgemeine Freigabe zum Zugriff auf interne Netze.

Test- und Liveaufruf

{"mode": "test", "input": {"email": "kunde@example.at"}}

Testmodus gibt eine Simulation zurück und stellt keine externe Verbindung her. Für mode=live muss das Tool aktiv bzw. veröffentlicht sein. Zusätzlich gelten Betreiber-/Arbeitsbereichfreigabe und die Hostallowlist. Eingaben werden bei GET als Query-Parameter, bei POST/PUT/PATCH/DELETE als JSON gesendet. Eine Eingabe darf höchstens etwa 16.000 Zeichen umfassen, Antworten höchstens 256 KB. Es gibt keinen garantierten universellen API-/OAuth-/MCP-Client.

Ein Liveaufruf kann Daten an einen Dritten übertragen oder eine Aktion in dessen System auslösen. Beschreibe deshalb im Toolnamen und Prompt genau, ob der Endpunkt nur liest oder schreibt. API-Fehler werden als Fehler zurückgegeben; es wird keine erfolgreiche Buchung erfunden.

Automatische Voice-Tools

Setze ein aktives Tool mit auto_execute=true, einer klaren Beschreibung und einem JSON-Objektschema in parameters. Ordne seine ID dem Agenten in tool_ids zu und veröffentliche anschließend eine neue Agentversion. Beispiel für eine lesende Kontaktprüfung:

{
  "auto_execute": true,
  "read_only": true,
  "method": "GET",
  "description": "Vorhandenen Kontakt anhand seiner E-Mail-Adresse suchen; verändert keine Daten.",
  "parameters": {
    "type": "object",
    "properties": {"email": {"type": "string", "maxLength": 254}},
    "required": ["email"],
    "additionalProperties": false
  }
}

Diese Felder werden zum bestehenden data-Objekt mit url und optional secret_env hinzugefügt. Der Worker erhält das Schema, keine Endpointcredentials. Das Backend prüft Sitzung, veröffentlichte Zuordnung, aktive Freigabe, Arbeitsbereich und Betreiber-Hostbindung erneut. Schemas enthalten keine externen Referenzen oder regulären Ausdrücke.

Provider-Aufrufkennungen werden auf stabile idempotente IDs abgebildet. Erfolgreiche identische Schreibaktionen werden innerhalb der Sitzung wiederverwendet; unklare oder abgebrochene Schreibaktionen benötigen Prüfung des externen Status. Diese Sperre ist auf die laufende Voice-Sitzung begrenzt. Für systemübergreifende Garantien muss die Ziel-API eigene Idempotenz-/Bestätigungsregeln bereitstellen. Markiere schreibende Endpunkte nicht als read_only.

Cal.com-/CRM-/SMS-/MCP-Einträge sind Integrationskonfigurationen. Ein fertiger Kalenderbuchungsprozess mit Verfügbarkeitsprüfung und Bestätigung ist noch nicht implementiert. Gesprächsbenachrichtigungen besitzen einen getrennten E-Mail-/Webhook-Outboxworker; sie werden über agent.data.notifications konfiguriert und brauchen einen laufenden Worker. Eine URL im Tooleditor aktiviert keine automatische Ereigniszustellung.