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 poslužitelji ThunderPhonea pozivaju kada LLM odluči upotrijebiti alat. Zahtjev je JSON POST, a tijelo sadrži argumente koje je odabrao LLM.

1. Odaberite uređivač#

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).

Navedite format: "email" za parametre adrese#

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

{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

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: <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.

Uobičajene poteškoće#

Sljedeći koraci#