Eigene Tools (Webhooks)

Mit Eigenen Tools (im Dashboard "Custom Tools") geben Sie Ihrem KI-Agenten die Fähigkeit, während eines Gesprächs Ihre eigenen Systeme abzufragen oder anzustoßen — zum Beispiel den Bestellstatus aus Ihrem Shop holen, einen Termin in Ihrem Branchensystem prüfen oder einen Datensatz in Ihrer eigenen Software anlegen. Sie beschreiben hier nur, welche Funktionen es gibt und welche Angaben der Agent dafür sammeln muss; ausgeführt werden die Tools über einen sogenannten Webhook — eine Internetadresse Ihrer Anwendung, die unsere Plattform automatisch aufruft.

Sie finden diesen Bereich im Agenten-Menü unter "Custom Tools". Im Kopf der Karte steht der Hinweis: "Funktionen, die der Agent aufrufen kann. Beim Aufruf POSTet das Backend an Ihre tool_webhook_url." Das bedeutet: Sobald der Agent ein Tool nutzt, schickt Prezio die gesammelten Angaben an die von Ihnen hinterlegte Webhook-Adresse, und Ihre Anwendung antwortet mit dem Ergebnis.

Wichtig vorab — zwei getrennte Stellen: Auf dieser Seite legen Sie die Tools selbst an (Name, Beschreibung, Parameter). Die Webhook-Adresse (tool_webhook_url), an die alle Tools dieses Agenten geschickt werden, tragen Sie an einer anderen Stelle ein: im Bereich "Kanäle / Channels" des Agenten unter dem Feld Tool-Webhook-URL. Ohne diese Adresse werden die Tools zwar definiert, aber es gibt keinen Empfänger, der sie ausführt. Siehe dazu den Hinweis am Ende dieses Abschnitts.

Ein Tool anlegen

Schritt 1 — Tool hinzufügen. Klicken Sie oben rechts auf "Tool hinzufügen" (bzw. bei einer leeren Liste auf die gleiche Schaltfläche in der Hinweisbox "Noch keine Custom Tools"). Es öffnet sich ein hervorgehobener Bearbeitungsbereich.

Schritt 2 — Tool-Name vergeben. Tragen Sie im Feld "Tool-Name" einen kurzen, technischen Namen ein, z. B. lookup_order (so der vorausgefüllte Beispieltext). Beachten Sie: - Der Name dient der KI als technische Kennung der Funktion — schreiben Sie ihn klein und sprechend (z. B. bestellung_pruefen, termin_freie_slots, lead_anlegen). - Leerzeichen werden automatisch durch Unterstriche ersetzt, während Sie tippen. Aus "lookup order" wird also lookup_order. Das ist gewollt und kein Fehler. - Der Name ist Pflicht: Die Schaltfläche "Tool speichern" bleibt grau, solange das Namensfeld leer ist. - Standard: leer. Empfehlung: ein eindeutiger, eindeutig zuordenbarer Bezeichner ohne Sonderzeichen.

Schritt 3 — Beschreibung formulieren. Im Feld "Beschreibung" erklären Sie, wann der Agent dieses Tool aufrufen soll (genau das sagt auch der Hinweis unter dem Feld: "Sagen Sie dem Agent, wann er dieses Tool aufrufen soll."). Diese Beschreibung ist entscheidend, denn die KI entscheidet allein anhand des Textes, ob ein Tool zur aktuellen Kundenfrage passt. - Beispiel (vorausgefüllter Platzhalter): "Status und Versanddetails einer Kundenbestellung per Order-ID abrufen." - Formulieren Sie aus Sicht des Auslösers: "Nutze dieses Tool, wenn der Kunde nach dem Status seiner Bestellung fragt und eine Bestellnummer nennt." - Standard: leer. Empfehlung: ein bis zwei klare Sätze mit dem konkreten Auslöser. Vage Beschreibungen führen dazu, dass das Tool zu selten oder zu oft aufgerufen wird.

Schritt 4 — Parameter definieren. Parameter sind die Angaben, die der Agent vom Kunden sammelt und an Ihren Webhook übergibt (z. B. die Bestellnummer). Klicken Sie auf "Param", um eine Zeile hinzuzufügen. Pro Parameter füllen Sie aus: - name — der technische Feldname, den Ihr Webhook erwartet (z. B. order_id). Wird in Monospace dargestellt; bitte ohne Leerzeichen. - type — der Datentyp. Auswahl per Klappliste, genau drei Werte: - string (Text, z. B. eine Bestellnummer oder ein Name) — dies ist die Vorauswahl jeder neuen Zeile. - number (Zahl, z. B. eine Personenanzahl oder ein Betrag), - boolean (Ja/Nein, z. B. "express gewünscht"). - Empfehlung: Im Zweifel string belassen — die KI kann fast alles als Text übergeben. - beschreibung — eine kurze Erläuterung, was dieser Parameter ist. Auch diese liest die KI, um den richtigen Wert beim Kunden zu erfragen (z. B. "Die Bestellnummer aus der Bestätigungs-E-Mail"). - "erf." (Kontrollkästchen "erforderlich") — ist es angehakt, wird der Parameter als Pflichtfeld markiert: Der Agent fragt aktiv nach, bevor er das Tool aufruft. Standard: nicht angehakt (optional). Empfehlung: alles anhaken, ohne das Ihr Webhook nicht arbeiten kann (z. B. die Bestellnummer). - Mit dem Papierkorb-Symbol am Zeilenende ("Parameter entfernen") löschen Sie eine Parameterzeile wieder.

Ein Tool darf auch gar keine Parameter haben (dann steht "Noch keine Parameter." im Bearbeitungsbereich). Das ist sinnvoll für Funktionen ohne Eingabe, z. B. "aktuelle Öffnungszeiten holen".

Schritt 5 — Speichern. Klicken Sie auf "Tool speichern". Das Tool erscheint nun als Zeile in der Liste — mit seinem Namen, einem Zähler-Badge ("1 Param" / "{Anzahl} Params", wird nur angezeigt, wenn es Parameter gibt) und der Beschreibung darunter. Mit "Abbrechen" verwerfen Sie den Entwurf ohne zu speichern.

Hinweis: Leere Parameterzeilen (ohne Namen) werden beim Speichern automatisch verworfen. Nur Parameter mit einem ausgefüllten name landen im Tool.

Tools verwalten

In der Liste der angelegten Tools haben Sie pro Eintrag zwei Symbolschaltflächen: - Bearbeiten (Stift) — öffnet das Tool wieder im Bearbeitungsbereich, inklusive aller Parameter. - Entfernen (Papierkorb, rot) — löscht das Tool aus der Liste.

Schritt 6 — Gesamten Agenten speichern (sehr wichtig). Alle Änderungen in diesem Bereich sind zunächst nur ein lokaler Entwurf. Erst wenn Sie unten in der fest sitzenden Speicher-Leiste auf "Speichern" klicken, werden die Tools dauerhaft beim Agenten gesichert. Solange es ungespeicherte Änderungen gibt, erscheint dort ein Hinweis; die Schaltfläche bleibt deaktiviert, wenn nichts geändert wurde. Verlassen Sie die Seite nicht, ohne hier gespeichert zu haben.

Was technisch hinterlegt wird

Damit Sie und Ihre IT denselben Stand haben: Pro Tool speichert Prezio drei Angaben — den Namen, die Beschreibung und ein Eingabe-Schema (input_schema). Das Eingabe-Schema wird aus Ihren Parameterzeilen automatisch als JSON-Schema erzeugt, in der Form:

{
  "type": "object",
  "properties": {
    "order_id": { "type": "string", "description": "Bestellnummer" }
  },
  "required": ["order_id"]
}

Genau diese Struktur (plus die vom Kunden gesammelten Werte) sendet Prezio per HTTP-POST an Ihre Tool-Webhook-URL, sobald der Agent das Tool nutzt. Ihre Anwendung verarbeitet die Anfrage und antwortet mit dem Ergebnis, das der Agent dann dem Kunden mitteilt.

Die Webhook-Adresse einrichten (im Bereich "Kanäle")

Wie oben erwähnt, wird die Empfänger-Adresse nicht hier, sondern im Bereich "Kanäle / Channels" des Agenten gepflegt: - Tool-Webhook-URL (tool_webhook_url) — die Internetadresse Ihrer Anwendung, die alle Tools dieses Agenten ausführt (Beispiel im Feld: https://your-app.com/api/tool-handler). Standard: leer. Ohne diese URL bleiben Ihre Tools wirkungslos. - Zur Absicherung kann zusätzlich ein Webhook-Geheimnis (tool_webhook_secret) hinterlegt werden. Damit kann Ihre Anwendung prüfen, dass ein eingehender Aufruf wirklich von Prezio stammt. Lassen Sie es leer, wenn Sie es nicht nutzen. - Davon getrennt gibt es eine Benachrichtigungs-Webhook-URL (notification_webhook_url, Beispiel https://your-app.com/api/notify) — diese ist nicht für Tools gedacht, sondern für Ereignis-Benachrichtigungen, und hat mit diesem Bereich nichts zu tun.

Tipps & Stolpersteine

• Tool-Name ist Pflicht, Webhook-URL kommt woanders her. Sie können ein Tool speichern, ohne dass eine Webhook-Adresse hinterlegt ist — es wird dann aber nie ausgeführt. Tragen Sie die Tool-Webhook-URL im Bereich "Kanäle" ein, sonst läuft das Tool ins Leere.
• Die Beschreibung steuert das Verhalten der KI. Der Agent ruft ein Tool nur auf, wenn die Beschreibung gut zur Kundenfrage passt. Eine schwammige Beschreibung ist der häufigste Grund, warum ein Tool "nicht reagiert". Wenn Sie nachvollziehen wollen, ob und warum der Agent ein Tool genutzt hat, hilft Ihnen der KI-Debug-Bereich: Im Entscheidungs-Fluss (Decision-Flow) jeder Antwort sehen Sie die tatsächlich ausgeführten Tool-Aufrufe Schritt für Schritt.
• Leerzeichen im Namen verschwinden absichtlich. Tippen Sie "kunde anlegen", wird daraus automatisch kunde_anlegen. Verwenden Sie keine Umlaute oder Sonderzeichen in Tool- und Parameternamen.
• Nur drei Parametertypen. Sie haben ausschließlich string, number und boolean zur Wahl. Für Datumsangaben, Auswahllisten o. Ä. nutzen Sie string und beschreiben das erwartete Format in der beschreibung des Parameters (z. B. "Datum im Format JJJJ-MM-TT").
• "Erforderlich" (erf.) gut wählen. Nur als erforderlich markierte Parameter erfragt der Agent zuverlässig vom Kunden. Vergessen Sie ein Pflichtfeld zu markieren, ruft der Agent das Tool unter Umständen mit fehlenden Angaben auf — Ihr Webhook erhält dann eine unvollständige Anfrage.
• Leere Parameterzeilen sind harmlos. Vergessen Sie, eine angefangene Zeile zu füllen, wird sie beim Speichern einfach ignoriert. Sie müssen sie nicht extra löschen, sollten es der Übersicht halber aber tun.
• Speichern nicht vergessen. Hinzufügen oder Löschen eines Tools allein genügt nicht — erst die "Speichern"-Schaltfläche unten in der fixierten Leiste schreibt die Änderung dauerhaft. Beim Verlassen ohne Speichern gehen die Änderungen verloren.