Funkcióeszközök

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

Eszközséma#

Minden eszköz ezt a struktúrát követi:

{
  "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ó#

Függvénydefiníció#

Endpointkonfiguráció#

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:

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#

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
• 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.

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:

{"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. 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:

{
  "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:

{
  "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 dokumentált kérést küldi:

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

Válasz#

Adjon vissza JSON-választ az eszköz eredményével:

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

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

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:

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}

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 oldalon találhatók.

Példa: Teljes foglalási folyamat#

Íme egy teljes időpontfoglalási rendszer eszközkészlete:

{
  "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#

Kapcsolódó témák#