Developer cookbook

Eine Tool-Integration erstellen (API)

Lassen Sie Ihren Agenten Ihre APIs während des Gesprächs aufrufen — eine Datenbank durchsuchen, ein Ticket erstellen oder eine Bestellung nachschlagen.

Eine Tool-Integration ist ein wiederverwendbarer HTTP-Endpunkt, den ein Agent während eines Anrufs aufrufen kann. Sie geben ThunderPhone eine JSON-Schema-Beschreibung des Tools sowie eine Endpunkt-URL; der Agent entscheidet anhand des Gesprächs, wann er es aufruft, und ThunderPhone sendet die ausgehende HTTP-Anfrage von seinen Servern und gibt die Antwort an den Agenten zurück.

Dieser Leitfaden zeigt Ihnen Schritt für Schritt, wie Sie ein Tool zur Wetterabfrage erstellen.

Aufbau eines Tools#

Zwei Bestandteile:

1. Das Schema — eine Funktionsdefinition im OpenAI-Stil ({type: "function", function: {name, description, parameters}}), die dem LLM mitteilt, was das Tool tut und welche Argumente es annimmt.
2. Der Endpunkt — die URL, die die Server von ThunderPhone aufrufen, wenn das LLM entscheidet, das Tool zu verwenden. Die Anfrage erfolgt als JSON-POST mit den vom LLM ausgewählten Argumenten als Body.

1. Speicherstrategie auswählen#

Dieser Leitfaden verwendet den Pfad über gespeicherte Integrationen.

2. Die Integration erstellen#

curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string", "description": "5-digit US ZIP code" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "headers": [
      { "key": "X-Api-Key", "value": "your-provider-key" }
    ]
  }'

Speichern Sie die zurückgegebene id (eine UUID).

3. Endpunkt in der Sandbox testen#

Bevor Sie die Integration mit einem Agenten verknüpfen, senden Sie eine signierte Anfrage von den Servern von ThunderPhone, um die Konnektivität zu bestätigen:

curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "headers": { "X-Api-Key": "your-provider-key" }
  }'

{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

Dieser Test härtet auch die SSRF-Schutzmechanismen von ThunderPhone — Anfragen an localhost oder private IP-Bereiche geben 400 code=url_not_allowed zurück.

4. Verknüpfen Sie die Integration mit einem Agenten#

Fügen Sie beim Erstellen oder Aktualisieren eines Agenten über integration_ids hinzu:

curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_ids": ["f9b5a1a4-..."]
  }'

Sie können viele Integrationen mit einem Agenten verknüpfen. Der Prompt des Agenten kann sie über ihren Namen referenzieren — „Verwende get_weather, wenn der Anrufer nach den Wetterbedingungen fragt“ — oder sie implizit anhand der Schemabeschreibungen erkennen.

5. Implementieren Sie den Endpunkt#

Wenn der Agent das Tool aufruft, sendet ThunderPhone einen signierten POST-Request an Ihre endpoint_url:

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

Ihr Server antwortet mit JSON, das an das LLM zurückgegeben wird:

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

Das LLM verarbeitet diese Antwort und gibt dem Anrufer eine verständliche Zusammenfassung.

6. Testen Sie den Ablauf#

Starten Sie eine Mikrofonsitzung mit dem Agenten und stellen Sie die Frage, die Ihr Tool verarbeitet („Wie ist das Wetter in 94110?“). Das Transkript des Anrufs zeigt den vollständigen Ablauf:

{
  "call_id": 987654321,
  "transcripts": [
    { "role": "user",
      "content": "What's the weather in 94110?" },
    { "role": "tool_call",
      "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
    { "role": "tool_response",
      "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
    { "role": "agent",
      "content": "It's 64 degrees and partly cloudy." }
  ]
}

Sie können dies über GET /v1/calls/{call_id}/transcript abrufen; der Rohdaten-Ereignisstream (mit Zeitangaben und Audio-Offsets pro Eintrag) befindet sich unter GET /v1/calls/{call_id}/history.

Häufige Fallstricke#

Nächste Schritte#