API

कस्टम tools

AI को बातचीत के बीच में आपकी API call करने दें

परिचय

कस्टम tool आपका एक endpoint है जिसे एजेंट ग्राहक से बात करते हुए call कर सकता है: ID नंबर से लोन देखना, स्टॉक चेक करना, टिकट खोलना। आप बताते हैं कि यह कब लागू होता है और इसे कौन-से parameters चाहिए; AI तय करता है कि इसे कब call करना है, ग्राहक की कही बातों से parameters भरता है और आपकी API के लौटाए नतीजे से जवाब देता है। हर एजेंट के लिए 15 tools तक।

परिभाषा

हर tool इन फ़ील्ड्स वाली एक entry है:

`name`	वह तकनीकी नाम जिससे AI इसे call करता है: अक्षर, अंक और underscore (consultar_credito)।
`description`	इसे कब इस्तेमाल करें और यह क्या लौटाता है। AI फ़ैसला लेने के लिए यही पढ़ता है; इसे निर्देश की तरह लिखें (“ID नंबर से लोन देखता है; बैलेंस और किस्तें लौटाता है”)।
`parameters`	{name, type (string \| number \| boolean \| enum), description, required, enum_values} की लिस्ट। AI इन्हें ग्राहक की कही बातों से भरता है।
`method + endpoint`	GET, POST, PUT या DELETE और पूरा URL।
`auth`	NONE, BEARER (Authorization: Bearer <token>), API_KEY (header का नाम और value जो आप चुनें) या BASIC (यूज़रनेम और पासवर्ड)।
`headers`	हर call में जाने वाले अतिरिक्त headers।
`body_template`	{{param}} वाला वैकल्पिक JSON टेम्पलेट। इसके बिना POST/PUT parameters को JSON ऑब्जेक्ट की तरह भेजते हैं।
`response_path`	Response के उस हिस्से तक का वैकल्पिक dotted path (data.results) जिसे AI को पढ़ना है।

Call कैसे होती है

GET और DELETE parameters को URL में query string की तरह जोड़ते हैं। POST और PUT उन्हें JSON body में भेजते हैं: या फिर भरा हुआ body_template। Auth headers और अतिरिक्त headers हर call में जाते हैं। JSON के साथ 2xx से जवाब दें: AI body (या response_path वाला हिस्सा) टेक्स्ट की तरह पाता है और उससे जवाब देता है। 2xx से अलग कोड AI तक “API returned <status>” के रूप में पहुँचता है और वह ग्राहक को बताता है कि जानकारी नहीं मिल पाई; अपने-आप कोई retry नहीं होता।

इसे कैसे बनाएँ

Canvas (newui.tbit.app): पूछें “मेरे पास कौन-से कस्टम tools हैं?” → लिस्ट में “नया tool…” होता है; हर पंक्ति Edit से tool खोलती है। एक फ़ॉर्म ऊपर की सारी जानकारी पूछता है; एडिट करते समय जो secrets आप खाली छोड़ते हैं, वे वैसे ही रहते हैं।
MCP (Claude, ChatGPT…): पढ़ने के लिए list_custom_tools, और action=create | update | delete के साथ manage_custom_tool। बदलाव का प्रस्ताव आता है और आप उसे कन्फ़र्म करते हैं।
प्लेटफ़ॉर्म ऐप: Integrations → Custom API।

उदाहरण: MCP से बनाएँ

json

manage_custom_tool
{
  "action": "create",
  "name": "consultar_credito",
  "description": "Consulta el estado de un crédito por número de cédula; devuelve saldo, cuotas pendientes y próxima fecha de pago.",
  "method": "GET",
  "endpoint": "https://api.tunegocio.com/v1/creditos",
  "parameters": [
    { "name": "cedula", "type": "string", "description": "Cédula del cliente, solo dígitos", "required": true }
  ],
  "auth_type": "BEARER",
  "auth_token": "<tu token>",
  "response_path": "data"
}

आपके endpoint को क्या मिलता है

ऊपर के उदाहरण में, जब कोई ग्राहक अपने लोन के बारे में पूछता है तो AI यह call करता है:

http

GET https://api.tunegocio.com/v1/creditos?cedula=1032456789
Authorization: Bearer <tu token>
Accept: application/json

→ 200 { "data": { "saldo": 1250000, "cuotas_pendientes": 3, "proximo_pago": "2026-10-05" } }

अच्छे तरीके

विवरण AI के लिए लिखें, डेवलपर के लिए नहीं: इसे कब इस्तेमाल करें और क्या वापस आता है।
सिर्फ़ वही ज़रूरी (required) मार्क करें जो AI को ग्राहक से पूछना ही है; बाकी के लिए अपनी तरफ़ एक default value रखें।
GET calls को idempotent रखें: अगर पहली कोशिश फ़ेल हो जाए तो AI एक ही बातचीत में वही tool दो बार call कर सकता है।
छोटा और सपाट JSON लौटाएँ। अगर आपकी API नतीजों को किसी wrapper में लपेटती है तो response_path इस्तेमाल करें।