Funkčné nástroje

Poskytnite svojim AI agentom funkčné nástroje, ktoré počas konverzácie volajú externé API — načítajú údaje o zákazníkoch, rezervujú termíny, aktualizujú záznamy — s typovanými parametrami.

Funkčné nástroje umožňujú vašim AI agentom počas telefonických hovorov volať externé API. Použite ich na vyhľadávanie údajov o zákazníkoch, kontrolu dostupnosti, rezervovanie termínov alebo vykonanie ľubovoľnej akcie, ktorú váš backend podporuje.

Ako to funguje#

1. Definujete nástroje pomocou schémy (aké argumenty nástroj prijíma)
2. Poskytnete konfiguráciu endpoint (kam ThunderPhone volá vaše API) — alebo ju vynecháte, aby ste prijímali volania nástrojov na webhooku organizácie
3. Počas hovoru sa AI na základe konverzácie rozhodne, kedy použiť nástroj
4. ThunderPhone zavolá váš endpoint s argumentmi nástroja
5. Odpoveď vášho API sa odošle späť AI na pokračovanie v konverzácii

Schéma nástroja#

Každý nástroj má nasledujúcu štruktúru:

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

Konfigurácia nástroja#

Definícia funkcie#

Konfigurácia endpointu#

Dva spôsoby volania#

Požiadavka, ktorú váš server prijme, závisí od toho, či nástroj obsahuje endpoint:

Oba spôsoby sú blokujúce — AI uprostred vety čaká na výsledok. Predvolený časový limit je 20 s; nastavením timeout na najvyššej úrovni nástroja povolíte dlhšie vykonávanie, až do maxima platformy 180 s. Handlery udržiavajte rýchle. Kombinácia je možná: pri hovore, ktorého organizácia má URL webhooku, sa nástroje s endpoint volajú priamo a ostatné sa vrátia k webhooku.

Priame volania koncových bodov#

Keď AI vyvolá nástroj, ktorý má endpoint, ThunderPhone odošle požiadavku na vašu URL adresu:

Hlavičky požiadavky#

POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-Api-Key: your-api-key

Vlastné hlavičky z vášho endpoint.headers sú vždy zahrnuté doslovne spolu s dvoma hlavičkami v mennom priestore ThunderPhone:

• X-ThunderPhone-Signature — HMAC-SHA256 z presných bajtov tela požiadavky s kľúčom tajomstvo webhooku vašej organizácie
• X-ThunderPhone-Call-ID — ID aktuálneho hovoru

Content-Type: application/json sa nastaví, pokiaľ ho váš endpoint.headers neprepíše — vlastný Content-Type má prednosť.

Telo požiadavky#

Pre POST / PUT / PATCH telo obsahuje iba argumenty nástroja (bez obálky), kanonicky serializované (zoradené kľúče, kompaktné oddeľovače):

{"date":"2025-01-02","service":"consultation"}

Pre GET / DELETE sa argumenty odosielajú ako parametre dopytu a telo je prázdne — podpis sa potom vypočíta nad prázdnym reťazcom bajtov. Pozrite si Overenie podpisov webhookov.

Odpoveď#

Vráťte odpoveď JSON s výsledkom nástroja:

{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}

Odpoveď sa naformátuje a poskytne AI, aby mohla pokračovať v konverzácii. Odpovede iné než JSON sa zabalia ako {"data": "<text>"}; časové limity a zlyhania pripojenia sa AI nahlásia ako chyby, takže sa agent môže ospravedlniť a pokračovať namiesto zaseknutia.

Odosielanie v režime webhooku#

Nástroje bez endpoint sa odosielajú na staršiu webhookovú URL vašej organizácie ako podpísaná požiadavka telephony.tool (telefonické hovory) alebo web.tool (webové volania). Na rozdiel od notifikácií auditu, ktoré sa doručujú na koncové body webhookov po vykonaní, táto požiadavka je samotným vykonaním — vaša odpoveď HTTP je výsledkom nástroja.

{
  "type": "telephony.tool",
  "data": {
    "call_id": 987654321,
    "tool_name": "search_appointments",
    "arguments": { "date": "2026-04-21" },
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  }
}

web.tool obsahuje origin_domain namiesto from_number / to_number. Odpovedzte výsledkom nástroja vo formáte JSON — platí rovnaký kontrakt odpovede ako pri priamych volaniach koncových bodov. Požiadavka je podpísaná tajomstvom webhooku organizácie nad nespracovaným telom, rovnako ako každý iný webhook.

Overenie podpisu#

Priame volania nástrojov sú podpisované rovnako ako webhooky:

• HMAC-SHA256 nad presnými bajtmi tela požiadavky (kanonický JSON — zoradené kľúče, bez nadbytočných medzier)
• S použitím tajného kľúča webhooku vašej organizácie
• Nástroje GET / DELETE podpisujú prázdny bajtový reťazec

import hmac
import hashlib
 
def verify_tool_call(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
 
@app.post("/appointments/search")
async def search_appointments(request: Request):
    body = await request.body()
    signature = request.headers.get("X-ThunderPhone-Signature", "")
 
    if not verify_tool_call(body, signature, WEBHOOK_SECRET):
        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}

app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-thunderphone-signature'] || '';
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
 
  if (!signature ||
      signature.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    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 });
});

Úplné postupy — vrátane prípadu s prázdnym telom a upozornenia na chýbajúci tajný kľúč — nájdete v časti Overenie podpisov webhookov.

Príklad: Kompletný proces rezervácie#

Tu je súbor nástrojov pre kompletný systém rezervácie termínov:

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

Osvedčené postupy#

Súvisiace#