टूल इंटिग्रेशन तयार करा (API)

तुमच्या एजंटला संभाषणादरम्यान तुमचे API कॉल करू द्या — डेटाबेस शोधा, तिकीट तयार करा, ऑर्डर शोधा.

टूल इंटिग्रेशन हा पुनर्वापरता येणारा HTTP एंडपॉइंट आहे, जो एजंट कॉलदरम्यान invoke करू शकतो. तुम्ही ThunderPhone ला टूलचे JSON-स्कीमा वर्णन आणि एंडपॉइंट URL देता; संभाषणाच्या आधारे एजंट ते कधी कॉल करायचे हे ठरवतो, आणि ThunderPhone त्याच्या सर्व्हरवरून आउटबाउंड HTTP विनंती करून प्रतिसाद एजंटकडे परत पाठवते.

हे मार्गदर्शक हवामान शोधणारे टूल सुरुवातीपासून शेवटपर्यंत तयार करण्याची प्रक्रिया सांगते.

टूलची रचना#

दोन भाग:

1. स्कीमा — OpenAI-शैलीतील फंक्शन डेफिनिशन ({type: "function", function: {name, description, parameters}}) जी LLM ला टूल काय करते आणि ते कोणते आर्ग्युमेंट स्वीकारते हे सांगते.
2. एंडपॉइंट — LLM ने टूल वापरण्याचे ठरवल्यावर ThunderPhone चे सर्व्हर कॉल करतात तो URL. विनंती ही JSON POST असते आणि LLM ने निवडलेले आर्ग्युमेंट तिच्या बॉडीमध्ये असतात.

1. संपादक निवडा#

दोन्ही मार्ग जतन केलेले इंटिग्रेशन तयार करतात. ते जतन केल्यानंतर हे इंटिग्रेशन एजंटला जोडा. Agents API मध्ये लिहिता येईल असे इनलाइन tools फील्ड नाही. हे मार्गदर्शक इंटिग्रेशन्स API मार्ग वापरते.

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) जतन करा.

पत्ता पॅरामीटर्सवर format: "email" घोषित करा#

ईमेल पत्ता स्वीकारणाऱ्या पॅरामीटरने त्याच्या स्कीमामध्ये तसे नमूद केले पाहिजे:

"email": { "type": "string", "format": "email", "description": "The caller's email address" }

format केवळ सूचक नाही. निश्चित झालेल्या ईमेल स्कीमासाठी, तुमचा एंडपॉइंट कॉल होण्यापूर्वी ThunderPhone मूल्याच्या सुरुवाती-शेवटची रिकामी जागा काढते, डोमेन लोअरकेसमध्ये करते, स्वतंत्र इंग्रजी शब्द at, dot, underscore, dash, आणि hyphen यांना त्यांच्या चिन्हांमध्ये रूपांतरित करते आणि @, ., _, आणि - च्या लगतची रिकामी जागा काढून टाकते. ट्रान्स्क्रिप्टमध्ये प्रत्यक्ष @ आधीपासून असो वा नसो, या शब्दांचा अर्थ तोच असतो: "john dot smith at gmail dot com" चे रूपांतर john.smith@gmail.com असे होते.

इतर कोणतीही अंतर्गत रिकामी जागा शांतपणे जोडण्याऐवजी नाकारली जाते. उच्चारलेले विभाजक शब्द केवळ इंग्रजीसाठी आहेत; इंग्रजीतर किंवा ओळखू न येणारे रिकामी जागेसह असलेले प्रकार सुरक्षितपणे अयशस्वी होतात. वैध आंतरराष्ट्रीयीकृत डोमेन्स आणि SMTPUTF8 लोकल पार्ट्स स्वीकारले जातात. पार्सर नॉर्मलायझेशननंतर Punycode इनपुट Punycodeच राहते आणि Unicode डोमेन इनपुट Unicodeच राहते, त्यामुळे तुमच्या API ला कॉलरने दिलेले प्रचलित प्रतिनिधित्व मिळते. अंतिम मूल्य अवैध असल्यास, टूल कॉल केले जात नाही. एजंटला invalid_email_argument मिळते, जे त्याला कॉलरकडून स्पेलिंगची पुष्टी करून प्रत्यक्ष पत्ता पुन्हा पाठवण्यास सांगते.

वगळलेला पर्यायी ईमेल जसा आहे तसाच राहतो. प्रॉपर्टी पर्यायी किंवा नलेबल असल्यास null, रिकामी स्ट्रिंग किंवा केवळ रिकामी जागा असलेली स्ट्रिंगही जशी आहे तशीच राहते; आवश्यक, नॉन-नलेबल ईमेलसाठी हीच मूल्ये नाकारली जातात.

#/$defs/email आणि #/definitions/email यांसारखे स्थानिक स्कीमा संदर्भ, तसेच anyOf, oneOf, आणि allOf, सायकल आणि खोली मर्यादांसह तपासले जातात. नॉन-लोकल किंवा निराकरण न होणारा $ref ही ज्ञात अंमलबजावणी मर्यादा आहे आणि तो जसाच्या तसा पुढे पाठवला जातो; वापरण्यायोग्य स्कीमा नसलेल्या टूल स्नॅपशॉटचा कॉलही तसाच पुढे पाठवला जातो. गेट लागू करायचा असल्यास ईमेल स्कीमा स्थानिक ठेवा.

लागू केलेला ईमेल फॉरमॅट नसलेले पॅरामीटर्स मॉडेलने तयार केल्याप्रमाणेच जसाच्या तशा पुढे पाठवले जातात.

समर्थित फॉरमॅट्स date-time, time, date, duration, email, hostname, ipv4, ipv6, आणि uuid आहेत; आज केवळ email नॉर्मलाइझ आणि लागू केले जाते.

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

तुमचा सर्व्हर 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.

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

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