ThunderPhone v3 आता लाइव्ह आहे.स्वतःच सुरू करा—2¢/मिनिटपासून.घोषणा वाचा

Developer cookbook

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

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

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

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

टूलची रचना

दोन भाग:

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

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

डॅशबोर्ड

कनेक्शन्स → APIs उघडा, API कनेक्शन तयार करा किंवा संपादित करा, पॅरामीटर एडिटर JSON वर बदला आणि तेथे फॉरमॅट जोडा.

इंटिग्रेशन्स API

POST /v1/integrations वापरून स्पेसिफिकेशन तयार करा किंवा PATCH /v1/integrations/{id} वापरून ते अद्यतनित करा.

दोन्ही मार्ग जतन केलेले इंटिग्रेशन तयार करतात. ते जतन केल्यानंतर हे इंटिग्रेशन एजंटला जोडा. 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) जतन करा. हेडर मूल्ये केवळ-लेखनासाठी आहेत: प्रतिसादांमध्ये फक्त हेडरची नावे सूचीबद्ध होतात आणि नंतरचा PATCH साठवलेले मूल्य कायम ठेवण्यासाठी value शिवाय हेडर पाठवू शकतो.

पत्ता पॅरामीटर्सवर 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" }
  }'
Response
{
  "ok": true,
  "status_code": 200,
  "reason": "OK",
  "latency_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_body_preview": "{\"temperature_f\": 64, ...}",
  "response_truncated": false
}

चाचणीमध्ये थेट टूल कॉलप्रमाणेच ThunderPhone हेडर्स असतात आणि ती तुमच्या संस्थेच्या वेबहूक सीक्रेटने स्वाक्षरीत असते, त्यामुळे ती तुमची स्वाक्षरी पडताळणी देखील तपासते: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 आणि X-ThunderPhone-Signature. body JSON म्हणून पाठवला जातो आणि पाठविल्याप्रमाणे त्यावर स्वाक्षरी केली जाते; GET सह, आर्ग्युमेंट्स URL मध्ये ठेवा. चाचणीला कोणताही कॉल नसल्यामुळे कॉलचे फोन क्रमांक पाठवले जात नाहीत.

ही चाचणी 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-V2: t=<unix seconds>,v1=<HMAC-SHA256 hex>
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.

Zeus मध्ये, दीर्घ कॉल ट्रान्सक्रिप्टमध्ये आता कॉलची सुरुवात आणि शेवट समाविष्ट असतो. गरजेनुसार मधला भाग पृष्ठांमध्ये विभागला जातो, त्यामुळे कॉल कसा संपला हे तुम्ही तरीही पाहू शकता.

कॉल सूची आणि विश्लेषण पृष्ठांमध्ये, ThunderPhone आता चाचणी कॉल वास्तविक ट्रॅफिकपासून वेगळे दाखवते. Browser Talk चाचण्या आणि सिम्युलेशनमध्ये वास्तविक फोन नंबर पुन्हा वापरला जाऊ शकतो आणि ते इनबाउंडसारखे दिसू शकतात, परंतु ते उत्पादन कॉलची एकूण संख्या, ग्रेड किंवा समस्या मेट्रिक्समध्ये गणले जात नाहीत.

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

एजंट टूलला कधीही कॉल करत नाही

LLM टूलच्या वर्णनाच्या आधारे निर्णय घेतो. कॉलरचा प्रश्न वर्णनाशी जुळत नसल्यास, मॉडेल टूल सुरू करणार नाही. वर्णन अधिक नेमके करा (सामान्य समानार्थी शब्द आणि वाक्यरचना जोडा) किंवा एजंटच्या prompt मध्ये त्याचा स्पष्ट उल्लेख करा ("कॉलरने हवामानाबद्दल विचारल्यास, get_weather वापरा.").

साधन खूप जास्त डेटा परत करते

साधनाचा परिणाम संभाषणात राहतो आणि एजंट तो प्रत्येक पुढील फेरीत पुन्हा वाचतो, त्यामुळे मोठा परिणाम उर्वरित कॉलचा खर्च आणि विलंब वाढवतो. 100,000 वर्णांपेक्षा मोठा परिणाम पूर्वावलोकनापुरता मर्यादित केला जातो आणि एजंटला तो अपूर्ण असल्याचे सांगितले जाते. खूप लांब कॉलमध्ये, जुन्या साधनांचे परिणाम एजंटच्या स्मृतीतून वगळले जाऊ शकतात; त्यांची गरज असल्यास तो साधनाला पुन्हा कॉल करू शकतो.

परिणाम लहान ठेवण्यासाठी:

  • एजंटला आवश्यक असलेलीच फील्ड परत करा, संपूर्ण रेकॉर्ड नाही.
  • सर्वकाही एकाच वेळी मिळवण्याऐवजी एजंटला एकावेळी एक आयटम किंवा श्रेणी शोधता यावी यासाठी पॅरामीटर जोडा.
  • मोठी संदर्भ सामग्री (मेनू, कॅटलॉग, धोरणे) त्याऐवजी ज्ञान बेसमध्ये ठेवा.

डॅशबोर्डमधील चाचणी विनंती पाठवा परिणामाचा आकार दाखवते आणि तो मोठा असल्यास चेतावणी देते.

टाइमआउट

टूल एंडपॉइंट्ससाठी डीफॉल्ट टाइमआउट 20 सेकंदांचा असतो. जास्तीत जास्त 180 सेकंदांना अनुमती देण्यासाठी spec.timeout सेट करा (टूल्स पहा). व्यक्तीची किंवा धीम्या जॉबची वाट पाहणाऱ्या टूलसाठी spec.wait_mode "hold" वर सेट करा: कॉलरला बोलून दिलेल्या अद्यतनांऐवजी होल्ड संगीत ऐकू येते आणि spec.timeout 600 सेकंदांपर्यंत जाऊ शकतो. तुमचा एंडपॉइंट तरीही 180 सेकंदांच्या आत प्रतिसाद देतो; जास्त वेळ प्रतीक्षा करण्यासाठी {"status": "pending", "request_id": "..."} त्वरित परत करा आणि नंतर परिणाम POST /v1/calls/{call_id}/tool-results वापरून वितरित करा. दीर्घ प्रतीक्षा पहा.

आवृत्तीकरण

प्रत्येक इंटिग्रेशन PATCH नवीन रिव्हिजन तयार करते. कोणी काय बदलले ते पाहण्यासाठी GET /v1/integrations/{id}/versions तपासा. तुम्ही टूलचा schema बिघडवल्यास, जुना स्नॅपशॉट परत PATCH करून तुम्ही तो मॅन्युअली रोल बॅक करू शकता.


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