Eszközintegráció (API) létrehozása

Tegye lehetővé, hogy ügynöke a beszélgetés közben meghívja API-jait — keressen egy adatbázisban, hozzon létre hibajegyet, keressen meg egy rendelést.

Az eszközintegráció egy újrahasználható HTTP-végpont, amelyet egy ügynök hívás közben meghívhat. Ön megadja a ThunderPhone számára az eszköz JSON-sémás leírását és egy végpont URL-jét; az ügynök a beszélgetés alapján eldönti, mikor hívja meg, a ThunderPhone pedig a szervereiről indítja a kimenő HTTP-kérést, és visszaadja a választ az ügynöknek.

Ez az útmutató végigvezeti Önt egy időjárás-lekérdező eszköz teljes körű elkészítésén.

Egy eszköz felépítése#

Két elem:

1. A séma — egy OpenAI-stílusú függvénydefiníció ({type: "function", function: {name, description, parameters}}), amely megadja az LLM-nek, mit végez az eszköz, és milyen argumentumokat fogad.
2. A végpont — az az URL, amelyet a ThunderPhone szerverei hívnak meg, amikor az LLM úgy dönt, hogy használja az eszközt. A kérés JSON POST-kérés, amelynek törzse az LLM által kiválasztott argumentumokat tartalmazza.

1. Válasszon szerkesztőt#

Mindkét útvonal mentett integrációt hoz létre. Mentés után rendelje hozzá ezt az integrációt az ügynökhöz. Az Agents API nem rendelkezik írható beágyazott tools mezővel. Ez az útmutató az integrációk API-jának használatát ismerteti.

2. Hozza létre az integrációt#

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

Mentse el a visszaadott id értéket (UUID). A fejlécértékek csak írhatók: a válaszok csak a fejlécneveket sorolják fel, és egy későbbi PATCH a tárolt érték megőrzéséhez value nélküli fejlécet is küldhet.

Adja meg a format: "email" értéket a címet fogadó paramétereknél#

Az e-mail-címet fogadó paraméternek ezt a sémájában is jeleznie kell:

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

A format több mint egy utalás. Feloldott e-mail-séma esetén a végpont meghívása előtt a ThunderPhone levágja az érték körüli szóközöket, kisbetűssé alakítja a domaint, az önálló angol at, dot, underscore, dash és hyphen szavakat a megfelelő karakterekre cseréli, valamint eltávolítja az @, ., _ és - közvetlen körüli szóközöket. A szavak jelentése ugyanaz, függetlenül attól, hogy az átirat már tartalmaz-e szó szerinti @ karaktert: "john dot smith at gmail dot com" értéke john.smith@gmail.com lesz.

Minden más belső szóközt a rendszer elutasít ahelyett, hogy észrevétlenül összefűzné. A kimondott elválasztószavak csak angolul támogatottak; a nem angol vagy fel nem ismert, szóközökkel tagolt formák zártan meghiúsulnak. Az érvényes nemzetköziesített domainek és SMTPUTF8 helyi részek elfogadottak. A Punycode-bemenet Punycode marad, a Unicode-domainbemenet pedig Unicode marad az elemző normalizálása után, így az API a hívó által megadott, hagyományos ábrázolást kapja. Ha a végső érték érvénytelen, az eszköz nem kerül meghívásra. Az ügynök megkapja az invalid_email_argument értéket, amely arra utasítja, hogy erősítse meg a helyesírást a hívóval, majd küldje el újra a szó szerinti címet.

A kihagyott opcionális e-mail-cím érintetlen marad. A null, az üres karakterlánc vagy a csak szóközöket tartalmazó karakterlánc szintén érintetlen marad, ha a tulajdonság opcionális vagy null értéket engedélyező; ugyanezeket az értékeket a rendszer elutasítja kötelező, null értéket nem engedélyező e-mail esetén.

A helyi sémareferenciákat, például a #/$defs/email és #/definitions/email értékeket, valamint az anyOf, oneOf és allOf elemeket a rendszer ciklus- és mélységkorlátokkal vizsgálja. A nem helyi vagy feloldhatatlan $ref ismert érvényesítési korlát, és változatlanul továbbításra kerül, csakúgy, mint az olyan hívás, amelynek eszközpillanatképe nem tartalmaz használható sémát. Tartsa helyben az e-mail-sémákat, ha azt szeretné, hogy az ellenőrző kapu érvényesüljön.

A kényszerített e-mail-formátum nélküli paraméterek pontosan úgy kerülnek továbbításra, ahogyan a modell előállította őket.

A támogatott formátumok: date-time, time, date, duration, email, hostname, ipv4, ipv6 és uuid; jelenleg csak az email normalizált és kényszerített.

3. Tesztelje a végpontot sandbox környezetben#

Mielőtt az integrációt egy ügynökhöz kapcsolná, küldjön aláírt kérést a ThunderPhone szervereiről a kapcsolat ellenőrzéséhez:

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

Ez a teszt a ThunderPhone SSRF-védelmét is megerősíti — a localhostra vagy privát IP-tartományokra irányuló kérések 400 code=url_not_allowed választ adnak vissza.

4. Kapcsolja az integrációt egy ügynökhöz#

Ügynök létrehozásakor vagy frissítésekor csatolja az integration_ids használatával:

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

Egy ügynökhöz több integrációt is kapcsolhat. Az ügynök promptja név szerint hivatkozhat rájuk — „használja a get_weather eszközt, amikor a hívó az időjárási körülményekről kérdez” —, vagy implicit módon is felismerheti őket a séma leírásaiból.

5. Valósítsa meg a végpontot#

Amikor az ügynök meghívja az eszközt, a ThunderPhone aláírt POST kérést küld az Ön endpoint_url címére:

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<HMAC-SHA256 hex>
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

A szervere JSON-választ küld, amely visszakerül az LLM-hez:

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

Az LLM feldolgozza ezt a választ, és emberi hangzású összefoglalót mond a hívónak.

6. Tesztelje a folyamatot#

Indítson egy mikrofonos munkamenetet az ügynökkel, és tegye fel azt a kérdést, amelyet az eszköze kezel („Milyen az időjárás 94110-ben?”). A hívás átirata a teljes oda-vissza folyamatot mutatja:

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

Ezt lekérheti a GET /v1/calls/{call_id}/transcript segítségével; a nyers eseményfolyam (bejegyzésenkénti időzítéssel és hanglejátszási eltolásokkal) itt érhető el: GET /v1/calls/{call_id}/history.

A híváslistázási és analitikai felületeken a ThunderPhone mostantól elkülönítve jeleníti meg a teszthívásokat a valós forgalomtól. A Browser Talk tesztek és szimulációk újra felhasználhatnak egy valódi telefonszámot, és bejövő hívásnak tűnhetnek, de nem számítanak bele az éles hívások összesített számába, az értékelésekbe vagy a problémamutatókba.

Gyakori buktatók#

Következő lépések#