Izdelajte integracijo orodja (API)

Svojemu agentu omogočite klicanje API-jev med pogovorom — iskanje po zbirki podatkov, ustvarjanje zahtevka, preverjanje naročila.

Integracija orodja je končna točka HTTP za večkratno uporabo, ki jo lahko agent pokliče med klicem. ThunderPhone posredujete opis orodja v shemi JSON in URL končne točke; agent se glede na pogovor odloči, kdaj jo bo poklical, ThunderPhone pa s svojih strežnikov izvede odhodno zahtevo HTTP in odgovor vrne agentu.

Ta vodnik vas vodi skozi izdelavo orodja za preverjanje vremena od začetka do konca.

Zgradba orodja#

Dva dela:

1. Shema — definicija funkcije v slogu OpenAI ({type: "function", function: {name, description, parameters}}), ki LLM-ju pove, kaj orodje počne in katere argumente sprejema.
2. Končna točka — URL, ki ga strežniki ThunderPhone pokličejo, ko se LLM odloči uporabiti orodje. Zahteva je JSON POST, telo pa vsebuje argumente, ki jih izbere LLM.

1. Izberite urejevalnik#

Obe poti ustvarita shranjeno integracijo. Po shranjevanju integracijo pripnite agentu. API za agente nima zapisljivega vdelanega polja tools. Ta vodnik uporablja pot API-ja za integracije.

2. Ustvarite integracijo#

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

Shranite vrnjeni id (UUID).

Pri parametrih naslovov navedite format: "email"#

Parameter, ki prejme e-poštni naslov, mora to navesti v svoji shemi:

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

format je več kot le namig. Preden ThunderPhone pokliče vašo končno točko, pri razrešeni e-poštni shemi odstrani odvečne presledke iz vrednosti, domeno pretvori v male črke, samostojne angleške besede at, dot, underscore, dash in hyphen pretvori v ustrezne znake ter odstrani presledke neposredno okoli znakov @, ., _ in -. Besede imajo enak pomen ne glede na to, ali prepis že vsebuje dobesedni znak @: "john dot smith at gmail dot com" postane john.smith@gmail.com.

Vsak drug notranji presledek je zavrnjen, namesto da bi bil tiho združen. Izgovorjene besede za ločila so podprte samo v angleščini; neangleške ali neprepoznane oblike s presledki so varno zavrnjene. Veljavne internacionalizirane domene in lokalni deli SMTPUTF8 so sprejeti. Vnos v obliki Punycode po normalizaciji razčlenjevalnika ostane Punycode, vnos domene Unicode pa ostane Unicode, zato vaš API prejme običajno predstavitev, ki jo je navedel klicatelj. Če končna vrednost ni veljavna, orodje ni poklicano. Agent prejme invalid_email_argument, ki mu sporoča, naj s klicateljem potrdi črkovanje in znova pošlje dobesedni naslov.

Izpuščen izbirni e-poštni naslov ostane nespremenjen. null, prazen niz ali niz samo s presledki prav tako ostanejo nespremenjeni, kadar je lastnost izbirna ali dopušča vrednost null; enake vrednosti so zavrnjene za obvezen e-poštni naslov, ki ne dopušča vrednosti null.

Lokalne reference sheme, kot sta #/$defs/email in #/definitions/email, ter anyOf, oneOf in allOf so pregledani z omejitvami ciklov in globine. Nelokalni ali nerazrešljiv $ref je znana omejitev uveljavljanja in se posreduje nespremenjen, enako kot klic, katerega posnetek orodja nima uporabne sheme. Kadar potrebujete uporabo tega preverjanja, naj bodo e-poštne sheme lokalne.

Parametri brez uveljavljenega e-poštnega formata se posredujejo natančno tako, kot jih je ustvaril model.

Podprti formati so date-time, time, date, duration, email, hostname, ipv4, ipv6 in uuid; danes je normaliziran in uveljavljen samo email.

3. Preizkusite končno točko v peskovniku#

Preden integracijo povežete z agentom, pošljite podpisano zahtevo s strežnikov ThunderPhone, da potrdite povezljivost:

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

Ta preizkus tudi okrepi zaščito ThunderPhone pred SSRF — zahteve za localhost ali zasebne obsege IP vrnejo 400 code=url_not_allowed.

4. Povežite integracijo z agentom#

Pri ustvarjanju ali posodabljanju agenta priložite prek integration_ids:

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

Z enim agentom lahko povežete več integracij. Poziv agenta se lahko nanje sklicuje po imenu — »uporabite get_weather, ko klicatelj vpraša o vremenskih razmerah« — ali pa jih lahko implicitno prepozna iz opisov shem.

5. Implementirajte končno točko#

Ko agent prikliče orodje, ThunderPhone pošlje podpisano zahtevo 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š strežnik odgovori z JSON-om, ki se posreduje nazaj LLM-ju:

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

LLM obdela ta odgovor in klicatelju glasovno poda povzetek v naravnem jeziku.

6. Preizkusite potek#

Zaženite sejo mikrofona z agentom in postavite vprašanje, ki ga vaše orodje obravnava (»Kakšno je vreme v 94110?«). Prepis klica prikazuje celoten potek:

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

To lahko pridobite prek GET /v1/calls/{call_id}/transcript; tok surovih dogodkov (s časovnimi podatki za posamezne vnose in odmiki zvoka) je na voljo na GET /v1/calls/{call_id}/history.

Pogoste težave#

Naslednji koraki#