একটি টুল ইন্টিগ্রেশন (API) তৈরি করুন

একটি টুল ইন্টিগ্রেশন হলো একটি পুনঃব্যবহারযোগ্য HTTP এন্ডপয়েন্ট, যা একটি এজেন্ট কলের সময় আহ্বান করতে পারে। আপনি ThunderPhone-কে টুলের একটি JSON-schema বিবরণ এবং একটি এন্ডপয়েন্ট URL দেন; এজেন্ট কথোপকথনের ভিত্তিতে কখন এটি কল করবে তা নির্ধারণ করে, এবং ThunderPhone তার সার্ভার থেকে আউটবাউন্ড HTTP অনুরোধ করে ও এজেন্টকে প্রতিক্রিয়া ফেরত দেয়।

এই গাইডে শুরু থেকে শেষ পর্যন্ত একটি আবহাওয়া-অনুসন্ধান টুল তৈরি করা দেখানো হয়েছে।

একটি টুলের গঠন

দুটি অংশ:

1. স্কিমা — একটি OpenAI-ধাঁচের ফাংশন সংজ্ঞা ({type: "function", function: {name, description, parameters}}) যা LLM-কে জানায় টুলটি কী করে এবং এটি কী আর্গুমেন্ট নেয়।
2. এন্ডপয়েন্ট — LLM টুলটি ব্যবহারের সিদ্ধান্ত নিলে ThunderPhone-এর সার্ভার যে URL-এ কল করে। অনুরোধটি JSON POST, যেখানে বডি হিসেবে LLM-এর নির্বাচিত আর্গুমেন্ট থাকে।

1. সংরক্ষণের কৌশল বেছে নিন

এই গাইডে সংরক্ষিত-ইন্টিগ্রেশন পদ্ধতি ব্যবহার করা হয়েছে।

2. ইন্টিগ্রেশন তৈরি করুন

curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string", "description": "5-digit US ZIP code" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "headers": [
      { "key": "X-Api-Key", "value": "your-provider-key" }
    ]
  }'

ফেরত পাওয়া id (একটি UUID) সংরক্ষণ করুন।

3. স্যান্ডবক্সে এন্ডপয়েন্ট পরীক্ষা করুন

ইন্টিগ্রেশনটি এজেন্টের সঙ্গে লিঙ্ক করার আগে, সংযোগ নিশ্চিত করতে ThunderPhone-এর সার্ভার থেকে একটি স্বাক্ষরিত অনুরোধ পাঠান:

curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "headers": { "X-Api-Key": "your-provider-key" }
  }'

{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

এই পরীক্ষাটি ThunderPhone-এর SSRF সুরক্ষাও শক্তিশালী করে — localhost বা ব্যক্তিগত IP রেঞ্জে অনুরোধ করলে 400 code=url_not_allowed ফেরত আসে।

4. এজেন্টের সঙ্গে ইন্টিগ্রেশন লিঙ্ক করুন

এজেন্ট তৈরি বা আপডেট করার সময় integration_ids ব্যবহার করে সংযুক্ত করুন:

curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_ids": ["f9b5a1a4-..."]
  }'

আপনি একটি এজেন্টের সঙ্গে একাধিক ইন্টিগ্রেশন লিঙ্ক করতে পারেন। এজেন্টের prompt নাম ধরে সেগুলো উল্লেখ করতে পারে — কলার আবহাওয়ার অবস্থা সম্পর্কে জিজ্ঞাসা করলে "get_weather ব্যবহার করুন" — অথবা schema-এর বর্ণনা থেকে পরোক্ষভাবে সেগুলো শনাক্ত করতে পারে।

5. এন্ডপয়েন্ট ইমপ্লিমেন্ট করুন

এজেন্ট টুলটি চালু করলে, ThunderPhone আপনার endpoint_url-এ একটি স্বাক্ষরিত POST পাঠায়:

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

আপনার সার্ভার JSON দিয়ে প্রতিক্রিয়া জানায়, যা LLM-এ ফেরত পাঠানো হয়:

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

LLM সেই প্রতিক্রিয়া গ্রহণ করে কলারকে মানুষের উপযোগী একটি সারসংক্ষেপ বলে।

6. সম্পূর্ণ প্রবাহ পরীক্ষা করুন

এজেন্টের বিরুদ্ধে একটি মাইক সেশন চালান এবং আপনার টুল যে প্রশ্নটি পরিচালনা করে তা জিজ্ঞাসা করুন ("94110-এ আবহাওয়া কেমন?")। কলের ট্রান্সক্রিপ্টে সম্পূর্ণ রাউন্ড ট্রিপ দেখা যায়:

{
  "call_id": 987654321,
  "transcripts": [
    { "role": "user",
      "content": "What's the weather in 94110?" },
    { "role": "tool_call",
      "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
    { "role": "tool_response",
      "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
    { "role": "agent",
      "content": "It's 64 degrees and partly cloudy." }
  ]
}

আপনি এটি GET /v1/calls/{call_id}/transcript দিয়ে আনতে পারেন; প্রতি এন্ট্রির সময় এবং অডিও অফসেটসহ কাঁচা ইভেন্ট স্ট্রিমটি রয়েছে GET /v1/calls/{call_id}/history-এ।

সাধারণ সমস্যাগুলো

পরবর্তী ধাপ