Funkcijų įrankiai

Suteikite savo DI agentams funkcijų įrankius, kurie pokalbio metu iškviečia išorines API, gauna klientų duomenis, rezervuoja susitikimus ir atnaujina įrašus naudodami tipizuotus parametrus.

Funkcijų įrankiai leidžia jūsų balso agentams skambučių metu iškviesti išorines API. Naudokite juos klientų duomenims rasti, prieinamumui patikrinti, susitikimams rezervuoti arba bet kuriam veiksmui, kurį palaiko jūsų vidinė sistema, atlikti.

Kaip tai veikia#

1. Apibrėžiate įrankius naudodami schemą (kokius argumentus priima įrankis)
2. Pateikiate endpoint konfigūraciją (kur ThunderPhone iškviečia jūsų API) arba jos nenurodote, kad įrankio iškvietimus gautumėte organizacijos žiniatinklio kablio adresu
3. Skambučio metu DI nusprendžia, kada naudoti įrankį, pagal pokalbį
4. ThunderPhone iškviečia jūsų galinį tašką su įrankio argumentais
5. Jūsų API atsakymas perduodamas atgal DI, kad pokalbis tęstųsi

Įrankio schema#

Kiekvienas įrankis turi tokią struktūrą:

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

Įrankio konfigūracija#

Funkcijos apibrėžimas#

Galinio taško konfigūracija#

Du iškvietimo keliai#

Kokią užklausą gauna jūsų serveris, priklauso nuo to, ar įrankis turi endpoint:

Abu keliai yra blokuojantys — DI sakinio viduryje laukia rezultato. Numatytasis laiko limitas yra 20 s; nustatykite įrankio aukščiausio lygio timeout, kad leistumėte ilgesnį vykdymą, iki platformos 180 s maksimumo. Užtikrinkite, kad tvarkytuvės veiktų greitai. Galima naudoti mišrų variantą: skambučio, kurio organizacija turi žiniatinklio kablio URL, metu įrankiai su endpoint yra iškviečiami tiesiogiai, o kiti grįžta prie žiniatinklio kablio.

Tiesioginiai galinio taško iškvietimai#

Kai AI iškviečia įrankį, turintį endpoint, ThunderPhone siunčia užklausą į jūsų URL:

Užklausos antraštės#

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

Pasirinktinės antraštės iš jūsų endpoint.headers visada įtraukiamos nepakeistos, kartu su dviem ThunderPhone vardų srities antraštėmis:

• X-ThunderPhone-Signature — tikslių užklausos turinio baitų HMAC-SHA256, kuriam naudojama jūsų organizacijos webhook paslaptis
• X-ThunderPhone-Call-ID — dabartinio skambučio ID

Content-Type: application/json nustatoma, nebent jūsų endpoint.headers ją pakeičia — pasirinktinė Content-Type turi pirmenybę.

Užklausos turinys#

Naudojant POST / PUT / PATCH, turinyje pateikiami tik įrankio argumentai (be apvalkalo), kanoniškai serializuoti (surikiuoti raktai, glausti skirtukai):

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

Naudojant GET / DELETE, argumentai siunčiami kaip užklausos parametrai, o turinys yra tuščias — tuomet parašas apskaičiuojamas pagal tuščią baitų eilutę. Žr. Webhook parašų tikrinimas.

Atsakymas#

Grąžinkite JSON atsakymą su įrankio rezultatu:

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

Atsakymas suformatuojamas ir pateikiamas AI, kad šis galėtų tęsti pokalbį. Ne JSON atsakymai apgaubiami kaip {"data": "<text>"}; laiko limitų viršijimai ir ryšio klaidos AI pateikiamos kaip klaidos, todėl agentas gali atsiprašyti ir tęsti, užuot užstrigęs.

Išsiuntimas webhook režimu#

Įrankiai be endpoint siunčiami į jūsų organizacijos senojo webhook URL kaip pasirašyta telephony.tool (telefono skambučiai) arba web.tool (žiniatinklio iškvietimai) užklausa. Kitaip nei audito pranešimai, kurie pateikiami webhook galiniams taškams po vykdymo, ši užklausa yra vykdymas — jūsų HTTP atsakymas yra įrankio rezultatas.

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

web.tool vietoj from_number / to_number pateikia origin_domain. Atsakykite įrankio rezultatu JSON formatu — taikoma ta pati atsakymo sutartis kaip ir tiesioginiams galinio taško iškvietimams. Užklausa pasirašoma organizacijos webhook paslaptimi pagal neapdorotą turinį, kaip ir kiekvienas kitas webhook.

Parašo patvirtinimas#

Tiesioginiai įrankių iškvietimai pasirašomi taip pat kaip ir žiniatinklio kabliukai:

• HMAC-SHA256 pagal tikslius užklausos teksto baitus (kanoninis JSON — surikiuoti raktai, be papildomų tarpų)
• Naudojant jūsų organizacijos žiniatinklio kabliuko slaptąjį raktą
• GET / DELETE įrankiai pasirašo tuščią baitų eilutę

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

Visi pavyzdžiai, įskaitant tuščio teksto atvejį ir pastabą dėl slaptojo rakto nebuvimo, pateikti skyriuje Žiniatinklio kabliukų parašų tikrinimas.

Pavyzdys: visas rezervavimo procesas#

Štai įrankių rinkinys visai vizitų rezervavimo sistemai:

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

Geriausios praktikos#

Susiję#