> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Eszközintegráció (API) létrehozása > Engedje, hogy ügynöke a beszélgetés közben meghívja API-jait — adatbázisban keressen, hibajegyet hozzon létre vagy rendelést keressen meg. Az **eszközintegráció** egy újrahasználható HTTP-végpont, amelyet egy ügynök hívás közben meghívhat. Ön egy JSON-séma szerinti leírást ad a ThunderPhone-nak az eszközről, valamint egy végponti URL-t; az ügynök a beszélgetés alapján dönti el, 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 összeköti 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 tervezeté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 nyers API-t ismerteti. Ez az útmutató végigvezeti Önt egy időjárás-lekérdező eszköz teljes körű létrehozásán. ## Egy eszköz felépítése Két részből áll: 1. **A séma** — OpenAI-stílusú függvénydefiníció (`{type: "function", function: {name, description, parameters}}`), amely megmondja az LLM-nek, mit csinál az eszköz, és milyen argumentumokat fogad. 2. **A végpont** — az az URL, amelyet a ThunderPhone szerverei hívnak, amikor az LLM az eszköz használata mellett dönt. A kérés JSON POST, amelynek törzse az LLM által kiválasztott argumentumokat tartalmazza. ## 1. Válasszon tárolási stratégiát Csatoljon egy egyszeri eszközt az ügynök `tools` tömbjéhez. Egyszerű, de nem újrahasználható. Tárolja az eszközt újrahasználható [integrációként](/api-reference/integrations), és kapcsolja össze több ügynökkel. Minden egynél többször használt eszközhöz ezt javasoljuk. Ez az útmutató a mentett integrációs megközelítést használja. ## 2. Hozza létre az integrációt ```bash theme={null} 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 (egy UUID-t). Fordítson kellő figyelmet az eszköz és minden paraméter `description` mezőjére. Az LLM ezeket a karakterláncokat használja futásidőben 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. ## 3. Tesztelje a végpontot sandboxban Mielőtt összekapcsolja az integrációt egy ügynökkel, küldjön egy aláírt kérést a ThunderPhone szervereiről a kapcsolat ellenőrzéséhez: ```bash theme={null} 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 theme={null} { "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 Csatolja az `integration_ids` használatával, amikor ügynököt hoz létre vagy frissít: ```bash theme={null} 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-..."] }' ``` Több integrációt is kapcsolhat egy ügynökhöz. 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. Implementálja 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: 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 theme={null} {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` Az LLM feldolgozza ezt a választ, és emberi összefoglalót mond a hívónak. Az aláírás a nyers kéréstörzs alapján készül, ugyanazzal a `secret` értékkel, mint a webhook-végpontjánál. **Ellenőrizze** — az eszközvégpontok internet felől elérhetők, és 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 az eszköze által kezelt kérdést („Milyen idő van 94110-ben?”). A hívás átirata a teljes oda-vissza folyamatot mutatja: ```json theme={null} { "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) végponton; a nyers eseményfolyam (bejegyzésenkénti időzítéssel és hangeltolásokkal) itt érhető el: [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Gyakori buktatók Az LLM az eszköz leírása alapján dönt. Ha a hívó kérdése nem egyezik a leírással, 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 rekordot. 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: adja vissza a `{"status": "pending", "request_id": "..."}` választ, és jelenítse meg az eredményt külön eszközhíváson keresztül. Minden integrációs `PATCH` új revízió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 hibásan módosítja egy eszköz sémáját, manuálisan visszaállíthatja egy régebbi pillanatkép PATCH-csel történő visszaírásával. *** ## Következő lépések CRUD, átvitel, verzióelőzmények. Teljes JSON-sémanyelvtan és az aláírt végpont szerződése. 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.