Byg en værktøjsintegration (API)

En værktøjsintegration er et genanvendeligt HTTP-slutpunkt, som en agent kan kalde under et opkald. Du giver ThunderPhone en JSON-schema-beskrivelse af værktøjet samt en slutpunkts-URL; agenten beslutter, hvornår det skal kaldes, baseret på samtalen, og ThunderPhone udfører den udgående HTTP-anmodning fra sine servere og returnerer svaret til agenten.

Dashboardet dækker de fleste værktøjsbehov uden dette API: Forbindelser → Apps forbinder Slack, HubSpot, Salesforce, Google Kalender, Google Sheets og Cal.com med få OAuth-klik; Forbindelser → API’er gør ethvert HTTP-API til en agenthandling (indsæt en cURL-kommando, og en AI-guide udarbejder værktøjet med en indbygget Testanmodning); og Forbindelser → MCP tilføjer MCP-servere. Se Forbindelser. Denne vejledning beskriver det underliggende rå API bag API-grænsefladen.

Denne vejledning gennemgår opbygningen af et værktøj til vejroplysninger fra start til slut.

Et værktøjs opbygning

To dele:

Schemaet — en funktionsdefinition i OpenAI-stil ({type: "function", function: {name, description, parameters}}) der fortæller LLM’en, hvad værktøjet gør, og hvilke argumenter det tager.
Slutpunktet — den URL, ThunderPhones servere kalder, når LLM’en beslutter at bruge værktøjet. Anmodningen er en JSON POST med LLM’ens valgte argumenter som brødtekst.

1. Vælg en lagringsstrategi

Indlejret på agenten

Tilknyt et enkeltstående værktøj til agentens tools-array. Simpelt, men ikke genanvendeligt.

Gemt integration

Gem værktøjet som en genanvendelig integration og tilknyt det fra mange agenter. Anbefales til alt, der bruges mere end én gang.

Denne vejledning bruger stien med gemt integration.

2. Opret integrationen

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

Gem det returnerede id (en UUID).

Brug reel tid på description for værktøjet og hver parameter. LLM’en bruger disse strenge under kørsel til at afgøre, om og hvordan værktøjet skal kaldes. Vage beskrivelser → vage værktøjskald.

3. Sandbox-test slutpunktet

Før du tilknytter integrationen til en agent, skal du sende en signeret anmodning fra ThunderPhones servere for at bekræfte forbindelsen:

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 test styrker også ThunderPhones SSRF-beskyttelse — anmodninger til localhost eller private IP-områder returnerer 400 code=url_not_allowed.

4. Knyt integrationen til en agent

Tilknyt via integration_ids, når du opretter eller opdaterer 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 integrationer til én agent. Agentens prompt kan henvise til dem ved navn — “brug get_weather, når opkalderen spørger om forholdene” — eller den kan finde dem implicit ud fra skemabeskrivelserne.

5. Implementer endpointet

Når agenten kalder værktøjet, sender ThunderPhone en signeret 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"}

Din server svarer med JSON, som sendes tilbage til LLM’en:

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

LLM’en behandler svaret og giver opkalderen en menneskeligt formuleret opsummering.

Signaturen beregnes over den rå anmodningsbody med den samme secret som dit webhook-endpoint. Bekræft den — værktøjsendpoints er eksponeret på internettet og er udsat for de samme risici for forfalskning som webhooks. Se Bekræft webhook-signaturer.

6. Test forløbet

Kør en mikrofonsession mod agenten, og stil det spørgsmål, som dit værktøj håndterer (“Hvad er vejret i 94110?”). Opkaldets transskription viser hele forløbet:

{
  "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å hændelsesstrøm (med tidsangivelser og lydforskydninger pr. post) findes på GET /v1/calls/{call_id}/history.

Almindelige faldgruber

Agenten kalder aldrig værktøjet

LLM’en beslutter ud fra værktøjets beskrivelse. Hvis opkalderens spørgsmål ikke matcher beskrivelsen, kalder modellen ikke værktøjet. Gør beskrivelsen mere præcis (tilføj almindelige synonymer og formuleringer), eller nævn det eksplicit i agentens prompt (“Når opkalderen spørger om vejret, skal du bruge get_weather.”).

Værktøjet returnerer for mange data

Svar over 6 kB afkortes i forhåndsvisningen af transskriptionen. Returner kun de felter, som LLM’en har brug for — ikke hele din række.

Tidsudløb

Værktøjsendpoints har en standardtimeout på 10 sekunder. Hvis du har brug for længere tid, skal du håndtere det asynkront: returner {"status": "pending", "request_id": "..."} og vis resultatet via et separat værktøjskald.

Versionsstyring

Hver PATCH af en integration opretter en ny revision. Undersøg GET /v1/integrations/{id}/versions for at se, hvem der ændrede hvad. Hvis du ødelægger et værktøjs skema, kan du rulle tilbage manuelt ved at PATCH’e et ældre snapshot tilbage.

Næste trin

Reference til integrationer

CRUD, overførsel, versionshistorik.

Specifikation for funktionsværktøjer

Fuld JSON-schema-grammatik og kontrakten for signerede endpoints.

Bekræft signaturer

Anvend mønstret for webhook-signaturer på værktøjsendpoints.

API til transskription + historik

Undersøg hele tur-retur-forløbet for et værktøjskald.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Byg en værktøjsintegration (API)

Et værktøjs opbygning

1. Vælg en lagringsstrategi

Indlejret på agenten

Gemt integration

2. Opret integrationen

3. Sandbox-test slutpunktet

4. Knyt integrationen til en agent

5. Implementer endpointet

6. Test forløbet

Almindelige faldgruber

Næste trin

Reference til integrationer

Specifikation for funktionsværktøjer

Bekræft signaturer

API til transskription + historik

​Et værktøjs opbygning

​1. Vælg en lagringsstrategi

Indlejret på agenten

Gemt integration

​2. Opret integrationen

​3. Sandbox-test slutpunktet

​4. Knyt integrationen til en agent

​5. Implementer endpointet

​6. Test forløbet

​Almindelige faldgruber

​Næste trin

Reference til integrationer

Specifikation for funktionsværktøjer

Bekræft signaturer

API til transskription + historik

Et værktøjs opbygning

1. Vælg en lagringsstrategi

2. Opret integrationen

3. Sandbox-test slutpunktet

4. Knyt integrationen til en agent

5. Implementer endpointet

6. Test forløbet

Almindelige faldgruber

Næste trin