Sukurkite įrankio integraciją (API)

įrankio integracija yra pakartotinai naudojamas HTTP galinis taškas, kurį agentas gali iškviesti pokalbio metu. Pateikiate ThunderPhone įrankio JSON schemos aprašą ir galinio taško URL; agentas pagal pokalbį nusprendžia, kada jį iškviesti, o ThunderPhone iš savo serverių siunčia išeinantį HTTP prašymą ir grąžina atsakymą agentui.

Šiame vadove žingsnis po žingsnio sukursite orų paieškos įrankį.

Įrankio sandara

Dvi dalys:

1. Schema — OpenAI stiliaus funkcijos apibrėžimas ({type: "function", function: {name, description, parameters}}), nurodantis LLM, ką įrankis daro ir kokius argumentus priima.
2. Galinis taškas — URL, kurį ThunderPhone serveriai iškviečia, kai LLM nusprendžia naudoti įrankį. Prašymas yra JSON POST, o jo turinį sudaro LLM pasirinkti argumentai.

1. Pasirinkite saugojimo strategiją

Šiame vadove naudojamas išsaugotos integracijos būdas.

2. Sukurkite integraciją

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

Išsaugokite grąžintą id (UUID).

3. Išbandykite galinį tašką smėlio dėžėje

Prieš susiedami integraciją su agentu, siųskite pasirašytą prašymą iš ThunderPhone serverių, kad patvirtintumėte ryšį:

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

Šis testas taip pat sustiprina ThunderPhone SSRF apsaugas — prašymai į localhost arba privačius IP diapazonus grąžina 400 code=url_not_allowed.

4. Susiekite integraciją su agentu

Pridėkite naudodami integration_ids, kai kuriate arba atnaujinate agentą:

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

Su vienu agentu galite susieti daug integracijų. Agento nurodyme galite jas nurodyti pagal pavadinimą — „naudokite get_weather, kai skambinantysis klausia apie oro sąlygas“ — arba agentas gali jas netiesiogiai aptikti pagal schemos aprašus.

5. Įdiekite galinį tašką

Kai agentas iškviečia įrankį, ThunderPhone siunčia pasirašytą POST užklausą į jūsų 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"}

Jūsų serveris atsako JSON duomenimis, kurie perduodami atgal LLM:

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

LLM apdoroja šį atsakymą ir žodžiu pateikia skambinančiajam suprantamą santrauką.

6. Išbandykite ciklą

Paleiskite mikrofono sesiją su agentu ir užduokite klausimą, kurį apdoroja jūsų įrankis („Kokie orai 94110?“). Skambučio nuoraše rodomas visas užklausos ir atsakymo ciklas:

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

Jį galite gauti naudodami GET /v1/calls/{call_id}/transcript; neapdorotų įvykių srautas su kiekvieno įrašo laiko informacija ir garso poslinkiais pasiekiamas adresu GET /v1/calls/{call_id}/history.

Dažnos klaidos

Tolesni veiksmai