> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
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](/de/guides/concepts). 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:
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
Hängen Sie ein einmaliges Tool an das `tools`-Array des Agenten an. Einfach,
aber nicht wiederverwendbar.
Speichern Sie das Tool als wiederverwendbare [Integration](/api-reference/integrations)
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
```bash theme={null}
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:
```bash theme={null}
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" }
}'
```
```json Response theme={null}
{
"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:
```bash theme={null}
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:
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json
{"zip": "94110"}
```
Ihr Server antwortet mit JSON, das an das LLM zurückgegeben wird:
```json theme={null}
{"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](/de/guides/verify-webhook-signatures).
## 6. Testen Sie den Ablauf
Starten Sie eine [Mikrofonsitzung](/api-reference/mic-sessions) 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:
```json theme={null}
{
"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`](/api-reference/calls#get-transcript) abrufen;
der Rohdaten-Ereignisstream (mit Zeitangaben und Audio-Offsets pro Eintrag) befindet sich unter
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).
## Häufige Fallstricke
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`.“).
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.
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.
Jedes `PATCH` einer Integration erstellt eine neue Revision. Prüfen Sie
[`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history),
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
CRUD, Übertragung, Versionsverlauf.
Vollständige JSON-Schema-Grammatik und der Vertrag für signierte Endpunkte.
Wenden Sie das Webhook-Signaturmuster auf Tool-Endpunkte an.
Prüfen Sie den vollständigen Ablauf eines Tool-Aufrufs.