Function Tools

Funktionswerkzeuge

Statten Sie Ihre KI-Agenten mit Funktionswerkzeugen aus, die während eines Gesprächs externe APIs aufrufen — Kundendaten abrufen, Termine buchen, Datensätze aktualisieren — mit typisierten Parametern.

Funktions-Tools ermöglichen Ihren KI-Agenten, während Telefonaten externe APIs aufzurufen. Verwenden Sie sie, um Kundendaten abzurufen, Verfügbarkeiten zu prüfen, Termine zu buchen oder jede Aktion auszuführen, die Ihr Backend unterstützt.

So funktioniert es#

1. Sie definieren Tools mit einem Schema (welche Argumente das Tool akzeptiert).
2. Sie geben eine endpoint-Konfiguration an (wo ThunderPhone Ihre API aufruft) — oder lassen sie weg, um Tool-Aufrufe über den Webhook Ihrer Organisation zu erhalten.
3. Während eines Anrufs entscheidet die KI anhand des Gesprächs, wann ein Tool verwendet wird.
4. ThunderPhone ruft Ihren Endpunkt mit den Tool-Argumenten auf.
5. Die API-Antwort wird an die KI zurückgegeben, um das Gespräch fortzusetzen.

Tool-Schema#

Jedes Tool folgt dieser Struktur:

{
  "type": "function",
  "function": {
    "name": "search_appointments",
    "description": "Find available appointment slots for a given date",
    "parameters": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "description": "Date in YYYY-MM-DD format"
        },
        "service": {
          "type": "string",
          "description": "Type of service (e.g., 'consultation', 'follow-up')"
        }
      },
      "required": ["date"]
    }
  },
  "endpoint": {
    "url": "https://api.example.com/appointments/search",
    "method": "POST",
    "headers": {
      "X-Api-Key": "your-api-key"
    }
  },
  "timeout": 120
}

Tool-Konfiguration#

Funktionsdefinition#

Endpunkt-Konfiguration#

Zwei Aufrufwege#

Welche Anfrage Ihr Server erhält, hängt davon ab, ob das Tool einen endpoint hat:

Beide Wege sind blockierend — die KI wartet mitten im Satz auf das Ergebnis. Das Standard-Timeout beträgt 20 s; legen Sie das timeout auf oberster Ebene des Tools fest, um eine längere Ausführung bis zum Plattformmaximum von 180 s zu ermöglichen. Halten Sie Handler schnell. Eine Mischung ist möglich: Bei einem Anruf, dessen Organisation eine Webhook-URL hat, werden Tools mit einem endpoint direkt aufgerufen, während die übrigen auf den Webhook zurückfallen.

Direkte Endpoint-Aufrufe#

Wenn die KI ein Tool mit einem endpoint aufruft, sendet ThunderPhone eine Anfrage an Ihre URL:

Anfrage-Header#

POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-Api-Key: your-api-key

Benutzerdefinierte Header aus Ihrem endpoint.headers werden stets unverändert eingefügt, zusätzlich zu zwei Headern im ThunderPhone-Namensraum:

• X-ThunderPhone-Signature — HMAC-SHA256 der exakten Bytes des Anfrage-Bodys, verschlüsselt mit Ihrem Webhook-Secret der Organisation
• X-ThunderPhone-Call-ID — Die aktuelle Anruf-ID

Content-Type: application/json wird gesetzt, sofern Ihre endpoint.headers diesen Header nicht überschreiben — ein benutzerdefinierter Content-Type hat Vorrang.

Anfrage-Body#

Für POST / PUT / PATCH enthält der Body nur die Tool-Argumente (ohne Wrapper), kanonisch serialisiert (sortierte Schlüssel, kompakte Trennzeichen):

{"date":"2025-01-02","service":"consultation"}

Für GET / DELETE werden die Argumente als Abfrageparameter gesendet und der Body ist leer — die Signatur wird dann über die leere Bytezeichenfolge berechnet. Siehe Webhook-Signaturen überprüfen.

Antwort#

Geben Sie eine JSON-Antwort mit dem Tool-Ergebnis zurück:

{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}

Die Antwort wird formatiert und der KI bereitgestellt, damit sie das Gespräch fortsetzen kann. Nicht-JSON-Antworten werden als {"data": "<text>"} verpackt; Zeitüberschreitungen und Verbindungsfehler werden der KI als Fehler gemeldet, sodass der Agent sich entschuldigen und fortfahren kann, statt zu blockieren.

Versand im Webhook-Modus#

Tools ohne einen endpoint werden als signierte telephony.tool-Anfrage (Telefonanrufe) oder web.tool-Anfrage (Webanrufe) an die Legacy-Webhook-URL Ihrer Organisation gesendet. Anders als die Audit-Benachrichtigungen, die nach der Ausführung an Webhook-Endpoints zugestellt werden, ist diese Anfrage die Ausführung — Ihre HTTP-Antwort ist das Tool-Ergebnis.

{
  "type": "telephony.tool",
  "data": {
    "call_id": 987654321,
    "tool_name": "search_appointments",
    "arguments": { "date": "2026-04-21" },
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  }
}

web.tool enthält origin_domain anstelle von from_number / to_number. Antworten Sie mit dem Tool-Ergebnis als JSON — derselbe Antwortvertrag wie bei direkten Endpoint-Aufrufen. Die Anfrage wird wie jeder andere Webhook mit dem Webhook-Secret der Organisation über den unverarbeiteten Body signiert.

Signaturprüfung#

Direkte Tool-Aufrufe werden auf dieselbe Weise wie Webhooks signiert:

• HMAC-SHA256 über die exakten Bytewerte des Request-Bodys (das kanonische JSON — sortierte Schlüssel, keine zusätzlichen Leerzeichen)
• Mit dem Webhook-Secret Ihrer Organisation als Schlüssel
• GET- / DELETE-Tools signieren die leere Bytezeichenfolge

import hmac
import hashlib
 
def verify_tool_call(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
 
@app.post("/appointments/search")
async def search_appointments(request: Request):
    body = await request.body()
    signature = request.headers.get("X-ThunderPhone-Signature", "")
 
    if not verify_tool_call(body, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=401)
 
    data = json.loads(body)
    date = data["date"]
 
    # Look up availability
    slots = await get_available_slots(date)
 
    return {"available_slots": slots}

app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-thunderphone-signature'] || '';
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
 
  if (!signature ||
      signature.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).send('Invalid signature');
  }
 
  const { date, service } = JSON.parse(req.body);
 
  // Look up availability
  const slots = getAvailableSlots(date, service);
 
  res.json({ available_slots: slots });
});

Vollständige Anleitungen — einschließlich des Falls mit leerem Body und des Hinweises bei fehlendem Secret — finden Sie unter Webhook-Signaturen prüfen.

Beispiel: Vollständiger Buchungsablauf#

Hier ist eine Reihe von Tools für ein vollständiges Terminbuchungssystem:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_appointments",
        "description": "Find available appointment slots",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "service": { "type": "string" }
          },
          "required": ["date"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/search",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "book_appointment",
        "description": "Book an appointment at a specific time",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "time": { "type": "string", "description": "HH:MM format" },
            "customer_name": { "type": "string" },
            "customer_phone": { "type": "string" }
          },
          "required": ["date", "time", "customer_name"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/book",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "cancel_appointment",
        "description": "Cancel an existing appointment",
        "parameters": {
          "type": "object",
          "properties": {
            "confirmation_number": { "type": "string" }
          },
          "required": ["confirmation_number"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/cancel",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    }
  ]
}

Best Practices#

Verwandte Inhalte#