Rakenna työkalun integraatio (API)

Työkalintegraatio on uudelleenkäytettävä HTTP-päätepiste, jonka agentti voi kutsua puhelun aikana. Annat ThunderPhonelle työkalun JSON-skeemakuvauksen sekä päätepisteen URL-osoitteen; agentti päättää keskustelun perusteella, milloin sitä kutsutaan, ja ThunderPhone tekee lähtevän HTTP-pyynnön palvelimiltaan sekä palauttaa vastauksen agentille.

Hallintapaneeli kattaa useimmat työkalutarpeet ilman tätä APIa: Yhteydet → Sovellukset yhdistää Slackin, HubSpotin, Salesforcen, Google Calendarin, Google Sheetsin ja Cal.comin muutamalla OAuth-klikkauksella; Yhteydet → APIt muuttaa minkä tahansa HTTP-APIn agentin toiminnoksi (liitä cURL-komento, niin AI-avustaja luonnostelee työkalun, jossa on sisäänrakennettu Testaa pyyntö -toiminto); ja Yhteydet → MCP lisää MCP-palvelimia. Katso Yhteydet. Tämä opas käsittelee API-näkymän taustalla olevaa raakaa APIa.

Tässä oppaassa rakennetaan sääntarkistustyökalu alusta loppuun.

Työkalun rakenne

Kaksi osaa:

Skeema — OpenAI-tyylinen funktiomääritelmä ({type: "function", function: {name, description, parameters}}), joka kertoo LLM:lle, mitä työkalu tekee ja mitä argumentteja se ottaa.
Päätepiste — URL-osoite, jota ThunderPhonen palvelimet kutsuvat, kun LLM päättää käyttää työkalua. Pyyntö on JSON-muotoinen POST-pyyntö, jonka runkona ovat LLM:n valitsemat argumentit.

1. Valitse tallennusstrategia

Agenttiin upotettu

Liitä kertakäyttöinen työkalu agentin tools-taulukkoon. Yksinkertaista, mutta ei uudelleenkäytettävää.

Tallennettu integraatio

Tallenna työkalu uudelleenkäytettävänä integraationa ja linkitä se useisiin agentteihin. Suositellaan kaikkeen, mitä käytetään useammin kuin kerran.

Tässä oppaassa käytetään tallennetun integraation polkua.

2. Luo integraatio

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

Tallenna palautettu id (UUID).

Panosta työkalun ja jokaisen parametrin description-kuvaukseen. LLM käyttää näitä merkkijonoja ajonaikaisesti päättääkseen, kutsuuko se työkalua ja miten. Epämääräiset kuvaukset → epämääräiset työkalukutsut.

3. Testaa päätepiste hiekkalaatikossa

Ennen kuin linkität integraation agenttiin, lähetä allekirjoitettu pyyntö ThunderPhonen palvelimilta varmistaaksesi yhteyden:

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

Tämä testi myös vahvistaa ThunderPhonen SSRF-suojauksia — localhostiin tai yksityisiin IP-osoitealueisiin kohdistuvat pyynnöt palauttavat 400 code=url_not_allowed.

4. Liitä integraatio agenttiin

Liitä integration_ids-kentän kautta, kun luot tai päivität agentin:

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

Voit liittää useita integraatioita yhteen agenttiin. Agentin kehotteessa voidaan viitata niihin nimellä — “use get_weather when the caller asks about conditions” — tai agentti voi tunnistaa ne epäsuorasti skeemakuvausten perusteella.

5. Toteuta päätepiste

Kun agentti kutsuu työkalua, ThunderPhone lähettää allekirjoitetun POST-pyynnön endpoint_url-osoitteeseesi:

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

Palvelimesi vastaa JSONilla, joka välitetään takaisin LLM:lle:

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

LLM käsittelee vastauksen ja kertoo soittajalle selkokielisen yhteenvedon.

Allekirjoitus lasketaan pyynnön raakasisällöstä käyttäen samaa secret-arvoa kuin webhook-päätepisteesi. Vahvista se — työkalujen päätepisteet ovat internetiin näkyviä ja niihin kohdistuu samoja väärentämisriskejä kuin webhookeihin. Katso Webhook-allekirjoitusten vahvistaminen.

6. Testaa kokonaisuus

Käynnistä mikrofonisessio agenttia vasten ja esitä kysymys, jota työkalusi käsittelee (“What’s the weather in 94110?”). Puhelun transkriptio näyttää koko kierroksen:

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

Voit hakea tämän GET /v1/calls/{call_id}/transcript-kutsulla; raaka tapahtumavirta (merkintäkohtaisine ajoituksineen ja äänisiirtymineen) on saatavilla GET /v1/calls/{call_id}/history-kutsulla.

Yleiset sudenkuopat

Agentti ei koskaan kutsu työkalua

LLM tekee päätöksen työkalun kuvauksen perusteella. Jos soittajan kysymys ei vastaa kuvausta, malli ei kutsu työkalua. Tarkennna kuvausta (lisää yleisiä synonyymejä ja ilmaisutapoja) tai mainitse se nimenomaisesti agentin kehotteessa (“When the caller asks about weather, use get_weather.”).

Työkalu palauttaa liikaa dataa

Yli 6 kB:n vastaukset katkaistaan transkription esikatselussa. Palauta vain LLM:n tarvitsemat kentät — älä koko tietuettasi.

Aikakatkaisut

Työkalujen päätepisteiden oletusaikakatkaisu on 10 sekuntia. Jos tarvitset enemmän aikaa, käsittele pyyntö asynkronisesti: palauta {"status": "pending", "request_id": "..."} ja tuo tulos esiin erillisellä työkalukutsulla.

Versiointi

Jokainen integraation PATCH luo uuden revision. Tarkista GET /v1/integrations/{id}/versions nähdäksesi, kuka muutti mitäkin. Jos rikot työkalun skeeman, voit palauttaa sen manuaalisesti tekemällä PATCH-pyynnön vanhemmällä tilannevedoksella.

Seuraavat vaiheet

Integraatioiden viite

CRUD, siirto, versiohistoria.

Function Tools -määritys

Täydellinen JSON-skeemakielioppi ja allekirjoitettujen päätepisteiden sopimus.

Vahvista allekirjoitukset

Käytä webhook-allekirjoitusmallia työkalujen päätepisteisiin.

Transkriptio- ja historia-API

Tarkastele työkalukutsun koko edestakaista kulkua.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Rakenna työkalun integraatio (API)

Työkalun rakenne

1. Valitse tallennusstrategia

Agenttiin upotettu

Tallennettu integraatio

2. Luo integraatio

3. Testaa päätepiste hiekkalaatikossa

4. Liitä integraatio agenttiin

5. Toteuta päätepiste

6. Testaa kokonaisuus

Yleiset sudenkuopat

Seuraavat vaiheet

Integraatioiden viite

Function Tools -määritys

Vahvista allekirjoitukset

Transkriptio- ja historia-API

​Työkalun rakenne

​1. Valitse tallennusstrategia

Agenttiin upotettu

Tallennettu integraatio

​2. Luo integraatio

​3. Testaa päätepiste hiekkalaatikossa

​4. Liitä integraatio agenttiin

​5. Toteuta päätepiste

​6. Testaa kokonaisuus

​Yleiset sudenkuopat

​Seuraavat vaiheet

Integraatioiden viite

Function Tools -määritys

Vahvista allekirjoitukset

Transkriptio- ja historia-API

Työkalun rakenne

1. Valitse tallennusstrategia

2. Luo integraatio

3. Testaa päätepiste hiekkalaatikossa

4. Liitä integraatio agenttiin

5. Toteuta päätepiste

6. Testaa kokonaisuus

Yleiset sudenkuopat

Seuraavat vaiheet