कस्टम टूल और फ़ंक्शन कॉलिंग

कस्टम टूल (जिसे फ़ंक्शन भी कहते हैं) से AI चैट के दौरान कोई छोटा काम चला सकता है। यह काम कोई तय टेक्स्ट लौटाना, किसी वेब पते को कॉल करना, या सर्वर पर छोटी सी स्क्रिप्ट चलाना हो सकता है। जब आप चाहते हैं कि AI अंदाज़ा लगाने के बजाय कुछ देखे या कोई गणना करे, तब इसे इस्तेमाल करें।

फ़ंक्शन कॉलिंग का मतलब है कि AI ऐप से कोई काम चलाने को कहता है और फिर उसका नतीजा अपने जवाब में इस्तेमाल करता है। Marinara में कुछ बिल्ट-इन टूल पहले से आते हैं, जैसे डाइस रोल, लोरबुक सर्च और गेम स्टेट अपडेट। आपके कस्टम टूल उन्हीं के साथ काम करते हैं। कस्टम टूल कैरेक्टर कार्ड से नहीं जुड़ता। आप इसे किसी चैट के लिए चालू करते हैं, या किसी एजेंट (आपकी चैट के साथ चलने वाला मददगार) से जोड़ते हैं।

Note: टूल के लिए ऐसा कनेक्शन चाहिए जो उन्हें सपोर्ट करे। Claude और Grok के सब्सक्रिप्शन कनेक्शन टूल डेफ़िनिशन को अनदेखा करते हैं, इसलिए Chat Settings (चैट सेटिंग्स) एक सूचना दिखाता है और उनके लिए टूल कंट्रोल बंद कर देता है। टेक्स्ट कमांड और डाइस टैग फिर भी काम करते हैं।

टूल बनाएँ

शुरू करने से पहले ऊपर की पट्टी से Presets (प्रीसेट) पैनल खोलें। टूल इसके Functions (फ़ंक्शन) सेक्शन में रहते हैं (रिंच आइकन)। अगर आप Marinara किसी दूसरे डिवाइस से खोलते हैं, तो पहले Settings → Advanced → Admin Access (सेटिंग्स → एडवांस्ड → एडमिन एक्सेस) में एडमिन सीक्रेट सेव करें। यह सर्वर के ADMIN_SECRET से मेल खाना चाहिए; देखें सर्वर कॉन्फ़िगरेशन रेफ़रेंस।

पहली बार आज़माने के लिए Static Result चुनें: इसके लिए और कुछ नहीं चाहिए।

टूल बनाना

1. Presets खोलें और Functions ढूँढें।
2. Create function (प्लस आइकन) पर क्लिक करें। खाली टूल एडिटर खुल जाता है।
3. छोटे अक्षरों वाला snake_case नाम टाइप करें, जैसे check_weather। AI ठीक इसी नाम से टूल को कॉल करता है। नाम छोटे अक्षर से शुरू होता है, फिर उसमें छोटे अक्षर, अंक और अंडरस्कोर आते हैं।
4. Description भरें। इसे AI के लिए एक निर्देश की तरह लिखें, क्योंकि AI इसी को पढ़कर तय करता है कि टूल कब कॉल करना है। उदाहरण: Get the current weather for a city the user names.
5. टूल को जो भी पैरामीटर चाहिए, वे जोड़ें (पैरामीटर जोड़ें देखें)।
6. Execution Type चुनें: Static Result, Webhook या Script।
7. उस टाइप का फ़ील्ड भरें (एक्ज़ीक्यूशन टाइप चुनें देखें)।
8. Save पर क्लिक करें। बटन के पास हरे रंग में Saved चमकता है।

नाम और विवरण के नियम:

• नाम 1 से 100 वर्ण का होता है। विवरण 1 से 500 वर्ण का होता है।
• दो टूल का नाम एक जैसा नहीं हो सकता, और कोई टूल बिल्ट-इन नाम इस्तेमाल नहीं कर सकता, जैसे roll_dice, update_game_state, set_expression, trigger_event, search_lorebook, web_search या update_about_me। नाम टकराने पर "your_name" is a reserved built-in tool name. जैसा संदेश दिखता है।
• बिना सेव किए बदलावों के साथ एडिटर से बाहर निकलने पर एक बैनर Keep editing, Discard या Save & close के विकल्प देता है।

Functions हेडर में तीन आइकन बटन हैं:

• Create function (प्लस आइकन)
• Import functions from ZIP or JSON
• Export functions to ZIP (एक भी टूल न होने पर ग्रे रहता है)

लिस्ट में हर टूल पर यह दिखता है:

• उसका नाम, टाइप, पैरामीटर की संख्या और विवरण
• चालू/बंद स्विच
• Edit function और Delete Function

लिस्ट का क्रम बदलने के लिए किसी टूल को उसके हैंडल से खींचें। यह क्रम सिर्फ़ दिखाने के लिए है। एक भी टूल न हो तो लिस्ट में No functions yet लिखा रहता है।

पैरामीटर जोड़ें

पैरामीटर वे इनपुट हैं जो AI आपके टूल को कॉल करते समय भेजता है। हर पैरामीटर का एक नाम, एक टाइप, ज़रूरी होने का एक फ़्लैग और एक विवरण होता है।

1. Parameters ग्रुप में Add Parameter पर क्लिक करें।
2. नाम टाइप करें, जैसे city।
3. टाइप चुनें: string, number, boolean, array या object।
4. अगर AI को यह वैल्यू हमेशा भेजनी ही है, तो Required चालू करें।
5. ऐसा विवरण लिखें जो AI को बताए कि इस वैल्यू का मतलब क्या है, जैसे The city name to look up, such as Tokyo.

Add Parameter से और पंक्तियाँ जोड़ें, या माइनस बटन से कोई पंक्ति हटाएँ। जिस पंक्ति का नाम खाली हो, वह सेव करते समय हट जाती है।

अगर AI किसी इंपोर्ट किए टूल को कभी कॉल करता न दिखे, तो हो सकता है उसके पैरामीटर गलत हों, और तब ऐप आपको बताए बिना उस टूल को छोड़ देता है। पैरामीटर डिलीट करें और उन्हें हाथ से दोबारा जोड़ें।

एक्ज़ीक्यूशन टाइप चुनें

Static Result

Static Result टूल हर बार वही टेक्स्ट लौटाता है। इसके लिए किसी बाहरी सेवा की ज़रूरत नहीं होती। इसके कार्ड पर लिखा रहता है: Returns a fixed string when called.

इसका इकलौता फ़ील्ड है Static Result, यानी कई पंक्तियों वाला बॉक्स। खाली छोड़ने पर टूल OK लौटाता है।

उदाहरण: store_hours नाम का टूल, जिसमें कोई पैरामीटर नहीं है और Static Result यह है:

We are open Monday to Friday, 9am to 5pm. We are closed on weekends.

AI जब store_hours कॉल करता है, तो उसे यह टेक्स्ट टूल के नाम और भेजे गए आर्ग्युमेंट के साथ मिलता है, और वह यूज़र को आपका समय बता सकता है।

Webhook

Webhook टूल कॉल को किसी वेब पते पर भेजता है और उस सेवा का जवाब AI को लौटा देता है। वेबहुक यानी ऐसा पता जो डेटा लेता है और बदले में डेटा भेजता है। इसके कार्ड पर लिखा रहता है: Sends a POST request to an external URL.

इसका इकलौता फ़ील्ड है Webhook URL। ऐप POST रिक्वेस्ट भेजता है, जो किसी वेब सेवा को डेटा भेजने का एक तरीका है। बॉडी JSON में होती है, यानी संरचित डेटा का सादा टेक्स्ट फ़ॉर्मैट, और उसका ढाँचा ऐसा रहता है:

{ "tool": "your_tool_name", "arguments": { ... } }

अगर आप Include hidden chat context चालू करते हैं, तो बॉडी में एक context वैल्यू भी होती है। सेवा JSON या सादे टेक्स्ट में जवाब देती है, और वह जवाब AI को वापस जाता है।

उदाहरण: check_weather नाम का टूल, जिसमें एक ज़रूरी string पैरामीटर city है, और Webhook URL यह है:

https://api.example.com/weather

AI जब city को Tokyo पर सेट करके इसे कॉल करता है, तो आपकी सेवा मौसम देखकर जवाब देती है, और AI वह जवाब अपने संदेश में इस्तेमाल करता है।

सीमाएँ:

• जवाब की सीमा 512 KB है।
• हर कॉल की एक समय सीमा होती है। डिफ़ॉल्ट 60 सेकंड है (CUSTOM_TOOL_TIMEOUT_MS)।
• डिफ़ॉल्ट रूप से सिर्फ़ https:// वाले पते चलते हैं। प्राइवेट और लोकल पते, जैसे localhost या घर के नेटवर्क का पता, तब तक ब्लॉक रहते हैं जब तक सर्वर एडमिन उनकी इजाज़त न दे। देखें सर्वर कॉन्फ़िगरेशन रेफ़रेंस।
• कॉल फ़ेल हो जाए या टाइमआउट हो जाए, तो AI को एरर वाला नतीजा मिलता है और चैट चलती रहती है।

अगर यह काम न करे: जाँचें कि पता https:// से शुरू होता है और वहाँ पहुँचा जा सकता है। लोकल पता तब तक ब्लॉक रहता है जब तक एडमिन उसकी इजाज़त न दे। धीमी सेवा 60 सेकंड की सीमा से टकरा सकती है।

Script

Script टूल सर्वर पर JavaScript का छोटा टुकड़ा चलाता है और उसका नतीजा लौटाता है। JavaScript एक आम प्रोग्रामिंग भाषा है। इसके कार्ड पर लिखा रहता है: Runs a JavaScript expression server-side.

स्क्रिप्ट टूल डिफ़ॉल्ट रूप से बंद रहते हैं। आपके सर्वर पर ये चालू न हों, तो Script कार्ड ग्रे दिखता है और एम्बर रंग की Script disabled पिल दिखती है। इन्हें चालू करने के लिए सर्वर एडमिन सर्वर की .env फ़ाइल में यह लाइन जोड़ता है और Marinara को रीस्टार्ट करता है:

CUSTOM_TOOL_SCRIPT_ENABLED=true

इसका इकलौता फ़ील्ड है Script Body। स्क्रिप्ट args (AI की भेजी हुई वैल्यू) पढ़ती है और उसे नतीजा return करना ज़रूरी है। JSON, Math और Date उपलब्ध हैं।

उदाहरण: add_numbers नाम का टूल, जिसमें x और y नाम के दो ज़रूरी number पैरामीटर हैं, और Script Body यह है:

const result = args.x + args.y;
return { sum: result };

AI जब x को 2 और y को 3 पर सेट करके इसे कॉल करता है, तो टूल 5 का जोड़ लौटाता है। स्क्रिप्ट एरर दे, तो AI को एरर वाला नतीजा मिलता है।

स्क्रिप्ट आपके सर्वर पर असली कोड चलाती है, एक सैंडबॉक्स (घेराबंद जगह, जो कोड के काम सीमित रखती है) के अंदर:

• नेटवर्क तक पहुँच नहीं और फ़ाइल तक पहुँच नहीं।
• एनवायरनमेंट वेरिएबल और सर्वर के सीक्रेट तक पहुँच नहीं।
• समय सीमा। डिफ़ॉल्ट 60 सेकंड है।

सैंडबॉक्स पूरे ऑपरेटिंग सिस्टम के स्तर का अलगाव नहीं है। जो व्यक्ति टूल बना सकता है, वह फिर भी ऐसी स्क्रिप्ट लिख सकता है जो CPU या मेमोरी बरबाद करे। स्क्रिप्ट टूल सिर्फ़ उन्हीं सर्वर पर चालू करें जिन पर आपको भरोसा है, और दूसरों की लिखी स्क्रिप्ट के साथ सावधानी बरतें।

अगर यह काम न करे: Script कार्ड ग्रे दिखे, तो एडमिन से CUSTOM_TOOL_SCRIPT_ENABLED=true सेट करके रीस्टार्ट करने को कहें।

Include hidden chat context

Webhook और Script टूल चैट का ऐसा अतिरिक्त डेटा पा सकते हैं जो AI को टूल के इनपुट के रूप में नहीं दिखता। टूल एडिटर में Include hidden chat context चालू करें (डिफ़ॉल्ट रूप से बंद)। तब आपके टूल को एक context वैल्यू मिलती है, जिसमें ये चीज़ें हो सकती हैं:

• चैट का मोड
• चालू पर्सोना का नाम और कैरेक्टर के नाम
• सेव किए गए चैट वेरिएबल
• Game Mode में, गेम स्टेट

इससे टूल अपना नतीजा हालात के हिसाब से ढाल सकता है, और AI को यह सारा डेटा भेजना नहीं पड़ता।

किसी चैट के लिए टूल चालू करें

टूल बना देने भर से AI उसे इस्तेमाल नहीं करता। आपको चैट के लिए भी टूल इस्तेमाल चालू करना होता है।

1. कोई चैट खोलें, फिर Chat Settings खोलें।
2. Function Calling (फ़ंक्शन कॉलिंग) सेक्शन खोलें (रिंच आइकन)।
3. Enable Tool Use चालू करें। इसका विवरण है: Allow AI to call functions (dice rolls, game state, etc.)। नई चैट में यह डिफ़ॉल्ट रूप से बंद रहता है।
4. जाँचें कि यह काम करता है: AI से ऐसा कुछ पूछें जिसका जवाब आपका टूल देता है, जैसे store_hours वाले उदाहरण के लिए "What are your store hours?"। जवाब में टूल का टेक्स्ट इस्तेमाल होना चाहिए।

Enable Tool Use चालू हो और उसके नीचे कुछ न जोड़ा गया हो, तो चैट हर उस ग्लोबल रूप से चालू टूल को इस्तेमाल कर सकती है जिसे वह सपोर्ट करती है: बिल्ट-इन टूल, और हर वह कस्टम टूल जिसका स्विच Functions में चालू है। Game चैट में search_lorebook के लिए Let the GM search lore (GM को लोर खोजने दें) भी चाहिए।

चैट को चुने हुए टूल तक सीमित रखने के लिए:

1. Add Functions पर क्लिक करें। एक पिकर खुलता है, जिसका सर्च बॉक्स सिर्फ़ टूल के नाम से मिलान करता है।
2. जो टूल चाहिए, उन्हें चेक करें। लिस्ट में बिल्ट-इन और कस्टम टूल मिले-जुले रहते हैं।
3. Add Selected पर क्लिक करें।

कोई भी टूल जोड़ने के बाद उस चैट में सिर्फ़ वही टूल चलते हैं। पिकर में New Custom Function सीधे टूल एडिटर पर ले जाता है।

Game चैट टूल प्लानिंग के लिए अलग कनेक्शन इस्तेमाल कर सकती हैं। उसकी लागत और व्यवहार के लिए वैकल्पिक टूल प्लानिंग और लोर खोज देखें।

अगर यह काम न करे: पक्का करें कि Enable Tool Use चालू है, अगर आपने खास टूल जोड़े हैं तो टूल चैट की लिस्ट में है, और Functions में टूल का स्विच चालू है। साफ़ Description और पैरामीटर के साफ़ विवरण से AI को यह तय करने में मदद मिलती है कि टूल कब कॉल करना है।

एजेंट से टूल जोड़ें

टूल किसी चैट के बजाय किसी एजेंट को भी दिया जा सकता है।

1. Agents (एजेंट) पैनल खोलें और कोई एजेंट खोलें।
2. उसका Tools / Function Calling ग्रुप खोलें।
3. वे टूल चालू करें जिन्हें वह एजेंट इस्तेमाल कर सकता है।

फिर भी आपको चैट के Function Calling सेक्शन में Enable Tool Use चालू करना होता है। एजेंट एडिटर का फ़ुटर आपको यह याद दिलाता है। एजेंट के बारे में आम जानकारी के लिए कस्टम एजेंट बनाना देखें।

टूल एक्सपोर्ट और इंपोर्ट करें

• कोई एक टूल एक्सपोर्ट करने के लिए उसे खोलें और Export function पर क्लिक करें। इससे एक .json फ़ाइल सेव होती है।
• सारे टूल एक्सपोर्ट करने के लिए Export functions to ZIP पर क्लिक करें।
• इंपोर्ट करने के लिए Import functions from ZIP or JSON पर क्लिक करें और कोई .json या .zip फ़ाइल चुनें। एक संदेश बताता है कि कितने टूल इंपोर्ट हुए।

इंपोर्ट किए गए वेबहुक और स्क्रिप्ट टूल हमेशा बंद हालत में और Include hidden chat context बंद रखकर सेव होते हैं, भले ही फ़ाइल इनमें से कुछ भी माँगे। फिर Marinara टाइप, वेबहुक का पता और फ़ाइल की माँगी हुई परमिशन दिखाता है। इंपोर्ट किए गए हर टूल को खोलकर जाँचें, और उसे तभी चालू करें जब उस पर भरोसा हो। Static टूल इंपोर्ट के समय वाली चालू/बंद हालत बनाए रखते हैं।

इंपोर्ट के दौरान वह हर टूल छोड़ दिया जाता है जिसका नाम किसी मौजूदा या बिल्ट-इन टूल से टकराता है। एजेंट पैकेज में कस्टम टूल साथ नहीं आते: उन्हें अलग से एक्सपोर्ट करके जाँचें, फिर एजेंट इंपोर्ट करने के बाद उन्हें जोड़ें।

मिलती-जुलती गाइड

• कस्टम एजेंट बनाना
• Home Assistant इंटीग्रेशन
• सर्वर कॉन्फ़िगरेशन रेफ़रेंस