Funktsioonitööriistad

Funktsioonitööriistad võimaldavad sinu tehisintellekti häälagentidel telefonikõnede ajal väliseid API-sid kutsuda. Kasuta neid kliendiandmete otsimiseks, saadavuse kontrollimiseks, kohtumiste broneerimiseks või mis tahes toimingu tegemiseks, mida sinu taustsüsteem toetab.

Kuidas see toimib

1. Määratled tööriistad skeemiga (milliseid argumente tööriist aktsepteerib)
2. Lisad endpoint-i konfiguratsiooni (kuhu ThunderPhone sinu API-d kutsub) või jätad selle ära, et võtta tööriistakutsed vastu oma organisatsiooni veebikonksu kaudu
3. Kõne ajal otsustab tehisintellekt vestluse põhjal, millal tööriista kasutada
4. ThunderPhone kutsub sinu lõpp-punkti tööriista argumentidega
5. Sinu API vastus saadetakse tehisintellektile tagasi, et vestlust jätkata

Tööriista skeem

Iga tööriist järgib seda struktuuri:

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

Funktsiooni määratlus

Lõpp-punkti konfiguratsioon

Kaks kutsumisteed

See, millise päringu sinu server vastu võtab, sõltub sellest, kas tööriistal on endpoint:

Mõlemad teed on blokeerivad — tehisintellekt ootab tulemuse järel keset lauset — ning ajalõpp on 20 s. Hoia töötlejad kiired. Kombineerimine on lubatud: kõnes, mille organisatsioonil on veebikonksu URL, kutsutakse endpoint-iga tööriistu otse ja ülejäänud kasutavad veebikonksu.

Otsesed lõpp-punkti kutsed

Kui tehisintellekt kutsub tööriista, millel on endpoint, saadab ThunderPhone sinu URL-ile päringu:

Päringu päised

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

Sinu endpoint.headers kohandatud päised lisatakse alati muutmata kujul ning lisaks kaks ThunderPhone'i nimeruumiga päist:

• X-ThunderPhone-Signature — täpse päringusisu baitide HMAC-SHA256, mille võtmeks on sinu organisatsiooni veebikonksu saladus
• X-ThunderPhone-Call-ID — praeguse kõne ID

Content-Type: application/json määratakse, välja arvatud juhul, kui sinu endpoint.headers selle alistavad — kohandatud Content-Type on ülimuslik.

Päringu sisu

POST / PUT / PATCH korral sisaldab sisu ainult tööriista argumente (ilma ümbriseta), kanoniliselt serialiseerituna (sorditud võtmed, kompaktsed eraldajad):

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

GET / DELETE korral saadetakse argumendid päringuparameetritena ja sisu on tühi — allkiri arvutatakse siis tühja baidistringi põhjal. Vaata Veebikonksu allkirjade kontrollimine.

Vastus

Tagasta tööriista tulemusega JSON-vastus:

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

Vastus vormindatakse ja edastatakse tehisintellektile vestluse jätkamiseks. Mitte-JSON-vastused mähitakse kujule {"data": "<text>"}; ajalõppudest ja ühenduse tõrgetest teatatakse tehisintellektile vigadena, et häälagent saaks vabandada ja jätkata, mitte hanguda.

Veebikonksurežiimi väljastus

Tööriistad, millel puudub endpoint, saadetakse sinu organisatsiooni pärand- veebikonksu URL-ile allkirjastatud telephony.tool (telefonikõned) või web.tool (veebikõned) päringuna. Erinevalt auditeerimisteavitustest, mis edastatakse veebikonksu lõpp-punktidele pärast täitmist, on see päring täitmine — sinu HTTP-vastus on tööriista tulemus.

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

web.tool sisaldab from_number / to_number asemel origin_domain. Vasta tööriista tulemusega JSON-vormingus — sama vastuseleping nagu otseste lõpp-punkti kutsete puhul. Päring allkirjastatakse organisatsiooni veebikonksu saladusega töötlemata sisu põhjal nagu kõik teised veebikonksud.

Allkirja kontrollimine

Otsesed tööriistakutsed allkirjastatakse samamoodi nagu veebikonksud:

• HMAC-SHA256 täpsete päringu keha baitide üle (kanooniline JSON — sorditud võtmed, ilma lisatühikuteta)
• Võtmeks on sinu organisatsiooni veebikonksu saladus
• GET- ja DELETE-tööriistad allkirjastavad tühja baidistringi

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

Täielikud juhised — sealhulgas tühja keha juhtum ja saladuse puudumise hoiatus — leiad jaotisest Veebikonksu allkirjade kontrollimine.

Näide: täielik broneerimisvoog

Siin on tööriistade komplekt täieliku aja broneerimise süsteemi jaoks:

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

Parimad tavad

Seotud