Developer cookbook

टूल इंटीग्रेशन (API) बनाएं

अपने एजेंट को बातचीत के दौरान आपके APIs कॉल करने दें — डेटाबेस खोजें, टिकट बनाएं, ऑर्डर देखें।

एक टूल इंटीग्रेशन एक पुन: उपयोग योग्य HTTP एंडपॉइंट है जिसे एजेंट कॉल के दौरान इनवोक कर सकता है। आप ThunderPhone को टूल का JSON-स्कीमा विवरण और एक एंडपॉइंट URL देते हैं; एजेंट बातचीत के आधार पर तय करता है कि इसे कब कॉल करना है, और ThunderPhone अपने सर्वर से आउटबाउंड HTTP रिक्वेस्ट करता है और रिस्पॉन्स एजेंट को लौटाता है।

यह गाइड एक वेदर-लुकअप टूल को शुरू से अंत तक बनाने की प्रक्रिया बताती है।

टूल की संरचना#

दो हिस्से:

1. स्कीमा — एक OpenAI-स्टाइल फ़ंक्शन डेफिनिशन ({type: "function", function: {name, description, parameters}}) जो LLM को बताती है कि टूल क्या करता है और वह कौन से आर्ग्युमेंट लेता है।
2. एंडपॉइंट — वह URL जिसे ThunderPhone के सर्वर तब कॉल करते हैं जब LLM टूल का उपयोग करने का निर्णय लेता है। रिक्वेस्ट 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-..."]
  }'

आप एक एजेंट से कई इंटीग्रेशन लिंक कर सकते हैं। एजेंट का प्रॉम्प्ट उन्हें नाम से रेफर कर सकता है — "जब कॉलर परिस्थितियों के बारे में पूछे तो 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"}

आपका सर्वर JSON के साथ प्रतिक्रिया देता है, जो LLM को वापस भेज दिया जाता है:

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

LLM उस प्रतिक्रिया को इनजेस्ट करता है और कॉलर को एक मानवीय सारांश बोलता है।

6. लूप टेस्ट करें#

एजेंट के विरुद्ध एक mic session चलाएँ और वह प्रश्न पूछें जिसे आपका टूल हैंडल करता है ("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 पर है।

सामान्य समस्याएँ#

अगले चरण#