टूल इंटिग्रेशन (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 वापरा — किंवा स्कीमा वर्णनांवरून एजंट त्यांना अप्रत्यक्षपणे शोधू शकतो.

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

तुमचा सर्व्हर LLM कडे परत पाठवला जाणारा JSON प्रतिसाद देतो:

{"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 येथे आहे.

सामान्य अडचणी

पुढील पायऱ्या