--- title: "ఫంక్షన్ టూల్స్" description: "మీ AI ఏజెంట్‌లకు సంభాషణ మధ్యలో బాహ్య APIలను కాల్ చేసే ఫంక్షన్ టూల్స్‌ను ఇవ్వండి — కస్టమర్ డేటాను పొందండి, అపాయింట్‌మెంట్‌లను బుక్ చేయండి, రికార్డులను అప్‌డేట్ చేయండి — టైప్ చేయబడిన పారామీటర్‌లతో." --- ఫంక్షన్ టూల్స్ మీ AI ఏజెంట్లు ఫోన్ కాల్‌ల సమయంలో బాహ్య APIలను పిలవడానికి అనుమతిస్తాయి. కస్టమర్ డేటాను వెతకడానికి, అందుబాటును తనిఖీ చేయడానికి, అపాయింట్‌మెంట్‌లను బుక్ చేయడానికి లేదా మీ బ్యాకెండ్ మద్దతిచ్చే ఏదైనా చర్యను నిర్వహించడానికి వాటిని ఉపయోగించండి. ## ఇది ఎలా పనిచేస్తుంది 1. మీరు ఒక స్కీమాతో టూల్స్‌ను నిర్వచిస్తారు (టూల్ అంగీకరించే ఆర్గ్యుమెంట్‌లు) 2. మీరు ఒక `endpoint` కాన్ఫిగరేషన్‌ను అందిస్తారు (ThunderPhone మీ APIని ఎక్కడ పిలుస్తుంది) — లేదా మీ సంస్థ వెబ్‌హుక్‌లో టూల్ కాల్‌లను స్వీకరించడానికి దానిని వదిలివేయండి 3. కాల్ సమయంలో, సంభాషణ ఆధారంగా టూల్‌ను ఎప్పుడు ఉపయోగించాలో AI నిర్ణయిస్తుంది 4. ThunderPhone టూల్ ఆర్గ్యుమెంట్‌లతో మీ endpointను పిలుస్తుంది 5. సంభాషణను కొనసాగించడానికి మీ API ప్రతిస్పందన AIకి తిరిగి పంపబడుతుంది | సామర్థ్యం | ఇది ఎక్కడ నడుస్తుంది | సెటప్ | | --- | --- | --- | | [అంతర్నిర్మిత టూల్స్](/te/guides/built-in-tools) | ThunderPhone | Prompt సూచనలు; కొన్ని టూల్స్‌కు ఏజెంట్ సెట్టింగ్ కూడా అవసరం | | [యాప్ కనెక్షన్‌లు](/te/guides/connect-apps) | ThunderPhone మరియు కనెక్ట్ చేసిన ప్రొవైడర్ | ఖాతాను కనెక్ట్ చేసి, ఆమోదించబడిన చర్యలను జత చేయండి | | [API కనెక్షన్‌లు](/te/guides/api-connections) మరియు ఫంక్షన్ టూల్స్ | మీ HTTP API | endpoint మరియు స్కీమాను నిర్వచించండి లేదా వెబ్‌హుక్ ద్వారా ఫంక్షన్ కాల్‌లను స్వీకరించండి | | [MCP సర్వర్‌లు](/te/guides/mcp-servers) | రిమోట్ MCP సర్వర్ | సర్వర్‌ను జోడించి, దాని టూల్స్‌ను కనుగొని, దానిని ఏజెంట్‌కు జత చేయండి | --- ## టూల్ స్కీమా ప్రతి టూల్ ఈ నిర్మాణాన్ని అనుసరిస్తుంది: ```json { "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 } ``` ### టూల్ కాన్ఫిగరేషన్ | ఫీల్డ్ | రకం | అవసరం | వివరణ | |-------|------|----------|-------------| | `timeout` | సంఖ్య | లేదు | సెకన్లలో గరిష్ట అమలు సమయం (డిఫాల్ట్: `20`, గరిష్టం: `180`) | ### ఫంక్షన్ నిర్వచనం | ఫీల్డ్ | రకం | అవసరం | వివరణ | |-------|------|----------|-------------| | `name` | స్ట్రింగ్ | అవును | టూల్‌కు ప్రత్యేక గుర్తింపుదారు | | `description` | స్ట్రింగ్ | అవును | ఈ టూల్‌ను ఎప్పుడు ఉపయోగించాలో AIకి వివరిస్తుంది | | `parameters` | ఆబ్జెక్ట్ | అవును | టూల్ ఆర్గ్యుమెంట్‌ల కోసం JSON Schema | ### Endpoint కాన్ఫిగరేషన్ | ఫీల్డ్ | రకం | అవసరం | వివరణ | |-------|------|----------|-------------| | `url` | స్ట్రింగ్ | అవును | మీ API endpoint URL | | `method` | స్ట్రింగ్ | లేదు | HTTP పద్ధతి (డిఫాల్ట్: `POST`) | | `headers` | ఆబ్జెక్ట్ | లేదు | చేర్చాల్సిన అనుకూల హెడర్‌లు | `endpoint` కాన్ఫిగరేషన్ AI మోడల్‌కు పంపబడదు—టూల్ కాల్‌ను అమలు చేయడానికి అది ThunderPhone మాత్రమే ఉపయోగిస్తుంది. --- ## రెండు ఇన్వొకేషన్ మార్గాలు మీ సర్వర్ స్వీకరించే అభ్యర్థన టూల్‌కు `endpoint` ఉందా అనే దానిపై ఆధారపడి ఉంటుంది: | | `endpoint` **ఉన్న** టూల్ | `endpoint` **లేని** టూల్ | |---|---|---| | అభ్యర్థన వెళ్లే స్థలం | నేరుగా `endpoint.url`కు | మీ సంస్థ యొక్క [లెగసీ వెబ్‌హుక్ URL](/api-reference/organizations#legacy-single-url-webhook) | | బాడీ | **కేవలం టూల్ ఆర్గ్యుమెంట్‌లు** | `telephony.tool` / `web.tool` ఎన్వలప్ | | హెడర్‌లు | మీ `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature` | `Content-Type` + `X-ThunderPhone-Signature` | | సైనింగ్ కీ | సంస్థ వెబ్‌హుక్ సీక్రెట్ | సంస్థ వెబ్‌హుక్ సీక్రెట్ | రెండు మార్గాలు **నిరోధకమైనవి** — ఫలితం కోసం AI వాక్యం మధ్యలో వేచి ఉంటుంది. డిఫాల్ట్ టైమ్‌అవుట్ **20 సెకన్లు**; దీర్ఘ అమలును అనుమతించడానికి టూల్ యొక్క టాప్-లెవల్ `timeout`ను సెట్ చేయండి, గరిష్టంగా ప్లాట్‌ఫారమ్ పరిమితి అయిన **180 సెకన్లు** వరకు. హ్యాండ్లర్‌లను వేగంగా ఉంచండి. మిశ్రమం కూడా సరే: వెబ్‌హుక్ URL ఉన్న సంస్థకు చెందిన కాల్‌లో, `endpoint` ఉన్న టూల్స్‌ను నేరుగా పిలుస్తారు మరియు మిగతావి వెబ్‌హుక్‌కు తిరిగి మారతాయి. ## ప్రత్యక్ష ఎండ్‌పాయింట్ కాల్‌లు AI ఒక `endpoint` ఉన్న టూల్‌ను అమలు చేసినప్పుడు, ThunderPhone మీ URLకు రిక్వెస్ట్‌ను పంపుతుంది: ### రిక్వెస్ట్ హెడర్‌లు ```http 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`కే ప్రాధాన్యం ఉంటుంది. సిగ్నేచర్‌కు సంస్థ-స్థాయి వెబ్‌హుక్ సీక్రెట్‌ను కీగా ఉపయోగిస్తారు, ఇది [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) నుండి లభిస్తుంది. మీ సంస్థ లెగసీ వెబ్‌హుక్‌ను ఎప్పుడూ కాన్ఫిగర్ చేయకపోతే, సీక్రెట్ ఉండదు మరియు టూల్ కాల్‌లు **కేవలం** `X-ThunderPhone-Call-ID`ను మాత్రమే కలిగి ఉంటాయి — సిగ్నేచర్ లేకపోవడాన్ని వెంటనే విఫలమయ్యేలా చేసే హ్యాండ్లర్ వాటిని తిరస్కరిస్తుంది. సీక్రెట్ పొందడానికి లెగసీ వెబ్‌హుక్‌ను కాన్ఫిగర్ చేయండి లేదా మీ స్వంత షేర్డ్ సీక్రెట్‌ను `endpoint.headers`లో ఉంచండి. ### రిక్వెస్ట్ బాడీ `POST` / `PUT` / `PATCH` కోసం, బాడీలో ర్యాపర్ లేకుండా టూల్ ఆర్గ్యుమెంట్‌లు **మాత్రమే** ఉంటాయి మరియు అవి కానానికల్‌గా సీరియలైజ్ చేయబడతాయి (క్రమబద్ధీకరించిన కీలు, కాంపాక్ట్ సెపరేటర్‌లు): ```json {"date":"2025-01-02","service":"consultation"} ``` `GET` / `DELETE` కోసం, ఆర్గ్యుమెంట్‌లు **క్వెరీ పారామీటర్‌లు**గా పంపబడతాయి మరియు బాడీ ఖాళీగా ఉంటుంది — అప్పుడు సిగ్నేచర్ ఖాళీ బైట్ స్ట్రింగ్‌పై లెక్కించబడుతుంది. [వెబ్‌హుక్ సిగ్నేచర్‌లను ధృవీకరించండి](/te/guides/verify-webhook-signatures) చూడండి. ### రెస్పాన్స్ టూల్ ఫలితంతో JSON రెస్పాన్స్‌ను తిరిగి ఇవ్వండి: ```json { "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"], "timezone": "America/Los_Angeles" } ``` రెస్పాన్స్‌ను ఫార్మాట్ చేసి, సంభాషణను కొనసాగించడానికి AIకి అందిస్తారు. JSON కాని రెస్పాన్స్‌లు `{"data": ""}`గా ర్యాప్ చేయబడతాయి; టైమ్‌అవుట్‌లు మరియు కనెక్షన్ వైఫల్యాలు AIకి ఎర్రర్‌లుగా నివేదించబడతాయి, కాబట్టి ఏజెంట్ ఆలస్యం కాకుండా క్షమాపణ చెప్పి ముందుకు సాగగలదు. ## వెబ్‌హుక్-మోడ్ డిస్పాచ్ `endpoint` **లేని** టూల్‌లు మీ సంస్థ లెగసీ వెబ్‌హుక్ URLకు సంతకం చేయబడిన `telephony.tool` (ఫోన్ కాల్‌లు) లేదా `web.tool` (వెబ్ కాల్‌లు) రిక్వెస్ట్‌గా డిస్పాచ్ చేయబడతాయి. అమలు తర్వాత వెబ్‌హుక్ ఎండ్‌పాయింట్‌లకు పంపబడే [ఆడిట్ నోటిఫికేషన్‌లు](/te/webhooks/events)కు భిన్నంగా, ఈ రిక్వెస్ట్‌యే **అమలు** — మీ HTTP రెస్పాన్స్ టూల్ ఫలితం. ```json { "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గా రెస్పాండ్ చేయండి — ప్రత్యక్ష ఎండ్‌పాయింట్ కాల్‌లకు ఉన్నదే రెస్పాన్స్ కాంట్రాక్ట్. ప్రతి ఇతర వెబ్‌హుక్‌లాగే, రిక్వెస్ట్‌కు రా బాడీపై సంస్థ వెబ్‌హుక్ సీక్రెట్‌తో సంతకం చేయబడుతుంది. సబ్‌స్క్రైబ్ చేసిన [వెబ్‌హుక్ ఎండ్‌పాయింట్‌లు](/te/webhooks/endpoints) అదనంగా, ప్రతి టూల్ అమలైన **తర్వాత** (దానిని ఏ మార్గం అమలు చేసినా) టూల్ రెస్పాన్స్‌తో సహా బ్లాకింగ్ కాని `telephony.tool` / `web.tool` **నోటిఫికేషన్‌ను** అందుకుంటాయి — ఆడిట్ ట్రెయిల్‌లకు ఉపయోగకరం. [ఈవెంట్‌ల కేటలాగ్](/te/webhooks/events) చూడండి. --- ## సంతకం ధృవీకరణ డైరెక్ట్ టూల్ కాల్‌లు వెబ్‌హుక్‌ల మాదిరిగానే సంతకం చేయబడతాయి: - ఖచ్చితమైన రిక్వెస్ట్-బాడీ బైట్‌లపై HMAC-SHA256 (కానానికల్ JSON — క్రమబద్ధీకరించిన కీలు, అదనపు వైట్‌స్పేస్ లేదు) - మీ సంస్థ వెబ్‌హుక్ సీక్రెట్‌తో కీ చేయబడుతుంది - `GET` / `DELETE` టూల్‌లు ఖాళీ బైట్ స్ట్రింగ్‌పై సంతకం చేస్తాయి ```python Python 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} ``` ```javascript Node.js 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 }); }); ``` ఖాళీ-బాడీ సందర్భం మరియు సీక్రెట్ లేనప్పుడు వర్తించే జాగ్రత్తతో సహా పూర్తి విధానాలు [వెబ్‌హుక్ సంతకాలను ధృవీకరించండి](/te/guides/verify-webhook-signatures)లో ఉన్నాయి. --- ## ఉదాహరణ: పూర్తి బుకింగ్ ఫ్లో పూర్తి అపాయింట్‌మెంట్ బుకింగ్ సిస్టమ్ కోసం టూల్‌ల సమితి ఇది: ```json { "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" } } } ] } ``` --- ## ఉత్తమ పద్ధతులు `description` ఫీల్డ్ టూల్‌ను **ఎప్పుడు** ఉపయోగించాలో AIకి అర్థం చేసుకోవడంలో సహాయపడుతుంది. అది ఏమి చేస్తుందో, ఎప్పుడు ఉపయోగించడం సముచితమో నిర్దిష్టంగా వివరించండి. సాధారణ 500 ఎర్రర్‌లకు బదులుగా AI అర్థం చేసుకోగల ఎర్రర్ సందేశాలను తిరిగి పంపండి: `{"error": "No slots available for that date"}`. సంభాషణను కొనసాగించడానికి AIకి అవసరమైనదాన్ని మాత్రమే తిరిగి పంపండి. పెద్ద పేలోడ్‌లు ప్రతిస్పందన సమయాలను నెమ్మదింపజేస్తాయి. నిజంగా అవసరమైనప్పుడు మాత్రమే ఫీల్డ్‌లను `required`గా గుర్తించండి. టూల్‌ను కాల్ చేయడానికి ముందు AI అవసరమైన సమాచారాన్ని వినియోగదారుని అడుగుతుంది. --- ## సంబంధితవి ఎండ్‌పాయింట్‌ను నిర్వచించకుండా ప్లాట్‌ఫారమ్ నిర్వహించే కాల్ చర్యలను prompt చేయండి. HubSpot, Salesforce, Slack, Google Calendar, Google Sheets, మరియు Cal.com కోసం ప్లాట్‌ఫారమ్ నిర్వహించే టూల్స్ — ఎండ్‌పాయింట్ అవసరం లేదు. MCP సర్వర్‌ను జతచేసి, ఏజెంట్ దాని టూల్స్‌ను కాల్ చేయనివ్వండి. ఏజెంట్‌లకు జతచేయగల పునర్వినియోగించదగిన REST ఇంటిగ్రేషన్‌లు. వెబ్‌హుక్‌లు మరియు టూల్ కాల్‌ల కోసం ఒక ధృవీకరణ సహాయకం.