--- title: "Funkcióeszközök" description: "Adjon AI-ügynökeinek olyan funkcióeszközöket, amelyek a beszélgetés közben külső API-kat hívnak meg — ügyféladatokat kérnek le, időpontokat foglalnak, rekordokat frissítenek — típusos paraméterekkel." --- A funkcióeszközök lehetővé teszik, hogy AI-ügynökei telefonhívások során külső API-kat hívjanak meg. Használja őket ügyféladatok lekérdezésére, elérhetőség ellenőrzésére, időpontfoglalásra vagy bármely, a háttérrendszere által támogatott művelet végrehajtására. ## Működése 1. Definiálja az eszközöket egy sémával (milyen argumentumokat fogad el az eszköz) 2. Adjon meg egy `endpoint` konfigurációt (ahová a ThunderPhone meghívja az API-ját) — vagy hagyja ki, hogy a szervezeti webhookon kapja meg az eszközhívásokat 3. Hívás közben az AI a beszélgetés alapján dönti el, mikor használjon eszközt 4. A ThunderPhone meghívja az endpointot az eszköz argumentumaival 5. Az API válasza visszakerül az AI-hoz a beszélgetés folytatásához | Képesség | Futtatási hely | Beállítás | | --- | --- | --- | | [Beépített eszközök](/hu/guides/built-in-tools) | ThunderPhone | Promptutasítások; egyes eszközökhöz ügynökbeállítás is szükséges | | [Alkalmazáskapcsolatok](/hu/guides/connect-apps) | ThunderPhone és a kapcsolódó szolgáltató | Csatlakoztassa a fiókot, és rendelje hozzá a jóváhagyott műveleteket | | [API-kapcsolatok](/hu/guides/api-connections) és funkcióeszközök | Az Ön HTTP API-ja | Definiálja az endpointot és a sémát, vagy fogadja a függvényhívásokat webhookon keresztül | | [MCP-szerverek](/hu/guides/mcp-servers) | Távoli MCP-szerver | Adja hozzá a szervert, fedezze fel az eszközeit, és rendelje hozzá az ügynökhöz | --- ## Eszközséma Minden eszköz ezt a struktúrát követi: ```json { "type": "function", "function": { "name": "search_appointments", "description": "Find available appointment slots for a given date", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "Date in YYYY-MM-DD format" }, "service": { "type": "string", "description": "Type of service (e.g., 'consultation', 'follow-up')" } }, "required": ["date"] } }, "endpoint": { "url": "https://api.example.com/appointments/search", "method": "POST", "headers": { "X-Api-Key": "your-api-key" } }, "timeout": 120 } ``` ### Eszközkonfiguráció | Mező | Típus | Kötelező | Leírás | |-------|------|----------|-------------| | `timeout` | number | Nem | Maximális végrehajtási idő másodpercben (alapértelmezett: `20`, maximum: `180`) | ### Függvénydefiníció | Mező | Típus | Kötelező | Leírás | |-------|------|----------|-------------| | `name` | string | Igen | Az eszköz egyedi azonosítója | | `description` | string | Igen | Elmagyarázza az AI-nak, mikor használja ezt az eszközt | | `parameters` | object | Igen | Az eszköz argumentumainak JSON-sémája | ### Endpointkonfiguráció | Mező | Típus | Kötelező | Leírás | |-------|------|----------|-------------| | `url` | string | Igen | Az Ön API-endpointjának URL-je | | `method` | string | Nem | HTTP-metódus (alapértelmezett: `POST`) | | `headers` | object | Nem | Egyéni fejlécek, amelyeket bele kell foglalni | Az `endpoint` konfiguráció **nem** kerül elküldésre az AI-modellnek — a ThunderPhone csak az eszközhívás végrehajtására használja. --- ## Két meghívási útvonal Az, hogy a szervere melyik kérést kapja, attól függ, hogy az eszköz rendelkezik-e `endpoint` értékkel: | | Eszköz `endpoint`-tal | Eszköz `endpoint` nélkül | |---|---|---| | A kérés célhelye | Közvetlenül az `endpoint.url` címre | Az Ön szervezetének [régi webhook URL-címe](/api-reference/organizations#legacy-single-url-webhook) | | Törzs | A kiválasztott kérésformátum (alapértelmezés szerint csak argumentumok) | `telephony.tool` / `web.tool` burkoló | | Fejlécek | Az Ön `endpoint.headers` fejlécei + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature-V2` + `X-ThunderPhone-Signature` | `Content-Type` + `X-ThunderPhone-Signature-V2` + `X-ThunderPhone-Signature` | | Aláírókulcs | A szervezet webhook titkos kulcsa | A szervezet webhook titkos kulcsa | Mindkét útvonal **blokkoló** — az AI a mondat közepén vár az eredményre. Az alapértelmezett időtúllépés **20 s**; állítsa be az eszköz legfelső szintű `timeout` értékét hosszabb, legfeljebb a platform **180 s** értékű maximumáig tartó végrehajtás engedélyezéséhez. Tartsa gyorsan a kezelőket. Vegyes használat is lehetséges: olyan hívásnál, amelynek szervezete rendelkezik webhook URL-lel, az `endpoint` értékkel rendelkező eszközök közvetlenül lesznek meghívva, a többi pedig a webhookra tér vissza. ## Közvetlen végpont-hívások Amikor az AI meghív egy `endpoint` paraméterrel rendelkező eszközt, a ThunderPhone kérést küld az Ön URL-címére: ### Kérésfejlécek ```http POST /appointments/search HTTP/1.1 Host: api.example.com Content-Type: application/json X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c... X-ThunderPhone-Signature: abc123... X-ThunderPhone-Call-ID: 987654321 X-Api-Key: your-api-key ``` Az `endpoint.headers` egyéni fejlécei mindig szó szerint szerepelnek, valamint ezek a ThunderPhone-névterű fejlécek: - `X-ThunderPhone-Signature-V2` — időbélyeggel ellátott HMAC-SHA256 a metóduson, útvonalon, lekérdezésen és törzsön, az Ön **szervezeti webhook-titkával** kulcsolva. Ellenőrizze ezt, és utasítsa el az 5 percnél régebbi kéréseket; lásd: [Webhook-aláírások ellenőrzése](/hu/guides/verify-webhook-signatures) - `X-ThunderPhone-Signature` — a pontos kérési törzsbájtok örökölt HMAC-SHA256-aláírása, ugyanazzal a kulccsal, amelyet a meglévő ellenőrzők számára továbbra is küldünk - `X-ThunderPhone-Call-ID` — Az aktuális hívásazonosító A `Content-Type: application/json` be van állítva, kivéve ha az `endpoint.headers` felülírja — az egyéni `Content-Type` elsőbbséget élvez. Az aláírás a szervezeti szintű webhooktitokkal van kulcsolva, amely a [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) végpontból származik. Ha szervezete még soha nem konfigurálta a régi webhookot, nincs titok, és az eszközhívások **csak** `X-ThunderPhone-Call-ID` fejlécet tartalmaznak — a hiányzó aláírás esetén hibával leálló kezelő elutasítaná őket. Konfigurálja a régi webhookot a titok lekéréséhez, vagy helyezze el saját megosztott titkát az `endpoint.headers` mezőben. ### Kérésformátum Minden API-kapcsolat rendelkezik `request_format` beállítással. Válassza a `vapi` vagy `retell` értéket, ha egy importált eszköznek továbbra is az adott platformhoz készült végpontot kell hívnia. Az új és meglévő kapcsolatok alapértelmezett értéke a `standard`. `POST` / `PUT` / `PATCH` esetén a ThunderPhone kanonikus formában szerializálja a kiválasztott burkot (rendezett kulcsok, tömör elválasztók). Mindkét aláírás pontosan ezeket a bájtokat fedi le. #### Standard A `standard` csak az eszköz argumentumait küldi el, burkoló nélkül. Ez az alapértelmezett beállítás, és bájtról bájtra megőrzi a ThunderPhone eredeti kérési törzsét: ```json {"date":"2025-01-02","service":"consultation"} ``` #### Vapi A `vapi` a Vapi által dokumentált formában küldi a Vapi [`tool-calls` szerverüzenetét](https://docs.vapi.ai/tools/custom-tools). A `call.id` a ThunderPhone hívásazonosítója. Az eszközhívás `id` értéke meghívásonként egyedi, és a végpont válaszának egyeztetésére használható. A hívás a `toolCallList` és a `toolWithToolCallList` mezőben is megjelenik, ahol a `function.arguments` JSON-objektum: ```json { "message": { "type": "tool-calls", "timestamp": 1725000000123, "call": { "id": "987654321" }, "toolCallList": [ { "id": "call_00112233445566778899aabbccddeeff", "type": "function", "function": { "name": "search_appointments", "arguments": { "date": "2025-01-02", "service": "consultation" } } } ], "toolWithToolCallList": [ { "type": "function", "function": { "name": "search_appointments" }, "toolCall": { "id": "call_00112233445566778899aabbccddeeff", "type": "function", "function": { "name": "search_appointments", "arguments": { "date": "2025-01-02", "service": "consultation" } } } } ] } } ``` A csak Vapihoz tartozó mezők, például az `assistant`, az `artifact` és a teljes `call` objektum nem kerülnek elküldésre. Adja vissza a Vapi válaszburkát az egyező eszközhívás-azonosítóval: ```json { "results": [ { "toolCallId": "call_00112233445566778899aabbccddeeff", "result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}" } ] } ``` A ThunderPhone a kibontott `result` karakterláncot adja át az AI-nak. Kompatibilitási okokból JSON-értéket is elfogad olyan végpontok esetén, amelyek már ilyet adnak vissza. A `result` helyén szereplő `error` eszközhibaként kerül vissza az AI-hoz. Ha a végpont hibás formátumú vagy nem egyező Vapi-burkot ad vissza, a ThunderPhone figyelmeztetést naplóz, és a hívás sikertelen befejezése helyett visszaáll a standard válaszfeldolgozásra. #### Retell A `retell` egy [Retell egyéni függvényhez](https://docs.retellai.com/build/single-multi-prompt/custom-function) dokumentált kérést küldi: ```json { "name": "search_appointments", "call": { "call_id": "987654321" }, "args": { "date": "2025-01-02", "service": "consultation" } } ``` A `call` objektum csak a `call_id` mezőt tartalmazza. A ThunderPhone nem tartalmaz olyan Retell-specifikus mezőket, amelyeket a küldéskor nem tud hitelesen megadni, például az `agent_id`, `transcript`, `transcript_object`, `metadata` vagy dinamikus változókat. A Retell bármilyen válasz törzsét elfogadja; a ThunderPhone a standard válaszkezeléssel változatlanul továbbítja azt. `GET` / `DELETE` esetén az argumentumok **lekérdezési paraméterekként** kerülnek elküldésre, és a törzs a `request_format` értékétől függetlenül üres. A V2-aláírás az elküldött lekérdezési karakterláncot fedi le; a régi aláírás az üres bájtkarakterlánc alapján készül. Lásd: [Webhook-aláírások ellenőrzése](/hu/guides/verify-webhook-signatures). ### Válasz Adjon vissza JSON-választ az eszköz eredményével: ```json { "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"], "timezone": "America/Los_Angeles" } ``` A válasz formázva kerül az AI-hoz, hogy folytathassa a beszélgetést. A nem JSON-válaszok `{"data": ""}` formában vannak burkolva; az időtúllépéseket és kapcsolódási hibákat az AI hibaként kapja meg, így az ügynök elnézést kérhet és továbbléphet ahelyett, hogy megakadna. ## Webhook módú továbbítás Az `endpoint` nélküli eszközök a szervezete régi webhook-URL-címére kerülnek továbbításra aláírt `telephony.tool` (telefonhívások) vagy `web.tool` (webes hívások) kérésként. Az [auditértesítésekkel](/hu/webhooks/events) ellentétben, amelyek végrehajtás után érkeznek a webhook-végpontokhoz, ez a kérés **maga** a végrehajtás — az Ön HTTP-válasza az eszköz eredménye. ```json { "type": "telephony.tool", "data": { "call_id": 987654321, "tool_name": "search_appointments", "arguments": { "date": "2026-04-21" }, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` A `web.tool` az `origin_domain` mezőt tartalmazza a `from_number` / `to_number` helyett. Válaszoljon a műveleti eszköz eredményével JSON-formátumban — ugyanazzal a válaszszerződéssel, mint a közvetlen végponthívások esetén. A kérést a szervezet webhooktitkával írják alá, mindkét aláírási fejléccel, akárcsak minden más webhookot. Az előfizetett [webhook-végpontok](/hu/webhooks/endpoints) emellett nem blokkoló `telephony.tool` / `web.tool` **értesítést kapnak minden eszköz végrehajtása után** (bármelyik útvonal futtatta azt), beleértve az eszköz válaszát is — hasznos auditnaplókhoz. Lásd az [eseménykatalógust](/hu/webhooks/events). --- ## Aláírás-ellenőrzés A közvetlen eszközhívások ugyanúgy vannak aláírva, mint a webhookok, az Ön szervezetének webhooktitkával: - Az `X-ThunderPhone-Signature-V2` az elküldött időbélyeget, metódust, útvonalat és lekérdezést, valamint a törzs pontos bájtjait írja alá. Utasítsa el azokat a kéréseket, amelyek időbélyege több mint 5 perccel eltér az Ön órájától. - Az `X-ThunderPhone-Signature` (örökölt) csak a törzs bájtjait írja alá, `GET` / `DELETE` esetén az üres bájtsorozatot. Továbbra is változatlanul küldjük. Az SDK-segédfüggvények ellenőrzik a V2-fejlécet, beleértve az 5 perces időablakot is: ```python Python import json from fastapi import FastAPI, HTTPException, Request from thunderphone import verify_signature app = FastAPI() @app.post("/appointments/search") async def search_appointments(request: Request): body = await request.body() query = request.scope.get("query_string", b"").decode("latin-1") path = request.url.path + (f"?{query}" if query else "") if not verify_signature( request.headers.get("X-ThunderPhone-Signature-V2"), secret=WEBHOOK_SECRET, method=request.method, path=path, body=body, ): raise HTTPException(status_code=401) data = json.loads(body) date = data["date"] # Look up availability slots = await get_available_slots(date) return {"available_slots": slots} ``` ```javascript Node.js import express from "express"; import { verifySignature } from "@thunderphone/sdk"; app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => { const ok = verifySignature({ header: req.header('X-ThunderPhone-Signature-V2'), secret: WEBHOOK_SECRET, method: req.method, path: req.originalUrl, body: req.body, }); if (!ok) return res.status(401).send('Invalid signature'); const { date, service } = JSON.parse(req.body); // Look up availability const slots = getAvailableSlots(date, service); res.json({ available_slots: slots }); }); ``` A teljes útmutatók — az aláírt karakterlánc, egy részletes példa, SDK nélküli kód, a `GET` / `DELETE` eset és a titok nélküli használatra vonatkozó figyelmeztetés — a [Webhook-aláírások ellenőrzése](/hu/guides/verify-webhook-signatures) oldalon találhatók. --- ## Példa: Teljes foglalási folyamat Íme egy teljes időpontfoglalási rendszer eszközkészlete: ```json { "tools": [ { "type": "function", "function": { "name": "search_appointments", "description": "Find available appointment slots", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD" }, "service": { "type": "string" } }, "required": ["date"] } }, "endpoint": { "url": "https://api.example.com/appointments/search", "method": "POST", "headers": { "X-Api-Key": "key" } } }, { "type": "function", "function": { "name": "book_appointment", "description": "Book an appointment at a specific time", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD" }, "time": { "type": "string", "description": "HH:MM format" }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" } }, "required": ["date", "time", "customer_name"] } }, "endpoint": { "url": "https://api.example.com/appointments/book", "method": "POST", "headers": { "X-Api-Key": "key" } } }, { "type": "function", "function": { "name": "cancel_appointment", "description": "Cancel an existing appointment", "parameters": { "type": "object", "properties": { "confirmation_number": { "type": "string" } }, "required": ["confirmation_number"] } }, "endpoint": { "url": "https://api.example.com/appointments/cancel", "method": "POST", "headers": { "X-Api-Key": "key" } } } ] } ``` --- ## Ajánlott eljárások A `description` mező segít az AI-nak megérteni, **mikor** használja az eszközt. Pontosan írja le, mit tesz, és mikor célszerű használni. Az AI által értelmezhető hibaüzeneteket adjon vissza: `{"error": "No slots available for that date"}` általános 500-as hibák helyett. Csak azt adja vissza, amire az AI-nak szüksége van a beszélgetés folytatásához. A nagy méretű hasznos adatok lassítják a válaszidőt. Csak akkor jelölje a mezőket `required` értékűnek, ha az valóban szükséges. Az AI az eszköz meghívása előtt elkéri a felhasználótól a kötelező adatokat. --- ## Kapcsolódó témák Platform által kezelt hívásműveletek indítása végpont meghatározása nélkül. Platform által kezelt eszközök a HubSpothoz, Salesforce-hoz, Slackhez, Google Calendarhoz, Google Sheetshöz és Cal.comhoz — nincs szükség végpontra. Csatlakoztasson egy MCP-szervert, és engedje, hogy az ügynök meghívja az eszközeit. Újrahasználható REST-integrációk, amelyeket ügynökökhöz csatolhat. Egyetlen ellenőrző segédeszköz webhookokhoz és eszközhívásokhoz.