Loo tööriistaintegratsioon (API)

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

See juhend näitab ilmaotsingu tööriista loomist algusest lõpuni.

Tööriista ülesehitus

Kaks osa:

1. Skeem — OpenAI stiilis funktsioonimääratlus ({type: "function", function: {name, description, parameters}}), mis ütleb 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 salvestusstrateegia

See juhend kasutab salvestatud integratsiooni teed.

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

3. Testi lõpp-punkti liivakastis

Enne integratsiooni agendiga sidumist saada ThunderPhone'i serveritest allkirjastatud päring, et kontrollida ü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 häälagendi loomisel või värskendamisel:

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 saad siduda mitu integratsiooni. Häälagendi viibas saad neile nime järgi viidata — „kasuta get_weather, kui helistaja küsib ilmaolude kohta” — või võib häälagent need skeemikirjelduste põhjal kaudselt tuvastada.

5. Rakenda endpoint

Kui häälagent kutsub tööriista välja, 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 vastuse ja annab helistajale sellest loomulikus keeles kokkuvõtte.

6. Testi töövoogu

Käivita häälagendi vastu mikrofoni seanss ja küsi küsimus, mida sinu tööriist käsitleb („Milline on ilm sihtnumbriga 94110 piirkonnas?”). Kõne transkriptsioon näitab kogu päringu-vastuse tsüklit:

{
  "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; toorsündmuste voog (koos iga kirje ajastuse ja heli nihetega) asub aadressil GET /v1/calls/{call_id}/history.

Levinud vead

Järgmised sammud