ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Developer cookbook

Izradite integraciju alata (API)

Omogućite svojem agentu da tijekom razgovora poziva vaše API-je — pretražuje bazu podataka, stvara tiket, provjerava narudžbu.

Integracija alata višekratno je upotrebljiva HTTP krajnja točka koju agent može pozvati tijekom poziva. ThunderPhoneu dajete opis alata u JSON shemi i URL krajnje točke; agent na temelju razgovora odlučuje kada je pozvati, a ThunderPhone sa svojih poslužitelja šalje odlazni HTTP zahtjev i vraća odgovor agentu.

Ovaj vodič vodi Vas kroz izradu alata za dohvaćanje vremenske prognoze od početka do kraja.

Anatomija alata

Dva dijela:

  1. Shema — definicija funkcije u stilu OpenAI-ja ({type: "function", function: {name, description, parameters}}) koja LLM-u govori što alat radi i koje argumente prihvaća.
  2. Krajnja točka — URL koji ThunderPhoneovi poslužitelji pozivaju kada se integracija pokrene. Za alate koje pokreće agent zahtjev je JSON POST s argumentima koje je LLM odabrao kao tijelom zahtjeva.

1. Odaberite uređivač

Nadzorna ploča

Otvorite Povezivanja → API-ji, izradite ili uredite API vezu, prebacite uređivač parametara na JSON i tamo dodajte format.

API za integracije

Izradite specifikaciju pomoću POST /v1/integrations ili je ažurirajte pomoću PATCH /v1/integrations/{id}.

Oba načina stvaraju spremljenu integraciju. Nakon spremanja priložite tu integraciju agentu. API za agente nema upisivo ugrađeno polje tools. Ovaj vodič koristi put API-ja za integracije.

2. Izradite integraciju

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

Spremite vraćeni id (UUID). Vrijednosti zaglavlja dostupne su samo za upis: odgovori navode samo nazive zaglavlja, a kasniji PATCH može poslati zaglavlje bez value kako bi se zadržala spremljena vrijednost.

Parametar koji prima adresu e-pošte trebao bi to navesti u svojoj shemi:

"email": { "type": "string", "format": "email", "description": "The caller's email address" }

format je više od naznake. Za razriješenu shemu e-pošte, prije poziva vaše krajnje točke ThunderPhone uklanja razmake s početka i kraja vrijednosti, pretvara domenu u mala slova, samostalne engleske riječi at, dot, underscore, dash i hyphen pretvara u njihove znakove te uklanja razmake neposredno oko znakova @, ., _ i -. Riječi imaju isto značenje bez obzira na to sadrži li transkript već doslovni znak @: "john dot smith at gmail dot com" postaje john.smith@gmail.com.

Svaki drugi unutarnji razmak odbija se umjesto da se tiho spoji. Izgovorene riječi za razdjelnike podržane su samo na engleskom; oblici s razmacima na drugim jezicima ili neprepoznati oblici sigurno ne prolaze. Prihvaćaju se valjane internacionalizirane domene i lokalni dijelovi SMTPUTF8. Unos u punycodeu ostaje u punycodeu, a Unicode unos domene ostaje Unicode nakon normalizacije parsera, tako da vaš API prima uobičajeni prikaz koji je naveo pozivatelj. Ako je konačna vrijednost nevaljana, alat se ne poziva. Agent prima invalid_email_argument, što mu govori da s pozivateljem potvrdi način pisanja i ponovno pošalje doslovnu adresu.

Izostavljena neobavezna e-pošta ostaje nepromijenjena. null, prazan niz ili niz koji sadrži samo razmake također ostaju nepromijenjeni kada je svojstvo neobavezno ili dopušta null; iste se vrijednosti odbijaju za obaveznu e-poštu koja ne dopušta null.

Lokalne reference sheme kao što su #/$defs/email i #/definitions/email, kao i anyOf, oneOf i allOf, provjeravaju se uz ograničenja ciklusa i dubine. Nelokalni ili nerazrješivi $ref poznato je ograničenje provedbe i prosljeđuje se nepromijenjen, kao i poziv čija snimka alata nema upotrebljivu shemu. Zadržite sheme e-pošte lokalnima kada trebate primijeniti provjeru.

Parametri bez provedbenog formata e-pošte prosljeđuju se točno onako kako ih je model proizveo.

Podržani formati su date-time, time, date, duration, email, hostname, ipv4, ipv6 i uuid; danas se normalizira i provodi samo email.

3. Testirajte krajnju točku u sandboxu

Prije nego što povežete integraciju s agentom, pošaljite potpisani zahtjev s ThunderPhone poslužitelja kako biste potvrdili povezivost:

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_code": 200,
  "reason": "OK",
  "latency_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_body_preview": "{\"temperature_f\": 64, ...}",
  "response_truncated": false
}

Test sadrži ista ThunderPhone zaglavlja kao poziv alata uživo, potpisan tajnom webhooka Vaše organizacije, pa također testira Vašu provjeru potpisa: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 i X-ThunderPhone-Signature. body se šalje kao JSON i potpisuje se u poslanom obliku; uz GET argumente stavite u URL. Telefonski brojevi poziva ne šalju se jer test nema poziv.

Ovaj test također učvršćuje ThunderPhone SSRF zaštite — zahtjevi za localhost ili privatne IP raspone vraćaju 400 code=url_not_allowed.

4. Povežite integraciju s agentom

Priložite putem integration_ids kada stvarate ili ažurirate agenta:

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

Možete povezati više integracija s jednim agentom. Uputa agenta može ih navesti po nazivu — „upotrijebi get_weather kada pozivatelj pita o vremenskim uvjetima” — ili ih može implicitno otkriti iz opisa sheme.

5. Implementirajte krajnju točku

Kada agent pozove alat, ThunderPhone šalje potpisani POST na vaš endpoint_url:

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<HMAC-SHA256 hex>
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

Vaš poslužitelj odgovara JSON-om koji se prosljeđuje natrag LLM-u:

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

LLM obrađuje taj odgovor i pozivatelju izgovara sažetak prirodnim jezikom.

6. Testirajte cijeli tijek

Pokrenite mikrofonsku sesiju prema agentu i postavite pitanje kojim se vaš alat bavi („Kakvo je vrijeme u 94110?”). Transkript poziva prikazuje cijeli tijek:

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

Ovo možete dohvatiti putem GET /v1/calls/{call_id}/transcript; tok neobrađenih događaja (s vremenom svake stavke i pomacima zvuka) nalazi se na GET /v1/calls/{call_id}/history.

U Zeusu dugi prijepisi poziva sada uključuju početak i kraj poziva, dok se srednji dio prema potrebi prikazuje po stranicama, tako da i dalje možete vidjeti kako je poziv završio.

Na popisima poziva i u analitičkim prikazima ThunderPhone sada testne pozive prikazuje odvojeno od stvarnog prometa. Testovi i simulacije u Browser Talku mogu ponovno upotrijebiti stvarni telefonski broj i mogu izgledati kao dolazni pozivi, ali se ne ubrajaju u ukupni broj produkcijskih poziva, ocjene ni metrike problema.

Uobičajene poteškoće

Agent nikada ne poziva alat

LLM odlučuje na temelju opisa alata. Ako pitanje pozivatelja ne odgovara opisu, model neće pozvati alat. Precizirajte opis (dodajte uobičajene sinonime i formulacije) ili ga izričito navedite u uputi agenta („Kada pozivatelj pita o vremenu, upotrijebi get_weather.”).

Alat vraća previše podataka

Rezultat alata ostaje u razgovoru, a agent ga ponovno čita pri svakom sljedećem koraku, pa velik rezultat povećava trošak i odgodu ostatka poziva. Rezultat veći od 100.000 znakova skraćuje se na pregled, a agentu se navodi da je nepotpun. Pri vrlo dugom pozivu stariji rezultati alata mogu se ukloniti iz memorije agenta; može ponovno pozvati alat ako su mu potrebni.

Kako biste zadržali male rezultate:

  • Vratite samo polja koja su agentu potrebna, a ne cijeli zapis.
  • Dodajte parametar kako bi agent mogao tražiti jednu stavku ili kategoriju odjednom umjesto dohvaćanja svega.
  • Velik referentni sadržaj (jelovnike, kataloge, pravila) umjesto toga stavite u bazu znanja.

Pošaljite testni zahtjev na nadzornoj ploči prikazuje koliko je rezultat velik i upozorava kada je velik.

Vremenska ograničenja

Krajnje točke alata imaju zadano vremensko ograničenje od 20 sekundi. Postavite spec.timeout da biste omogućili do 180 sekundi (pogledajte Alati). Za alat koji čeka osobu ili spor zadatak postavite spec.wait_mode na "hold": pozivatelj čuje glazbu na čekanju umjesto govornih obavijesti, a spec.timeout može biti do 600 sekundi. Vaša krajnja točka i dalje odgovara unutar 180 sekundi; za dulje čekanje odmah vratite {"status": "pending", "request_id": "..."} i rezultat dostavite kasnije putem POST /v1/calls/{call_id}/tool-results. Pogledajte Duga čekanja.

Verzioniranje

Svaki PATCH integracije stvara novu reviziju. Pregledajte GET /v1/integrations/{id}/versions kako biste vidjeli tko je što promijenio. Ako pokvarite shemu alata, možete je ručno vratiti slanjem PATCH zahtjeva sa starijom snimkom.


Sljedeći koraci