Алатке функција

Омогућите својим AI агентима алатке функција које позивају спољне API-је усред разговора — преузимају податке о клијентима, заказују термине, ажурирају евиденцију — са типизираним параметрима.

Алатке функција омогућавају Вашим AI агентима да позивају спољне API-је током телефонских позива. Користите их за проналажење података о клијентима, проверу доступности, заказивање термина или извршавање било које радње коју подржава Ваш позадински систем.

Како функционише#

1. Дефинишете алатке помоћу шеме (које аргументе алатка прихвата)
2. Наводите конфигурацију endpoint (где ThunderPhone позива Ваш API) — или је изостављате да бисте примали позиве алатки на webhook-у Ваше организације
3. Током позива, AI одлучује када да користи алатку на основу разговора
4. ThunderPhone позива Ваш endpoint са аргументима алатке
5. Одговор Вашег API-ја се враћа AI-ју ради наставка разговора

Шема алатке#

Свака алатка прати ову структуру:

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

Конфигурација алатке#

Дефиниција функције#

Конфигурација endpoint-а#

Два пута позивања#

Који захтев ће Ваш сервер примити зависи од тога да ли алатка има endpoint:

Оба пута су блокирајућа — AI усред реченице чека резултат. Подразумевано временско ограничење је 20 s; подесите timeout на највишем нивоу алатке да бисте омогућили дуже извршавање, до максималних 180 s које платформа дозвољава. Нека обрађивачи буду брзи. Можете користити комбинацију: у позиву чија организација има URL webhook-а, алатке са endpoint-ом се позивају директно, а остале се враћају на webhook.

Директни позиви крајњих тачака#

Када AI позове алат који има endpoint, ThunderPhone шаље захтев на Ваш URL:

Заглавља захтева#

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

Прилагођена заглавља из Вашег endpoint.headers увек су укључена дословно, уз два заглавља у ThunderPhone простору имена:

• X-ThunderPhone-Signature — HMAC-SHA256 тачних бајтова тела захтева, потписан тајном вебхук тајном организације
• X-ThunderPhone-Call-ID — ID тренутног позива

Content-Type: application/json је постављен осим ако га Ваш endpoint.headers не замени — прилагођени Content-Type има предност.

Тело захтева#

За POST / PUT / PATCH, тело садржи само аргументе алата (без омотача), серијализоване канонски (сортирани кључеви, сажети раздвајачи):

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

За GET / DELETE, аргументи се шаљу као параметри упита а тело је празно — потпис се тада израчунава над празним низом бајтова. Погледајте Верификација потписа вебхука.

Одговор#

Вратите JSON одговор са резултатом алата:

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

Одговор се форматира и доставља AI-ју да настави разговор. Одговори који нису JSON умотавају се као {"data": "<text>"}; истеци времена и грешке везе пријављују се AI-ју као грешке, тако да агент може да се извини и настави уместо да застане.

Отпремање у режиму вебхука#

Алати без endpoint шаљу се на застарели URL вебхука Ваше организације као потписани захтев telephony.tool (телефонски позиви) или web.tool (веб позиви). За разлику од обавештења за ревизију која се испоручују вебхук крајњим тачкама након извршавања, овај захтев јесте извршавање — Ваш HTTP одговор је резултат алата.

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

web.tool садржи origin_domain уместо from_number / to_number. Одговорите резултатом алата као JSON — исти уговор о одговору као за директне позиве крајњих тачака. Захтев је потписан вебхук тајном организације над необрађеним телом, као и сваки други вебхук.

Верификација потписа#

Директни позиви алата потписују се на исти начин као webhook-ови:

• HMAC-SHA256 преко тачних бајтова тела захтева (канонски JSON — сортирани кључеви, без додатног размака)
• Са тајним webhook кључем Ваше организације
• Алати GET / DELETE потписују празан низ бајтова

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 });
});

Потпуна упутства — укључујући случај празног тела и напомену када тајни кључ није подешен — налазе се у одељку Верификација webhook потписа.

Пример: Комплетан ток заказивања#

Ево скупа алата за комплетан систем заказивања термина:

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

Најбоље праксе#

Повезано#