Bygg en verktøyintegrasjon (API)

En verktøyintegrasjon er et gjenbrukbart HTTP-endepunkt som en agent kan kalle under en samtale. Du gir ThunderPhone en JSON-schemabeskrivelse av verktøyet samt en endepunkt-URL; agenten avgjør når det skal kalles basert på samtalen, og ThunderPhone utfører den utgående HTTP- forespørselen fra serverne sine og returnerer svaret til agenten.

Dashbordet dekker de fleste verktøybehov uten dette API-et: Tilkoblinger → Apper kobler til Slack, HubSpot, Salesforce, Google Calendar, Google Sheets og Cal.com med noen få OAuth-klikk; Tilkoblinger → API-er gjør et hvilket som helst HTTP-API om til en agenthandling (lim inn en cURL-kommando, så lager en AI-veiviser et utkast til verktøyet, med innebygd Test forespørsel); og Tilkoblinger → MCP legger til MCP-servere. Se Tilkoblinger. Denne veiledningen dekker det underliggende rå-API-et for API-flaten.

Denne veiledningen går gjennom hvordan du bygger et verktøy for værdata fra start til slutt.

Oppbygningen av et verktøy

To deler:

Schemaet — en funksjonsdefinisjon i OpenAI-stil ({type: "function", function: {name, description, parameters}}) som forteller LLM-en hva verktøyet gjør og hvilke argumenter det tar.
Endepunktet — URL-en som ThunderPhone-serverne kaller når LLM-en bestemmer seg for å bruke verktøyet. Forespørselen er en JSON POST med argumentene LLM-en har valgt som brødtekst.

1. Velg en lagringsstrategi

Direkte på agenten

Knytt et engangsverktøy til agentens tools-array. Enkelt, men ikke gjenbrukbart.

Lagret integrasjon

Lagre verktøyet som en gjenbrukbar integrasjon og koble det til mange agenter. Anbefales for alt som brukes mer enn én gang.

Denne veiledningen bruker fremgangsmåten med lagret integrasjon.

2. Opprett integrasjonen

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

Lagre den returnerte id-en (en UUID).

Legg reell innsats i description for verktøyet og hver parameter. LLM-en bruker disse strengene under kjøring for å avgjøre om og hvordan verktøyet skal kalles. Vage beskrivelser → vage verktøykall.

3. Test endepunktet i sandbox

Før du kobler integrasjonen til en agent, send en signert forespørsel fra ThunderPhone-serverne for å bekrefte tilkoblingen:

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

Denne testen forsterker også ThunderPhones SSRF-beskyttelse — forespørsler til localhost eller private IP-områder returnerer 400 code=url_not_allowed.

4. Knytt integrasjonen til en agent

Knytt den til via integration_ids når du oppretter eller oppdaterer en agent:

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

Du kan knytte mange integrasjoner til én agent. Agentens ledetekst kan referere til dem ved navn — «bruk get_weather når innringeren spør om værforhold» — eller den kan oppdage dem implisitt fra skjemabeskrivelsene.

5. Implementer endepunktet

Når agenten kaller verktøyet, sender ThunderPhone en signert POST til din 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"}

Serveren din svarer med JSON som sendes tilbake til LLM-en:

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

LLM-en tar inn svaret og gir innringeren en naturlig oppsummering.

Signaturen beregnes over den rå forespørselsbrødteksten med samme secret som webhook-endepunktet ditt. Verifiser den — verktøyendepunkter er eksponert mot internett og har de samme risikoene for forfalskning som webhooks. Se Verifiser webhook-signaturer.

6. Test flyten

Kjør en mikrofonøkt mot agenten og still spørsmålet verktøyet ditt håndterer («Hvordan er været i 94110?»). Samtaleutskriften viser hele runden:

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

Du kan hente dette via GET /v1/calls/{call_id}/transcript; den rå hendelsesstrømmen (med tidsangivelser og lydforskyvninger per oppføring) finner du på GET /v1/calls/{call_id}/history.

Vanlige fallgruver

Agenten kaller aldri verktøyet

LLM-en avgjør basert på verktøyets beskrivelse. Hvis innringerens spørsmål ikke samsvarer med beskrivelsen, kaller ikke modellen verktøyet. Gjør beskrivelsen mer presis (legg til vanlige synonymer og formuleringer), eller nevn det eksplisitt i agentens ledetekst («Når innringeren spør om været, bruk get_weather.»).

Verktøyet returnerer for mye data

Svar over 6 kB blir avkortet i forhåndsvisningen av utskriften. Returner bare feltene LLM-en trenger — ikke hele raden.

Tidsavbrudd

Verktøyendepunkter har en standard tidsavbruddsgrense på 10 sekunder. Hvis du trenger mer tid, håndter det asynkront: returner {"status": "pending", "request_id": "..."} og vis resultatet via et separat verktøykall.

Versjonering

Hver PATCH av en integrasjon oppretter en ny revisjon. Undersøk GET /v1/integrations/{id}/versions for å se hvem som endret hva. Hvis du ødelegger skjemaet til et verktøy, kan du rulle tilbake manuelt ved å PATCH-e et eldre øyeblikksbilde inn igjen.

Neste trinn

Referanse for integrasjoner

CRUD, overføring, versjonshistorikk.

Spesifikasjon for funksjonsverktøy

Fullstendig JSON-schemagrammatikk og kontrakten for signerte endepunkter.

Verifiser signaturer

Bruk mønsteret for webhook-signaturer på verktøyendepunkter.

API for transkripsjon + historikk

Undersøk hele tur-retur-flyten for et verktøykall.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Bygg en verktøyintegrasjon (API)

Oppbygningen av et verktøy

1. Velg en lagringsstrategi

Direkte på agenten

Lagret integrasjon

2. Opprett integrasjonen

3. Test endepunktet i sandbox

4. Knytt integrasjonen til en agent

5. Implementer endepunktet

6. Test flyten

Vanlige fallgruver

Neste trinn

Referanse for integrasjoner

Spesifikasjon for funksjonsverktøy

Verifiser signaturer

API for transkripsjon + historikk

​Oppbygningen av et verktøy

​1. Velg en lagringsstrategi

Direkte på agenten

Lagret integrasjon

​2. Opprett integrasjonen

​3. Test endepunktet i sandbox

​4. Knytt integrasjonen til en agent

​5. Implementer endepunktet

​6. Test flyten

​Vanlige fallgruver

​Neste trinn

Referanse for integrasjoner

Spesifikasjon for funksjonsverktøy

Verifiser signaturer

API for transkripsjon + historikk

Oppbygningen av et verktøy

1. Velg en lagringsstrategi

2. Opprett integrasjonen

3. Test endepunktet i sandbox

4. Knytt integrasjonen til en agent

5. Implementer endepunktet

6. Test flyten

Vanlige fallgruver

Neste trinn