Open in
ফাংশন টুলস
আপনার AI এজেন্টদের এমন ফাংশন টুল দিন যা কথোপকথনের মাঝখানে বাহ্যিক API কল করে — গ্রাহকের ডেটা আনে, অ্যাপয়েন্টমেন্ট বুক করে, রেকর্ড আপডেট করে — টাইপ করা প্যারামিটারসহ।
ফাংশন টুল আপনার AI এজেন্টদের ফোন কলের সময় বাহ্যিক API আহ্বান করতে দেয়। গ্রাহকের ডেটা খুঁজতে, উপলভ্যতা পরীক্ষা করতে, অ্যাপয়েন্টমেন্ট বুক করতে বা আপনার ব্যাকএন্ড সমর্থন করে এমন যেকোনো কাজ করতে এগুলো ব্যবহার করুন।
এটি কীভাবে কাজ করে
- আপনি একটি স্কিমাসহ টুল সংজ্ঞায়িত করেন (টুলটি কোন আর্গুমেন্ট গ্রহণ করে)
- আপনি একটি
endpointকনফিগারেশন দেন (ThunderPhone কোথায় আপনার API কল করে) — অথবা আপনার org webhook-এ টুল কল পেতে এটি বাদ রাখুন - কল চলাকালে, কথোপকথনের ভিত্তিতে AI সিদ্ধান্ত নেয় কখন একটি টুল ব্যবহার করবে
- ThunderPhone টুল আর্গুমেন্টসহ আপনার endpoint কল করে
- কথোপকথন চালিয়ে যেতে আপনার API প্রতিক্রিয়া AI-তে ফেরত পাঠানো হয়
| সক্ষমতা | কোথায় চলে | সেটআপ |
|---|---|---|
| অন্তর্নির্মিত টুল | ThunderPhone | Prompt নির্দেশনা; কিছু টুলের জন্য এজেন্ট সেটিংও প্রয়োজন |
| অ্যাপ সংযোগ | ThunderPhone এবং সংযুক্ত প্রোভাইডার | অ্যাকাউন্ট সংযুক্ত করুন এবং অনুমোদিত অ্যাকশন যুক্ত করুন |
| API সংযোগ এবং ফাংশন টুল | আপনার HTTP API | endpoint এবং স্কিমা সংজ্ঞায়িত করুন, অথবা webhook-এর মাধ্যমে ফাংশন কল গ্রহণ করুন |
| MCP সার্ভার | একটি দূরবর্তী MCP সার্ভার | সার্ভার যোগ করুন, এর টুলগুলো আবিষ্কার করুন এবং এজেন্টের সঙ্গে যুক্ত করুন |
টুল স্কিমা
প্রতিটি টুল এই কাঠামো অনুসরণ করে:
{
"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, অথবা wait_mode: "hold" সহ 600) |
wait_mode | স্ট্রিং | না | টুল চলাকালীন কলার যা শোনেন: updates (ডিফল্ট), সংক্ষিপ্ত কথ্য আপডেট; অথবা hold, হোল্ড মিউজিক। দেখুন দীর্ঘ অপেক্ষা: হোল্ড মোড এবং পরে উত্তর দিন |
call_start | অবজেক্ট | না | প্রতিটি ফোন কলের শুরুতে, অভিবাদনের আগে, স্বয়ংক্রিয়ভাবে টুলটি চালান। দেখুন কলের শুরুতে একটি টুল চালান |
ফাংশন সংজ্ঞা
| ক্ষেত্র | ধরন | প্রয়োজনীয় | বিবরণ |
|---|---|---|---|
name | স্ট্রিং | হ্যাঁ | টুলের শনাক্তকারী; একটি কলের টুলগুলোর মধ্যে অনন্য। ভিন্ন এজেন্টের একই নামের নিজস্ব টুল থাকতে পারে |
description | স্ট্রিং | হ্যাঁ | AI-কে ব্যাখ্যা করে কখন এই টুল ব্যবহার করতে হবে |
parameters | অবজেক্ট | হ্যাঁ | টুল আর্গুমেন্টের জন্য JSON Schema |
Endpoint কনফিগারেশন
| ক্ষেত্র | ধরন | প্রয়োজনীয় | বিবরণ |
|---|---|---|---|
url | স্ট্রিং | হ্যাঁ | আপনার API endpoint URL |
method | স্ট্রিং | না | HTTP মেথড (ডিফল্ট: POST) |
headers | অবজেক্ট | না | অন্তর্ভুক্ত করার জন্য কাস্টম হেডার |
দুটি আহ্বান পাথ
আপনার সার্ভার কোন অনুরোধ পাবে, তা নির্ভর করে টুলটির একটি
endpoint আছে কি না তার ওপর:
endpoint-সহ টুল | endpoint-ছাড়া টুল | |
|---|---|---|
| অনুরোধ কোথায় যায় | সরাসরি endpoint.url-এ | আপনার সংস্থার লিগ্যাসি webhook URL-এ |
| বডি | নির্বাচিত অনুরোধ ফরম্যাট (ডিফল্টভাবে শুধু আর্গুমেন্ট) | telephony.tool / web.tool এনভেলপ |
| হেডার | আপনার endpoint.headers + X-ThunderPhone-Call-ID + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature, এবং ফোন কলে কলের নম্বরগুলো | Content-Type + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature |
| সাইনিং কী | সংস্থার webhook সিক্রেট | সংস্থার webhook সিক্রেট |
উভয় পথই ব্লকিং — AI ফলাফলের জন্য বাক্যের মাঝখানে অপেক্ষা করে। ডিফল্ট টাইমআউট 20 s; আরও দীর্ঘ এক্সিকিউশন অনুমোদন করতে টুলের শীর্ষ-স্তরের timeout সেট করুন, প্ল্যাটফর্মের সর্বোচ্চ 180 s পর্যন্ত। হ্যান্ডলার দ্রুত রাখুন। কোনো ব্যক্তি বা ধীর কাজের জন্য অপেক্ষা করতে হোল্ড মোড ব্যবহার করুন। মিশ্রণও করা যায়: যে কলে থাকা org-এর একটি webhook URL আছে, সেখানে endpoint-সহ টুলগুলো সরাসরি কল করা হয় এবং বাকি টুলগুলো webhook-এ ফিরে যায়।
সরাসরি endpoint কল
AI যখন এমন একটি টুল আহ্বান করে যার একটি endpoint আছে, ThunderPhone আপনার URL-এ একটি
অনুরোধ পাঠায়:
অনুরোধ হেডার
POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-keyআপনার endpoint.headers থেকে কাস্টম হেডার সবসময়
হুবহু অন্তর্ভুক্ত করা হয়, সঙ্গে এই ThunderPhone-নেমস্পেসযুক্ত হেডারগুলো:
X-ThunderPhone-Signature-V2— মেথড, পাথ, কোয়েরি এবং বডির ওপর টাইমস্ট্যাম্পযুক্ত HMAC-SHA256, যা আপনার সংস্থার ওয়েবহুক সিক্রেট দিয়ে কী করা। এটি যাচাই করুন এবং 5 মিনিটের বেশি পুরোনো অনুরোধ প্রত্যাখ্যান করুন; দেখুন ওয়েবহুক স্বাক্ষর যাচাই করুনX-ThunderPhone-Signature— অনুরোধ-বডির সঠিক বাইটগুলোর লিগ্যাসি HMAC-SHA256, একই কী ব্যবহার করে; বিদ্যমান যাচাইকারীদের জন্য এখনও পাঠানো হয়X-ThunderPhone-Call-ID— বর্তমান কল IDX-ThunderPhone-From-NumberএবংX-ThunderPhone-To-Number— E.164 ফরম্যাটে কলের From এবং To নম্বর। এগুলোর অর্থtelephony.complete-এরfrom_numberএবংto_number-এর মতোই: একটি আউটবাউন্ড কলে From হলো আপনার এজেন্টের নম্বর এবং To হলো যাকে কল করা হয়েছে তার নম্বর। কলার ID গোপন রাখা হলে বা সেটি ফোন নম্বর না হলে একটি নম্বর বাদ দেওয়া হয়X-ThunderPhone-Call-Direction—inboundবাoutbound, যাতে আপনি নির্ধারণ করতে পারেন কোন নম্বরটি গ্রাহকের
কল-নম্বর হেডার কেবল ফোন কলে পাঠানো হয়। ওয়েব, উইজেট, রিয়েলটাইম এবং ব্রাউজার Talk পরীক্ষায় কোনো ফোন নম্বর থাকে না, তাই এগুলো বাদ থাকে। এজেন্ট এডিটর থেকে করা টেস্ট কল এবং AI সিমুলেশনে সিমুলেট করা কলারের নম্বর থাকে। স্বাক্ষরগুলোর মধ্যে হেডার অন্তর্ভুক্ত থাকে না: V2 টাইমস্ট্যাম্প, মেথড, পাথ, কোয়েরি এবং বডিতে স্বাক্ষর করে। আপনার যদি নম্বরগুলো স্বাক্ষরিত অবস্থায় প্রয়োজন হয়, তাহলে সেগুলো বডি থেকে পড়ুন: retell অনুরোধ ফরম্যাটে তিনটিই থাকে এবং vapi-তে গ্রাহকের নম্বর থাকে।
আপনার endpoint.headers এটি ওভাররাইড না করলে Content-Type: application/json
সেট করা হয় — কাস্টম Content-Type অগ্রাধিকার পায়।
অনুরোধের ফর্ম্যাট
প্রতিটি API সংযোগে একটি request_format সেটিং থাকে। ইমপোর্ট করা কোনো টুলকে সেই প্ল্যাটফর্মের জন্য তৈরি এন্ডপয়েন্টে কল করতে রাখতে vapi বা
retell বেছে নিন। নতুন ও বিদ্যমান সংযোগগুলোর ডিফল্ট হলো standard।
POST / PUT / PATCH-এর জন্য ThunderPhone নির্বাচিত
এনভেলপ ক্যানোনিক্যালভাবে সিরিয়ালাইজ করে (সাজানো কী, কমপ্যাক্ট বিভাজক)। উভয় স্বাক্ষর এই সঠিক বাইটগুলো কভার করে।
Standard
standard কোনো র্যাপার ছাড়াই শুধু টুল আর্গুমেন্ট পাঠায়। এটি ডিফল্ট এবং ThunderPhone-এর মূল রিকোয়েস্ট বডি বাইটের পর বাইট অপরিবর্তিত রাখে:
{"date":"2025-01-02","service":"consultation"}Vapi
vapi, Vapi যে আকারে নথিভুক্ত করেছে সেই আকারে Vapi-এর tool-calls সার্ভার বার্তা পাঠায়। call.id হলো ThunderPhone কল ID।
ফোন কলে, call.customer.number হলো অপর পক্ষের নম্বর, Vapi-এর কল অবজেক্টের মতো: ইনবাউন্ড কলে কলার এবং
আউটবাউন্ড কলে যাকে কল করা হয়। নম্বরটি গোপন রাখা হলে বা সেটি ফোন নম্বর না হলে এটি অন্তর্ভুক্ত করা হয় না। টুল-কলের id ইনভোকেশনের জন্য অনন্য এবং
এন্ডপয়েন্টের ফলাফলের সঙ্গে মেলাতে পুনরায় ব্যবহার করা হয়। কলটি toolCallList এবং
toolWithToolCallList উভয়টিতেই দেখা যায়, যেখানে function.arguments একটি JSON অবজেক্ট:
{
"message": {
"type": "tool-calls",
"timestamp": 1725000000123,
"call": { "id": "987654321" },
"toolCallList": [
{
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
],
"toolWithToolCallList": [
{
"type": "function",
"function": { "name": "search_appointments" },
"toolCall": {
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
}
]
}
}assistant, artifact এবং সম্পূর্ণ call অবজেক্টের মতো শুধু Vapi-এর জন্য প্রযোজ্য ফিল্ড পাঠানো হয় না।
মিল থাকা টুল-কল ID-সহ Vapi-এর রেসপন্স এনভেলপ ফেরত দিন:
{
"results": [
{
"toolCallId": "call_00112233445566778899aabbccddeeff",
"result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
}
]
}ThunderPhone AI-কে আনর্যাপ করা result স্ট্রিং দেয়। যেসব এন্ডপয়েন্ট ইতিমধ্যে JSON মান ফেরত দেয়, তাদের সামঞ্জস্যের জন্য এটি JSON মানও গ্রহণ করে। result-এর পরিবর্তে থাকা একটি error টুল ত্রুটি হিসেবে AI-তে ফেরত দেওয়া হয়। এন্ডপয়েন্ট বিকৃত বা অমিল Vapi এনভেলপ ফেরত দিলে, ThunderPhone একটি সতর্কতা লগ করে এবং কল ব্যর্থ করার পরিবর্তে তার স্ট্যান্ডার্ড রেসপন্স পার্সিংয়ে ফিরে যায়।
Retell
retell, একটি Retell কাস্টম ফাংশন-এর জন্য ডকুমেন্ট করা অনুরোধ পাঠায়:
{
"name": "search_appointments",
"call": {
"call_id": "987654321",
"from_number": "+14155550199",
"to_number": "+14155550100",
"direction": "inbound"
},
"args": { "date": "2025-01-02", "service": "consultation" }
}ফোন কলে, call অবজেক্টে call_id, from_number,
to_number এবং direction (inbound বা outbound) থাকে, যা
Retell-এর ফোন কল অবজেক্টে ব্যবহৃত ফিল্ড নাম। এগুলো কল-নম্বর হেডারের সঙ্গে মেলে,
এবং হেডারগুলোর বিপরীতে এগুলো উভয় স্বাক্ষরের আওতায় থাকে। গোপন রাখা হয়েছে বা
ফোন নম্বর নয় এমন কোনো নম্বর বাদ দেওয়া হয়। ওয়েব, উইজেট,
রিয়েলটাইম এবং ব্রাউজার Talk পরীক্ষায় এতে শুধু call_id থাকে। ThunderPhone
পাঠানোর সময় সত্যনিষ্ঠভাবে সরবরাহ করতে না পারা Retell-নির্দিষ্ট ফিল্ড অন্তর্ভুক্ত করে না,
যেমন agent_id, transcript, transcript_object, metadata, অথবা
ডাইনামিক ভেরিয়েবল। Retell যেকোনো রেসপন্স বডি গ্রহণ করে; ThunderPhone
স্ট্যান্ডার্ড রেসপন্স হ্যান্ডলিং ব্যবহার করে তা পাঠিয়ে দেয়।
GET / DELETE-এর জন্য, request_format নির্বিশেষে আর্গুমেন্টগুলো কোয়েরি প্যারামিটার হিসেবে পাঠানো হয় এবং বডি খালি থাকে। V2 স্বাক্ষর পাঠানো কোয়েরি স্ট্রিংকে কভার করে; লিগ্যাসি স্বাক্ষর খালি বাইট স্ট্রিংয়ের ওপর গণনা করা হয়। দেখুন
ওয়েবহুক স্বাক্ষর যাচাই করুন।
প্রতিক্রিয়া
টুলের ফলাফলসহ একটি JSON প্রতিক্রিয়া ফেরত দিন:
{
"available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
"timezone": "America/Los_Angeles"
}প্রতিক্রিয়াটি ফরম্যাট করে কথোপকথন চালিয়ে যাওয়ার জন্য AI-কে দেওয়া হয়।
নন-JSON প্রতিক্রিয়াগুলো {"data": "<text>"} হিসেবে wrapper করা হয়;
timeout এবং সংযোগ ব্যর্থতা AI-কে ত্রুটি হিসেবে জানানো হয়, যাতে
এজেন্ট থেমে না গিয়ে ক্ষমা চেয়ে এগিয়ে যেতে পারে।
Webhook-মোড ডিসপ্যাচ
endpoint ছাড়া টুলগুলো আপনার org-এর লিগ্যাসি webhook URL-এ স্বাক্ষরিত telephony.tool (ফোন কল) অথবা web.tool
(ওয়েব কল) অনুরোধ হিসেবে ডিসপ্যাচ করা হয়। এক্সিকিউশনের পরে webhook endpoint-এ পৌঁছানো অডিট বিজ্ঞপ্তি-এর
বিপরীতে, এই অনুরোধটিই হল
এক্সিকিউশন — আপনার 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 হিসেবে পাঠান — সরাসরি endpoint কলে ব্যবহৃত একই প্রতিক্রিয়া চুক্তি। অন্য সব webhook-এর মতো, উভয় signature header-সহ অনুরোধটি org webhook secret দিয়ে স্বাক্ষরিত থাকে।
দীর্ঘ অপেক্ষা: হোল্ড মোড এবং পরে উত্তর দিন
কিছু টুল একজন ব্যক্তির জন্য অপেক্ষা করে: কোনো ম্যানেজার ডিসকাউন্ট অনুমোদন করছেন, কোনো মালিক Slack-এ একটি প্রশ্নের উত্তর দিচ্ছেন। সেই টুলগুলোতে wait_mode-কে "hold" সেট করুন।
wait_mode: "updates" (ডিফল্ট) | wait_mode: "hold" | |
|---|---|---|
| কলার যা শোনে | টুল-শুরুর লাইন, তারপর প্রায় 12 সেকেন্ড পরে একটি সংক্ষিপ্ত "এখনও কাজ চলছে" লাইন এবং প্রায় প্রতি 15 সেকেন্ডে আরেকটি | টুল-শুরুর লাইন, তারপর ফলাফল আসা পর্যন্ত হোল্ড মিউজিক |
timeout সর্বোচ্চ | 180 সেকেন্ড | 600 সেকেন্ড |
| মুলতুবি উত্তর | ফলাফল হিসেবে এজেন্টের কাছে পাঠানো হয় | আপনি ফলাফল সরবরাহ না করা পর্যন্ত টুলটি খোলা থাকে |
হোল্ড মোডে টুল শুরু হওয়ার সময় এজেন্ট একটি লাইন বলে (নিজের ভাষায়, অথবা এজেন্টে সেট করা টুল-শুরুর লাইন), তারপর কলার হোল্ড মিউজিক শোনে। এজেন্ট ফলাফল বলার আগে মিউজিক ধীরে ধীরে বন্ধ হয়। এক বা দুই সেকেন্ডের মধ্যে উত্তর দেওয়া টুলে কোনো মিউজিক বাজে না। এজেন্ট যখন কোনো ফোন মেনু বা ভয়েসমেইল বক্সের সঙ্গে কথা বলে, তখন এটি কথ্য আপডেট ব্যবহার করে, কারণ মিউজিককে উত্তর হিসেবে শোনা হতে পারে। এর মধ্যে হোল্ড চলাকালে মেনু বা মেইলবক্স হিসেবে শনাক্ত হওয়া কলও অন্তর্ভুক্ত: মিউজিক বন্ধ হয় এবং কথ্য আপডেট শুরু হয়। যেসব কলে মিউজিক বাজানো যায় না, সেখানেও একই ঘটনা ঘটে।
হোল্ড চলাকালে কলার কথা বললে মিউজিক চলতে থাকে এবং এজেন্ট তখনও উত্তর দেয় না। কলার কী বলেছে তা এজেন্ট শোনে এবং ফলাফলের সঙ্গে তার উত্তর দেয়। কল কেটে দিলে কল এবং খোলা টুল শেষ হয়ে যায়।
পরে উত্তর দিন
আপনার এন্ডপয়েন্টের নিজস্ব প্রতিক্রিয়া এখনও 180 সেকেন্ডের মধ্যে আসতে হবে। কলারকে আরও বেশি সময় হোল্ডে রাখতে, মুলতুবি ফলাফলসহ সঙ্গে সঙ্গে উত্তর দিন:
{ "status": "pending", "request_id": "ask-4471" }request_id হলো সর্বোচ্চ 200 অক্ষরের যেকোনো স্ট্রিং, যা আপনার দিক থেকে এই
অনুরোধ শনাক্ত করে। কলার হোল্ডে থাকে যতক্ষণ না আপনি এর ফলাফল
POST /v1/calls/{call_id}/tool-results-এর মাধ্যমে সরবরাহ করেন।
call_id হলো টুল অনুরোধের X-ThunderPhone-Call-ID হেডার।
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_id": "ask-4471",
"result": { "answer": "Yes, book Tuesday at 10." }
}'এজেন্ট result-কে টুলের উত্তর হিসেবে পড়ে, ঠিক যেমন আপনার এন্ডপয়েন্ট
সেটি ফেরত দিলে পড়ত। টুল কল হওয়ার সময় থেকে গণনা করা টুলের timeout-এর
আগে কোনো ফলাফল না এলে, এজেন্টকে জানানো হয় যে কোনো উত্তর ফেরত আসেনি এবং
এটি কলারকে পরবর্তী পদক্ষেপের প্রস্তাব দেয়, যেমন একটি বার্তা নেওয়া।
আপনার মুলতুবি প্রতিক্রিয়া ThunderPhone-এ পৌঁছানোর আগেও আপনি চাইলে ফলাফল
পোস্ট করতে পারেন। একটি 202 মানে কল সেটি গ্রহণ করেছে: কোনো খোলা অনুরোধ
সেটি নিয়েছে, অথবা টুলের নিজস্ব অনুরোধ এখনও প্রক্রিয়াধীন এবং তার মুলতুবি
উত্তর সেটি গ্রহণ করবে। এমন ফলাফল যা কোনো অনুরোধ কখনও গ্রহণ করে না (আপনার
এন্ডপয়েন্ট পরে সেই request_id-এর জন্য মুলতুবি ছাড়া অন্য কিছু দিয়ে
উত্তর দিয়েছে) বাদ দেওয়া হয়।
সংযোগে প্রতিক্রিয়া রূপান্তর থাকলে (এজেন্ট দেখার আগে আপনার এন্ডপয়েন্টের
উত্তর পুনর্লিখন করে এমন কোড), ThunderPhone মুলতুবি উত্তর পরীক্ষা করার আগে
রূপান্তরটি আপনার এন্ডপয়েন্টের নিজস্ব উত্তরের ওপর চলে, তাই এটিকে মুলতুবি
উত্তরে status এবং request_id রাখতে হবে। পরে পোস্ট করা ফলাফলের ওপর এটি
চলে না: এজেন্ট ফলাফলটি আপনার পাঠানো অবস্থাতেই পায়।
একটি ফুল-ডুপ্লেক্স এজেন্টে কোনো হোল্ড মিউজিক বা আপডেট লাইন নেই, তাই এর
কলগুলোতে একটি হোল্ড টুল updates টুলের মতো আচরণ করে: একটি মুলতুবি উত্তর
টুলের ফলাফল হিসেবে এজেন্টের কাছে পৌঁছায়।
updates মোডে থাকা টুলের মুলতুবি প্রতিক্রিয়া খোলা রাখা হয় না: এজেন্ট
সেটি টুলের ফলাফল হিসেবে পায়।
স্বাক্ষর যাচাইকরণ
সরাসরি টুল কলগুলো আপনার প্রতিষ্ঠানের webhook secret ব্যবহার করে webhook-এর মতোই সাইন করা হয়:
X-ThunderPhone-Signature-V2প্রেরিত timestamp, method, path ও query এবং body-এর হুবহু বাইটগুলোতে সাইন করে। timestamp আপনার ঘড়ির সময় থেকে 5 মিনিটের বেশি পার্থক্য হলে অনুরোধ প্রত্যাখ্যান করুন।X-ThunderPhone-Signature(লিগ্যাসি) শুধু body-এর বাইটগুলোতে সাইন করে;GET/DELETE-এর জন্য খালি byte string ব্যবহার করে। এটি এখনও অপরিবর্তিত অবস্থায় পাঠানো হয়।
SDK helper-গুলো 5 মিনিটের সময়সীমাসহ V2 header পরীক্ষা করে:
import json
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
app = FastAPI()
@app.post("/appointments/search")
async def search_appointments(request: Request):
body = await request.body()
query = request.scope.get("query_string", b"").decode("latin-1")
path = request.url.path + (f"?{query}" if query else "")
if not verify_signature(
request.headers.get("X-ThunderPhone-Signature-V2"),
secret=WEBHOOK_SECRET,
method=request.method,
path=path,
body=body,
):
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}import express from "express";
import { verifySignature } from "@thunderphone/sdk";
app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
const ok = verifySignature({
header: req.header('X-ThunderPhone-Signature-V2'),
secret: WEBHOOK_SECRET,
method: req.method,
path: req.originalUrl,
body: req.body,
});
if (!ok) 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 });
});সম্পূর্ণ রেসিপি — সাইন করা string, একটি কার্যকর উদাহরণ, SDK ছাড়া কোড, GET / DELETE ক্ষেত্র এবং secret না থাকার সতর্কতা — Webhook signature যাচাই করুন-এ রয়েছে।
উদাহরণ: সম্পূর্ণ বুকিং ফ্লো
এখানে একটি সম্পূর্ণ অ্যাপয়েন্টমেন্ট বুকিং সিস্টেমের জন্য টুলগুলোর একটি সেট দেওয়া হলো:
{
"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" }
}
}
]
}কলের শুরুতে একটি টুল চালান
প্রতিটি ফোন কলের শুরুতে, এজেন্ট তার প্রথম কথা বলার আগেই একটি টুল স্বয়ংক্রিয়ভাবে চলতে পারে, যাতে অভিবাদনে ফলাফলটি ব্যবহার করা যায়। সাধারণত কলারের নম্বর দিয়ে CRM লুকআপ করা হয়: "আবার স্বাগতম, আর্থি! আপনি কি আপনার নিয়মিত অর্ডারটি চান?"
ড্যাশবোর্ডে API সংযোগ খুলুন এবং কখন এটি চলে-কে প্রতিটি ফোন কলের শুরুতে সেট করুন, তারপর প্রতিটি প্যারামিটারের জন্য যে মান পাবে তা পূরণ করুন। API-এর মাধ্যমে ইন্টিগ্রেশনের trigger-কে call_start এবং এর call_start_arguments
(API সংযোগ) সেট করুন, অথবা একটি ইনলাইন টুলে call_start
ব্লক যোগ করুন:
{
"type": "function",
"function": {
"name": "get_contact_by_phone",
"description": "Look up a customer by phone number.",
"parameters": {
"type": "object",
"properties": {
"business_id": {"type": "string"},
"phone_number": {"type": "string"}
},
"required": ["business_id", "phone_number"]
}
},
"endpoint": {"url": "https://crm.example.com/contacts/lookup"},
"call_start": {
"arguments": {
"business_id": "a0a81c23",
"phone_number": "{{caller_number}}"
}
}
}প্রতিটি প্রয়োজনীয় প্যারামিটারের জন্য arguments-এ একটি মান থাকতে হবে, কারণ কল শুরুর সময় কেউ কিছু পূরণ করে না। মান স্ট্রিং, সংখ্যা বা বুলিয়ান হতে পারে। এগুলো সাধারণ টেক্সট হিসেবে সংরক্ষিত ও ফেরত দেওয়া হয় এবং এজেন্ট সেগুলো দেখতে পায়, তাই API কী-এর মতো গোপন তথ্য এখানে নয়, সংযোগের হেডারে রাখুন। স্ট্রিংয়ে এই প্লেসহোল্ডারগুলো ব্যবহার করা যায়:
| প্লেসহোল্ডার | মান |
|---|---|
{{caller_number}} | E.164 ফরম্যাটে কলে থাকা অন্য ব্যক্তির নম্বর, যেমন +61402122887: ইনবাউন্ড কলে কলার, আউটবাউন্ড কলে যাকে কল করা হয়েছে |
{{caller_number_national}} | স্পেস ছাড়া ওই দেশের জাতীয় ফরম্যাটে একই নম্বর, যেমন 0402122887 |
{{agent_number}} | এজেন্টের নিজস্ব নম্বর |
এটি যেভাবে কাজ করে:
- অনুরোধটি এজেন্টের নিজস্ব টুল কল থেকে পাঠানো অনুরোধের মতোই হয় (একই endpoint, headers, অনুরোধের ফরম্যাট এবং signature)।
- কল শুরু হলে টুলটি শুরু হয় এবং যেকোনো সংযোগ টোন, পরিচিতিমূলক বার্তা বা রেকর্ডিং বিজ্ঞপ্তি চলাকালীন কাজ করে। ওই সময় থেকে অভিবাদন এটির জন্য প্রায় 3 সেকেন্ড পর্যন্ত অপেক্ষা করে। ধীরগতির ফলাফল আসামাত্র বাকি কলের জন্য এজেন্টকে দেওয়া হয়। আউটবাউন্ড কলে, কল দেওয়ার সময় এটি শুরু হয়, তাই কেউ উত্তর না দিলেও প্রতিটি চেষ্টায় এটি চলে।
- যে এজেন্টে কলার আগে কথা বলে, সেখানে অপেক্ষা করার মতো কোনো অভিবাদন থাকে না; ফলাফল আসামাত্র এজেন্ট তা পায়।
- ফলাফলটি পুরো কলের জন্য প্রসঙ্গ হিসেবে এজেন্টকে দেওয়া হয়। এটি কীভাবে ব্যবহার করতে হবে তা আপনার prompt-এ এজেন্টকে জানান; অন্যথায় এটি পড়ে শোনানো হয় না।
- টুল ব্যর্থ হলে বা সময় শেষ হয়ে গেলে, এজেন্ট স্বাভাবিকভাবে কলারকে অভিবাদন জানায় এবং এ সম্পর্কে কিছু বলে না।
- এজেন্ট পরে কলের মধ্যে নিজেও টুলটি কল করতে পারে।
- এটি ফোন কলে চলে, যার মধ্যে আপনার ফোনে ড্যাশবোর্ডের পরীক্ষামূলক কল এবং AI সিমুলেশন অন্তর্ভুক্ত; AI সিমুলেশন আপনার endpoint-এ সিমুলেট করা কলারের নম্বর পাঠায়। এটি ব্রাউজার কথোপকথন পরীক্ষা বা ওয়েব উইজেট সেশনে চলে না, কারণ সেগুলোতে কোনো কলার নম্বর থাকে না; কলার ID গোপন রাখা কলেও নয়, বা ধাপযুক্ত এজেন্টেও নয়।
- একটি এজেন্ট একসঙ্গে সর্বোচ্চ তিনটি কল-শুরুর টুল চালায়।
আপনার prompt-এ ফলাফলটির উল্লেখ করুন, যাতে এজেন্ট বুঝতে পারে এটি কীভাবে ব্যবহার করতে হবে, উদাহরণস্বরূপ: "কল শুরুর লুকআপে কলারকে পাওয়া গেলে, তাকে প্রথম নামে অভিবাদন জানান।"
সেরা অনুশীলন
স্পষ্ট বিবরণ লিখুন
description ফিল্ডটি AI-কে টুলটি কখন ব্যবহার করতে হবে তা বুঝতে সাহায্য করে। এটি কী করে এবং কখন উপযুক্ত, সে বিষয়ে সুনির্দিষ্ট থাকুন।
সুচারুভাবে ত্রুটি পরিচালনা করুন
AI বুঝতে পারে এমন ত্রুটি বার্তা দিন: সাধারণ 500 ত্রুটির পরিবর্তে {"error": "No slots available for that date"}।
প্রতিক্রিয়া সংক্ষিপ্ত রাখুন
কথোপকথন চালিয়ে যেতে AI-এর যা প্রয়োজন, শুধু তা-ই ফেরত দিন। একটি টুলের ফলাফল কথোপকথনে থেকে যায় এবং পরবর্তী প্রতিটি টার্নে আবার পড়া হয়, তাই বড় ফলাফল কলের বাকি অংশে খরচ ও বিলম্ব বাড়ায়। 100,000 অক্ষরের বেশি ফলাফল অসম্পূর্ণ বলে AI জানে এমন একটি প্রিভিউতে সংক্ষিপ্ত করা হয়, এবং খুব দীর্ঘ কলে পুরোনো ফলাফল বাদ পড়তে পারে (AI আবার টুলটি কল করতে পারে)। একটি প্যারামিটার যোগ করুন যাতে AI একবারে একটি আইটেম বা ক্যাটাগরি খুঁজে দেখতে পারে, এবং মেনু বা ক্যাটালগের মতো বড় রেফারেন্স কনটেন্ট নলেজ বেসে রাখুন। ড্যাশবোর্ডে টেস্ট রিকোয়েস্ট পাঠান প্রতিটি ফলাফলের আকার দেখায় এবং বড় হলে সতর্ক করে।
প্রয়োজনীয় ফিল্ড বিচক্ষণতার সঙ্গে ব্যবহার করুন
সত্যিই প্রয়োজন হলে তবেই ফিল্ডকে required হিসেবে চিহ্নিত করুন। টুল কল করার আগে AI ব্যবহারকারীর কাছে প্রয়োজনীয় তথ্য চাইবে।
সম্পর্কিত
এন্ডপয়েন্ট নির্ধারণ না করেই প্ল্যাটফর্ম-পরিচালিত কল অ্যাকশন prompt করুন।
HubSpot, Salesforce, Google Calendar, Google Sheets এবং Cal.com-এর জন্য প্ল্যাটফর্ম-পরিচালিত টুল — কোনো এন্ডপয়েন্ট প্রয়োজন নেই।
একটি MCP সার্ভার সংযুক্ত করুন এবং এজেন্টকে এর টুল কল করতে দিন।
পুনর্ব্যবহারযোগ্য REST ইন্টিগ্রেশন যা আপনি এজেন্টের সঙ্গে সংযুক্ত করতে পারেন।
ওয়েবহুক ও টুল কলের জন্য একটি যাচাইকরণ সহায়ক।