Tools: der Agent ruft Ihre HTTP-Endpunkte auf

Alles, was der Agent über das Sprechen hinaus tut, läuft über Tools: einen Kalender lesen, buchen, eine Bestellung prüfen, ein Ticket eröffnen. Ein Tool ist ein GET- oder POST-Endpunkt auf Ihrer Seite, für das Modell beschrieben mit einem JSON-Schema. Das Modell entscheidet, wann es ihn aufruft und mit welchen Argumenten; die Plattform führt die Anfrage aus.

Ein Tool definieren

Ein Tool hat einen Namen, eine für das Modell geschriebene Beschreibung, ein JSON-Schema seiner Argumente und den Laufzeitteil: URL, Methode, Header und eine optionale Body-Vorlage. Schreiben Sie Platzhalter {{name}} in die URL, in Header-Werte oder in den Body; jeder Platzhalter muss im Schema mit einer Beschreibung deklariert sein. Das Modell füllt ihn aus dem Gespräch und die Laufzeit ersetzt ihn, URL-kodiert in der URL und escaped in einem JSON-Body.

{
  "name": "book_appointment",
  "description": "Bucht einen Termin. Nur aufrufen, nachdem der Anrufer Tag, Uhrzeit und Namen bestätigt hat.",
  "method": "POST",
  "url": "https://api.example.ch/clinics/{{clinic}}/appointments",
  "headers": { "Authorization": "Bearer sk_…" },
  "body": "{ \"start\": \"{{start}}\", \"name\": \"{{name}}\", \"phone\": \"{{phone}}\" }",
  "schema": { "type": "object", "properties": {
    "clinic": { "type": "string", "description": "Standortcode: immer 'zurich'" },
    "start":  { "type": "string", "description": "Beginn, yyyy-MM-dd HH:mm" },
    "name":   { "type": "string", "description": "Vor- und Nachname des Anrufers" },
    "phone":  { "type": "string", "description": "Telefonnummer des Anrufers, nur Ziffern" }
  }, "required": ["clinic", "start", "name", "phone"] }
}

Was Ihr Endpunkt erhält und antworten muss

Jede Anfrage trägt einen Header token mit dem Tool-Token des Agenten: prüfen Sie ihn zuerst. Antworten Sie 200 mit einem JSON-Body. Bei Erfolg { "success": true, "message": "…" } plus beliebige Daten: die Nachricht ist dafür gedacht, dem Anrufer weitergegeben zu werden. Bei einem fachlichen Fehler { "success": false, "error": "…" } mit dem Fehler als Satz für das Modell, zum Beispiel was stattdessen vorzuschlagen ist. Bei 401 oder 500 entschuldigt sich der Agent und bietet einen Rückruf an. Halten Sie Antworten unter wenigen Sekunden: der Anrufer wartet in der Leitung.

app.post('/clinics/:clinic/appointments', express.json(), async (req, res) => {
  if (req.get('token') !== process.env.SWISSAI_TOOL_TOKEN) return res.status(401).end();
  const { start, name, phone } = req.body;
  if (!(await isFree(req.params.clinic, start)))
    return res.json({ success: false, error: 'Dieser Termin ist belegt. Biete 11:00 oder 14:30 am selben Tag an.' });
  await book(req.params.clinic, start, name, phone);
  res.json({ success: true, message: 'Termin gebucht für ' + start + '.' });
});

Eine Tool-Liste, von den Agenten geteilt

Tools liegen im Bereich Tools des Dashboards und Agenten verwenden sie per Referenz: ein Tool einmal ändern, und jeder Agent, der es nutzt, ist aktualisiert. Ein einem Kunden zugewiesenes Tool können nur dessen Agenten verwenden. Vor dem Speichern prüft das Dashboard die Definition mit Claude und baut das Schema aus den Platzhaltern.

Testen, ohne etwas zu hosten

Die Sandbox ist eine Reihe funktionierender Beispiel-Endpunkte mit separaten Testdaten pro Konto: Kalender, Restauranttische, Lager, Rückrufe, Kontakte, Bestellungen. Ihre 22 Tools sind bereits im Bereich Tools; jedes hat einen Leitfaden mit den Parametern, ein durchgerechnetes Beispiel von Anfrage und Antwort und den Code des Endpunkts, den Sie herunterladen und als Basis verwenden können.

Verwandte Seiten

• Terminbuchung am Telefon, erledigt von einem KI-Agenten
• Eine SIP-URI für jeden Sprachagenten
• Ein Anrufknopf auf Ihrer Website, beantwortet vom Agenten