--- title: "Eszközintegráció (API) létrehozása" description: "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. Az irányítópult a legtöbb eszközigényt lefedi ezen API nélkül: a **Kapcsolatok → Alkalmazások** néhány OAuth-kattintással csatlakoztatja a Slacket, a HubSpotot, a Salesforce-t, a Google Naptárt, a Google Táblázatokat és a Cal.comot; a **Kapcsolatok → API-k** bármely HTTP API-t ügynökműveletté alakít (illesszen be egy cURL-parancsot, és egy AI-varázsló elkészíti az eszköz vázlatát beépített Tesztkéréssel); a **Kapcsolatok → MCP** pedig MCP-szervereket ad hozzá. Lásd: [Kapcsolatok](/hu/guides/concepts). Ez az útmutató az API-k felülete mögötti közvetlen API-t ismerteti. 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 Nyissa meg a **Kapcsolatok → API-k** menüt, hozzon létre vagy szerkesszen egy API-kapcsolatot, állítsa a paraméterszerkesztőt **JSON** módba, majd adja hozzá ott a sémát. Hozza létre a specifikációt a `POST /v1/integrations` végponttal, vagy frissítse a `PATCH /v1/integrations/{id}` végponttal. 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 ```bash 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. Fordítson valódi figyelmet az eszköz `description` mezőjére és minden paraméterére. Az LLM ezeket a karakterláncokat futásidőben használja annak eldöntésére, hogy meghívja-e az eszközt, és ha igen, hogyan. Homályos leírások → homályos eszközhívások. ### 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: ```json "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: ```bash 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" } }' ``` ```json Response { "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: ```bash 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=,v1= X-ThunderPhone-Signature: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` A szervere JSON-választ küld, amely visszakerül az LLM-hez: ```json {"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. Az aláírás a nyers kéréstörzs alapján, a webhook-végpontjával azonos `secret` használatával készül. **Ellenőrizze** — az eszközvégpontok internet felől elérhetők, ezért a webhookokhoz hasonló hamisítási kockázatoknak vannak kitéve. Lásd: [Webhook-aláírások ellenőrzése](/hu/guides/verify-webhook-signatures). ## 6. Tesztelje a folyamatot Indítson egy [mikrofonos munkamenetet](/api-reference/mic-sessions) 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: ```json { "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`](/api-reference/calls#get-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`](/api-reference/calls#get-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 Az LLM az eszköz leírása alapján dönt. Ha a hívó kérdése nem felel meg a leírásnak, a modell nem fogja meghívni az eszközt. Pontosítsa a leírást (adjon hozzá gyakori szinonimákat és megfogalmazásokat), vagy említse meg kifejezetten az ügynök promptjában („Amikor a hívó az időjárásról kérdez, használja a `get_weather` eszközt.”). A 6 kB-nál nagyobb válaszok csonkolva jelennek meg az átirat előnézetében. Csak azokat a mezőket adja vissza, amelyekre az LLM-nek szüksége van — ne a teljes sort. Az eszközvégpontok alapértelmezett időtúllépése 10 másodperc. Ha hosszabb időre van szüksége, kezelje aszinkron módon: adjon vissza `{"status": "pending", "request_id": "..."}` választ, majd jelenítse meg az eredményt külön eszközhívással. Minden integrációs `PATCH` új verziót hoz létre. Vizsgálja meg a [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history) végpontot, hogy lássa, ki mit módosított. Ha elrontja egy eszköz sémáját, manuálisan visszaállíthatja úgy, hogy egy régebbi pillanatképet PATCH kéréssel visszaküld. --- ## Következő lépések CRUD, átvitel, verzióelőzmények. Teljes JSON-sémanyelvtan és az aláírt végpontokra vonatkozó szerződés. Alkalmazza a webhook-aláírási mintát az eszközvégpontokra. Vizsgálja meg egy eszközhívás teljes oda-vissza folyamatát.