Unda ujumuishaji wa zana (API)

Ujumuishaji wa zana ni endpoint ya HTTP inayoweza kutumika tena ambayo ejenti inaweza kuita wakati wa simu. Unaipa ThunderPhone maelezo ya JSON-schema ya zana pamoja na URL ya endpoint; ejenti huamua lini ya kuiita kulingana na mazungumzo, na ThunderPhone hutuma ombi la HTTP linalotoka kutoka kwenye seva zake na kurudisha jibu kwa ejenti.

Mwongozo huu unaelekeza uundaji wa zana ya kutafuta hali ya hewa hatua kwa hatua.

Muundo wa zana

Sehemu mbili:

1. Schema — ufafanuzi wa function wa mtindo wa OpenAI ({type: "function", function: {name, description, parameters}}) unaoieleza LLM zana hufanya nini na hukubali hoja zipi.
2. Endpoint — URL ambayo seva za ThunderPhone huiita wakati LLM inapoamua kutumia zana. Ombi ni JSON POST yenye hoja zilizochaguliwa na LLM kama mwili wa ombi.

1. Chagua mkakati wa uhifadhi

Mwongozo huu unatumia njia ya ujumuishaji uliohifadhiwa.

2. Unda ujumuishaji

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

Hifadhi id iliyorejeshwa (UUID).

3. Jaribu endpoint katika sandbox

Kabla ya kuunganisha ujumuishaji na ejenti, tuma ombi lililotiwa sahihi kutoka kwenye seva za ThunderPhone ili kuthibitisha muunganisho:

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

Jaribio hili pia huimarisha kinga za SSRF za ThunderPhone — maombi kwa localhost au masafa binafsi ya IP hurudisha 400 code=url_not_allowed.

4. Unganisha muunganisho na ejenti

Ambatisha kupitia integration_ids unapounda au kusasisha ejenti:

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

Unaweza kuunganisha miunganisho mingi kwa ejenti moja. prompt ya ejenti inaweza kuzirejelea kwa jina — "tumia get_weather mpigaji simu anapouliza kuhusu hali ya hewa" — au inaweza kuzigundua kwa njia isiyo ya moja kwa moja kutoka kwenye maelezo ya schema.

5. Tekeleza endpoint

Ejenti inapoitisha zana, ThunderPhone hutuma POST yenye sahihi kwa endpoint_url yako:

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

Seva yako hujibu kwa JSON ambayo hurudishwa kwa LLM:

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

LLM hupokea jibu hilo na kumwambia mpigaji simu muhtasari unaoeleweka kwa binadamu.

6. Jaribu mzunguko

Endesha kipindi cha mic dhidi ya ejenti na uulize swali linaloshughulikiwa na zana yako ("Hali ya hewa ikoje katika 94110?"). Nakala ya mazungumzo ya simu inaonyesha mzunguko mzima:

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

Unaweza kupata hii kupitia GET /v1/calls/{call_id}/transcript; mtiririko ghafi wa matukio (wenye muda wa kila ingizo na mipangilio ya sauti) uko kwenye GET /v1/calls/{call_id}/history.

Changamoto za kawaida

Hatua zinazofuata