ఫంక్షన్ టూల్స్

మీ AI ఏజెంట్‌లకు సంభాషణ మధ్యలో బాహ్య APIలను కాల్ చేసే ఫంక్షన్ టూల్స్‌ను ఇవ్వండి — కస్టమర్ డేటాను పొందండి, అపాయింట్‌మెంట్‌లను బుక్ చేయండి, రికార్డులను అప్‌డేట్ చేయండి — టైప్ చేయబడిన పారామీటర్‌లతో.

ఫంక్షన్ టూల్స్ మీ AI ఏజెంట్లు ఫోన్ కాల్‌ల సమయంలో బాహ్య APIలను పిలవడానికి అనుమతిస్తాయి. కస్టమర్ డేటాను వెతకడానికి, అందుబాటును తనిఖీ చేయడానికి, అపాయింట్‌మెంట్‌లను బుక్ చేయడానికి లేదా మీ బ్యాకెండ్ మద్దతిచ్చే ఏదైనా చర్యను నిర్వహించడానికి వాటిని ఉపయోగించండి.

ఇది ఎలా పనిచేస్తుంది#

1. మీరు ఒక స్కీమాతో టూల్స్‌ను నిర్వచిస్తారు (టూల్ అంగీకరించే ఆర్గ్యుమెంట్‌లు)
2. మీరు ఒక endpoint కాన్ఫిగరేషన్‌ను అందిస్తారు (ThunderPhone మీ APIని ఎక్కడ పిలుస్తుంది) — లేదా మీ సంస్థ వెబ్‌హుక్‌లో టూల్ కాల్‌లను స్వీకరించడానికి దానిని వదిలివేయండి
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 సెకన్లు; దీర్ఘ అమలును అనుమతించడానికి టూల్ యొక్క టాప్-లెవల్ timeoutను సెట్ చేయండి, గరిష్టంగా ప్లాట్‌ఫారమ్ పరిమితి అయిన 180 సెకన్లు వరకు. హ్యాండ్లర్‌లను వేగంగా ఉంచండి. మిశ్రమం కూడా సరే: వెబ్‌హుక్ URL ఉన్న సంస్థకు చెందిన కాల్‌లో, endpoint ఉన్న టూల్స్‌ను నేరుగా పిలుస్తారు మరియు మిగతావి వెబ్‌హుక్‌కు తిరిగి మారతాయి.

ప్రత్యక్ష ఎండ్‌పాయింట్ కాల్‌లు#

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

మీ endpoint.headers దానిని ఓవర్‌రైడ్ చేయనంత వరకు Content-Type: application/json సెట్ చేయబడుతుంది — కస్టమ్ 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లో from_number / to_numberకు బదులుగా origin_domain ఉంటుంది. టూల్ ఫలితాన్ని JSONగా రెస్పాండ్ చేయండి — ప్రత్యక్ష ఎండ్‌పాయింట్ కాల్‌లకు ఉన్నదే రెస్పాన్స్ కాంట్రాక్ట్. ప్రతి ఇతర వెబ్‌హుక్‌లాగే, రిక్వెస్ట్‌కు రా బాడీపై సంస్థ వెబ్‌హుక్ సీక్రెట్‌తో సంతకం చేయబడుతుంది.

సంతకం ధృవీకరణ#

డైరెక్ట్ టూల్ కాల్‌లు వెబ్‌హుక్‌ల మాదిరిగానే సంతకం చేయబడతాయి:

• ఖచ్చితమైన రిక్వెస్ట్-బాడీ బైట్‌లపై HMAC-SHA256 (కానానికల్ JSON — క్రమబద్ధీకరించిన కీలు, అదనపు వైట్‌స్పేస్ లేదు)
• మీ సంస్థ వెబ్‌హుక్ సీక్రెట్‌తో కీ చేయబడుతుంది
• 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 });
});

ఖాళీ-బాడీ సందర్భం మరియు సీక్రెట్ లేనప్పుడు వర్తించే జాగ్రత్తతో సహా పూర్తి విధానాలు వెబ్‌హుక్ సంతకాలను ధృవీకరించండిలో ఉన్నాయి.

ఉదాహరణ: పూర్తి బుకింగ్ ఫ్లో#

పూర్తి అపాయింట్‌మెంట్ బుకింగ్ సిస్టమ్ కోసం టూల్‌ల సమితి ఇది:

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

ఉత్తమ పద్ధతులు#

సంబంధితవి#