Developer cookbook

Een toolintegratie bouwen (API)

Laat je agent tijdens een gesprek je API

Een toolintegratie is een herbruikbaar HTTP-eindpunt dat een agent tijdens een gesprek kan aanroepen. Je geeft ThunderPhone een JSON-schemabeschrijving van de tool plus een eindpunt-URL; de agent beslist op basis van het gesprek wanneer deze moet worden aangeroepen, en ThunderPhone doet het uitgaande HTTP-verzoek vanaf zijn servers en retourneert het antwoord aan de agent.

Deze handleiding neemt je stap voor stap mee bij het bouwen van een tool voor het opzoeken van weergegevens.

Anatomie van een tool#

Twee onderdelen:

1. Het schema — een functiedefinitie in OpenAI-stijl ({type: "function", function: {name, description, parameters}}) die de LLM vertelt wat de tool doet en welke argumenten deze accepteert.
2. Het eindpunt — de URL die de servers van ThunderPhone aanroepen wanneer de LLM beslist de tool te gebruiken. Het verzoek is een JSON-POST met de door de LLM gekozen argumenten als hoofdtekst.

1. Kies een opslagstrategie#

Deze handleiding gebruikt de route met opgeslagen integraties.

2. Maak de integratie#

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

Sla de geretourneerde id (een UUID) op.

3. Test het eindpunt in de sandbox#

Voordat je de integratie aan een agent koppelt, stuur je een ondertekend verzoek vanaf de servers van ThunderPhone om de connectiviteit te bevestigen:

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, ...}"
}

Deze test versterkt ook de SSRF-beveiliging van ThunderPhone — verzoeken naar localhost of privé-IP-bereiken retourneren 400 code=url_not_allowed.

4. Koppel de integratie aan een spraakagent#

Koppel via integration_ids wanneer je een spraakagent maakt of bijwerkt:

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

Je kunt meerdere integraties aan één spraakagent koppelen. De prompt van de spraakagent kan ernaar verwijzen op naam — "gebruik get_weather wanneer de beller naar de weersomstandigheden vraagt" — of ze impliciet herkennen aan de schemabeschrijvingen.

5. Implementeer het endpoint#

Wanneer de spraakagent de tool aanroept, stuurt ThunderPhone een ondertekende POST naar je 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"}

Je server antwoordt met JSON dat wordt teruggestuurd naar de LLM:

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

De LLM verwerkt dat antwoord en spreekt een begrijpelijke samenvatting uit voor de beller.

6. Test de volledige stroom#

Start een micsessie met de spraakagent en stel de vraag die je tool afhandelt ("Wat is het weer in 94110?"). Het transcript van het gesprek toont de volledige heen-en-terugcommunicatie:

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

Je kunt dit ophalen via GET /v1/calls/{call_id}/transcript; de onbewerkte eventstream (met timing per item en audio-offsets) vind je op GET /v1/calls/{call_id}/history.

Veelvoorkomende valkuilen#

Volgende stappen#