Loo tööriistaintegratsioon (API)

Lase oma agendil vestluse ajal oma API-sid kutsuda — otsida andmebaasist, luua pilet, otsida tellimust.

Tööriistaintegratsioon on korduskasutatav HTTP-lõpp-punkt, mida agent saab kõne ajal kasutada. Annad ThunderPhone'ile tööriista JSON-skeemi kirjelduse ja lõpp-punkti URL-i; agent otsustab vestluse põhjal, millal seda kasutada, ning ThunderPhone teeb oma serveritest väljuva HTTP-päringu ja tagastab vastuse agendile.

See juhend näitab ilmaandmete päringu tööriista loomist algusest lõpuni.

Tööriista ülesehitus#

Kaks osa:

1. Skeem — OpenAI-stiilis funktsiooni definitsioon ({type: "function", function: {name, description, parameters}}), mis kirjeldab LLM-ile, mida tööriist teeb ja milliseid argumente see kasutab.
2. Lõpp-punkt — URL, mida ThunderPhone'i serverid kutsuvad, kui LLM otsustab tööriista kasutada. Päring on JSON POST, mille sisuks on LLM-i valitud argumendid.

1. Vali redaktor#

Mõlemad viisid loovad salvestatud integratsiooni. Pärast salvestamist lisa see integratsioon agendile. Agentide API-s ei ole kirjutatavat reasisest tools välja. See juhend kasutab integratsioonide API varianti.

2. Loo integratsioon#

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

Salvesta tagastatud id (UUID).

Määra aadressiparameetritele format: "email"#

Parameeter, mis võtab vastu e-posti aadressi, peab seda oma skeemis märkima:

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

format on rohkem kui vihje. Lahendatud e-posti skeemi korral kärbib ThunderPhone enne sinu lõpp-punkti kutsumist väärtuse, muudab domeeni väiketähtedeks, teisendab eraldiseisvad ingliskeelsed sõnad at, dot, underscore, dash ja hyphen nende märkideks ning eemaldab tühimärgid otse märkide @, ., _ ja - ümbert. Sõnadel on sama tähendus olenemata sellest, kas transkript juba sisaldab sõnasõnalist märki @: "john dot smith at gmail dot com" muutub väärtuseks john.smith@gmail.com.

Kõik muud sisemised tühimärgid lükatakse tagasi, mitte ei ühendata vaikselt. Öeldud eraldussõnad toimivad ainult inglise keeles; muukeelsed või tuvastamata tühikutega vormid nurjuvad suletult. Kehtivad rahvusvahelised domeenid ja SMTPUTF8 lokaalosad on lubatud. Punycode'i sisend jääb punycode'iks ning Unicode'i domeenisisend jääb pärast parseri normaliseerimist Unicode'iks, seega saab sinu API helistaja esitatud tavapärase esituse. Kui lõppväärtus on vigane, tööriista ei kutsuta. Agent saab väärtuse invalid_email_argument, mis juhendab teda kinnitama helistajaga õigekirja ja saatma sõnasõnalise aadressi uuesti.

Välja jäetud valikulist e-posti aadressi ei muudeta. null, tühi string või ainult tühimärkidest koosnev string jäetakse samuti muutmata, kui atribuut on valikuline või nullitav; nõutud, mittenullitava e-posti aadressi puhul lükatakse samad väärtused tagasi.

Kohalikke skeemiviiteid, näiteks #/$defs/email ja #/definitions/email, ning anyOf, oneOf ja allOf kontrollitakse tsükli- ja sügavuspiirangutega. Mittekohalik või lahendamatu $ref on teadaolev jõustamispiirang ning see edastatakse muutmata kujul, nagu ka kutse, mille tööriista hetktõmmisel puudub kasutatav skeem. Kui vajad selle kontrolli rakendumist, hoia e-posti skeemid kohalikud.

Parameetrid, millel puudub jõustatud e-posti vorming, edastatakse täpselt sellisena, nagu mudel need koostas.

Toetatud vormingud on date-time, time, date, duration, email, hostname, ipv4, ipv6 ja uuid; praegu normaliseeritakse ja jõustatakse ainult email.

3. Testi lõpp-punkti liivakastis#

Enne integratsiooni agendiga ühendamist saada ThunderPhone'i serveritest allkirjastatud päring, et kinnitada ühenduvust:

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

See test tugevdab ka ThunderPhone'i SSRF-kaitseid — localhosti või privaatsete IP-vahemike päringud tagastavad 400 code=url_not_allowed.

4. Seo integratsioon häälagendiga#

Lisa integration_ids, kui lood või uuendad häälagenti:

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

Ühe häälagendiga saab siduda mitu integratsiooni. Häälagendi viip võib neile nime järgi viidata — „kasuta get_weather, kui helistaja küsib ilmaolude kohta” — või saab häälagent need skeemikirjelduste põhjal kaudselt tuvastada.

5. Rakenda lõpp-punkt#

Kui häälagent tööriista käivitab, saadab ThunderPhone sinu endpoint_url-ile allkirjastatud POST-päringu:

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

Sinu server vastab JSON-iga, mis edastatakse tagasi LLM-ile:

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

LLM töötleb vastust ja ütleb helistajale inimkeelse kokkuvõtte.

6. Testi tsüklit#

Käivita häälagendi vastu mikrofoniseanss ja esita küsimus, mida sinu tööriist käsitleb („Milline on ilm sihtnumbriga 94110 piirkonnas?”). Kõne transkriptsioon näitab täielikku edasi-tagasi päringut:

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

Selle saad pärida kaudu GET /v1/calls/{call_id}/transcript; töötlemata sündmuste voog (iga kirje ajastuse ja heli nihetega) asub siin: GET /v1/calls/{call_id}/history.

Levinud probleemid#

Järgmised sammud#