Eine Tool-Integration erstellen (API)

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.

Das Dashboard deckt die meisten Tool-Anforderungen ohne diese API ab: Verbindungen → Apps verbindet Slack, HubSpot, Salesforce, Google Calendar, Google Sheets und Cal.com mit wenigen OAuth-Klicks; Verbindungen → APIs macht jede HTTP-API zu einer Agentenaktion (fügen Sie einen cURL-Befehl ein, und ein KI-Assistent erstellt einen Tool-Entwurf mit integrierter Testanfrage); und Verbindungen → MCP fügt MCP-Server hinzu. Siehe Verbindungen. Dieser Leitfaden behandelt die zugrunde liegende API der APIs-Oberfläche.

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

Aufbau eines Tools

Zwei Bestandteile:

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.
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

Inline beim Agenten

Hängen Sie ein einmaliges Tool an das tools-Array des Agenten an. Einfach, aber nicht wiederverwendbar.

Gespeicherte Integration

Speichern Sie das Tool als wiederverwendbare Integration und verknüpfen Sie es mit vielen Agenten. Empfohlen für alles, was mehr als einmal verwendet wird.

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).

Investieren Sie in die description des Tools und jedes Parameters. Das LLM verwendet diese Zeichenfolgen zur Laufzeit, um zu entscheiden, ob und wie es das Tool aufruft. Vage Beschreibungen → vage Tool-Aufrufe.

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" }
  }'

Response

{
  "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.

Die Signatur wird über den unverarbeiteten Request-Body mit demselben secret wie Ihr Webhook-Endpunkt berechnet. Überprüfen Sie sie — Tool-Endpunkte sind über das Internet erreichbar und denselben Spoofing-Risiken wie Webhooks ausgesetzt. Siehe Webhook-Signaturen überprüfen.

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

Agent ruft das Tool nie auf

Das LLM entscheidet anhand der Beschreibung des Tools. Wenn die Frage des Anrufers nicht zur Beschreibung passt, ruft das Modell das Tool nicht auf. Präzisieren Sie die Beschreibung (fügen Sie gängige Synonyme und Formulierungen hinzu) oder erwähnen Sie es explizit im Prompt des Agenten („Wenn der Anrufer nach dem Wetter fragt, verwende get_weather.“).

Tool gibt zu viele Daten zurück

Antworten über 6 kB werden in der Transkriptvorschau abgeschnitten. Geben Sie nur die Felder zurück, die das LLM benötigt — nicht Ihre gesamte Zeile.

Zeitüberschreitungen

Tool-Endpunkte haben ein Standard-Timeout von 10 Sekunden. Wenn Sie mehr Zeit benötigen, verarbeiten Sie die Anfrage asynchron: Geben Sie {"status": "pending", "request_id": "..."} zurück und stellen Sie das Ergebnis über einen separaten Tool-Aufruf bereit.

Versionierung

Jedes PATCH einer Integration erstellt eine neue Revision. Prüfen Sie GET /v1/integrations/{id}/versions, um zu sehen, wer was geändert hat. Wenn Sie das Schema eines Tools beschädigen, können Sie es manuell zurücksetzen, indem Sie einen älteren Snapshot erneut per PATCH einspielen.

Nächste Schritte

Integrationsreferenz

CRUD, Übertragung, Versionsverlauf.

Spezifikation für Funktions-Tools

Vollständige JSON-Schema-Grammatik und der Vertrag für signierte Endpunkte.

Signaturen verifizieren

Wenden Sie das Webhook-Signaturmuster auf Tool-Endpunkte an.

Transkript- und Verlaufs-API

Prüfen Sie den vollständigen Ablauf eines Tool-Aufrufs.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Eine Tool-Integration erstellen (API)

Aufbau eines Tools

1. Speicherstrategie auswählen

Inline beim Agenten

Gespeicherte Integration

2. Die Integration erstellen

3. Endpunkt in der Sandbox testen

4. Verknüpfen Sie die Integration mit einem Agenten

5. Implementieren Sie den Endpunkt

6. Testen Sie den Ablauf

Häufige Fallstricke

Nächste Schritte

Integrationsreferenz

Spezifikation für Funktions-Tools

Signaturen verifizieren

Transkript- und Verlaufs-API

​Aufbau eines Tools

​1. Speicherstrategie auswählen

Inline beim Agenten

Gespeicherte Integration

​2. Die Integration erstellen

​3. Endpunkt in der Sandbox testen

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

​5. Implementieren Sie den Endpunkt

​6. Testen Sie den Ablauf

​Häufige Fallstricke

​Nächste Schritte

Integrationsreferenz

Spezifikation für Funktions-Tools

Signaturen verifizieren

Transkript- und Verlaufs-API

Aufbau eines Tools

1. Speicherstrategie auswählen

2. Die Integration erstellen

3. Endpunkt in der Sandbox testen

4. Verknüpfen Sie die Integration mit einem Agenten

5. Implementieren Sie den Endpunkt

6. Testen Sie den Ablauf

Häufige Fallstricke

Nächste Schritte