GPT-5 फ़ंक्शन कॉलिंग ट्यूटोरियल

GPT-5 की लॉन्चिंग के साथ, OpenAI ने API में टूल/फ़ंक्शन कॉलिंग का विस्तार करके फ्री-फॉर्म टूल कॉल्स (रॉ टेक्स्ट, बिना JSON), Lark/CFG के जरिए ग्रामर बाधाएँ, टूल अलौलिस्ट्स, और बेहतर टूल-यूज़ रीज़निंग शामिल की है। ये सब मिलकर GPT-5 को वाकई एजेंटिक मॉडल बनाते हैं; आप Responses API से APIs, डेटाबेस, और कस्टम टूल्स जोड़ सकते हैं और ग्राउंडेड उत्तर जनरेट कर सकते हैं या वर्कफ़्लो तक ऑटोमेट कर सकते हैं।

इस ट्यूटोरियल में, मैं फ़ंक्शन टूल्स, कस्टम टूल्स, ग्रामर बाधाएँ, टूल अलौलिस्ट्स, और प्रीऐम्बल्स कवर करूंगा, साथ ही कोड उदाहरण और यह स्पष्ट समझ भी दूंगा कि वे कैसे काम करते हैं और कब उपयोग करें।

GPT-5 में फ़ंक्शन कॉलिंग: क्या और क्यों

GPT-5 में फ़ंक्शन कॉलिंग आपको मॉडल को आपकी एप्लिकेशन के डेटा और ऐक्शंस से संवर्धित करने देती है। मॉडल यह निर्धारित कर सकता है कि कब किसी टूल को कॉल करना है, जबकि आप लॉजिक संभालते हैं और अंतिम, ग्राउंडेड प्रतिक्रिया के लिए परिणाम लौटाते हैं। 

फ़ंक्शन कॉलिंग के प्रकार:

1. फ़ंक्शन टूल्स (JSON Schema): ये सटीक कॉलिंग के लिए स्ट्रक्चर्ड इनपुट और आउटपुट प्रदान करते हैं।
2. कस्टम टूल्स (फ्री-फॉर्म): ये अनस्ट्रक्चर्ड इंटीग्रेशन के लिए लचीले टेक्स्ट इनपुट और आउटपुट देते हैं।

फ़ंक्शन कॉलिंग क्या है?

GPT-5, JSON Schema आधारित स्ट्रक्चर्ड फ़ंक्शन टूल्स और कस्टम टूल्स दोनों का समर्थन करता है, जो फ्री-फॉर्म टेक्स्ट पेलोड्स (जैसे SQL, स्क्रिप्ट्स, या कॉन्फ़िगरेशन) स्वीकार करते हैं, ताकि बाहरी रनटाइम्स के साथ सहज एकीकरण हो सके। 

फ़ंक्शन टूल्स JSON Schema द्वारा परिभाषित होते हैं, जो सुनिश्चित करता है कि मॉडल को ठीक-ठीक पता हो कि कौन से आर्ग्युमेंट्स पास करने हैं और कड़े इनपुट वैलिडेशन की अनुमति देता है। आप हमारी OpenAI Function Calling ट्यूटोरियल में और पढ़ सकते हैं।

फ़ंक्शन कॉलिंग का उपयोग क्यों करें?

• लचीलापन: फ्री-फॉर्म टूल्स मॉडल को वही सटीक टेक्स्ट उत्पन्न करने देते हैं जिसकी आपके सिस्टम को आवश्यकता है, कठोर JSON की पाबंदियों के बिना—कोड, क्वेरीज़ या कॉन्फ़िगरेशन के लिए आदर्श।
• विश्वसनीयता और नियंत्रण: फ़ंक्शन टूल्स स्ट्रक्चर्ड आर्ग्युमेंट्स को लागू करते हैं, जो अनुमान-योग्यता बढ़ाते हैं और पार्सिंग त्रुटियों को घटाते हैं।
• एजेंटिक वर्कफ़्लोज़: GPT-5 जटिल, बहु-चरणीय टूल उपयोग और कोडिंग कार्यों के लिए डिज़ाइन किया गया है, जिससे टूल कॉलिंग एक प्राथमिक फीचर बनती है।

फ़ंक्शन कॉलिंग कैसे काम करती है?

1. एक प्रॉम्प्ट भेजें जिसमें सभी उपलब्ध टूल्स शामिल हों।
2. मॉडल एक टूल कॉल जारी करता है (या तो आर्ग्युमेंट्स के साथ या फ्री-फॉर्म टेक्स्ट के साथ)।
3. आपका एप्लिकेशन टूल निष्पादित करता है (Python फ़ंक्शन चलाएँ)।
4. टूल से आउटपुट मॉडल को लौटाएँ।
5. फिर मॉडल प्रतिक्रिया देता है या अतिरिक्त टूल्स कॉल कर सकता है।

स्रोत: Function calling - OpenAI API

फ़ंक्शन बनाम कस्टम टूल्स कब उपयोग करें

• फ़ंक्शन टूल्स का उपयोग करें जब आप JSON Schema के जरिए सख्त वैलिडेशन और अनुमान-योग्य, टाइप्ड आर्ग्युमेंट्स चाहते हैं।
• कस्टम टूल्स (फ्री-फॉर्म) का उपयोग करें जब आपका रनटाइम रॉ टेक्स्ट मांगता हो (जैसे स्क्रिप्ट्स, SQL, या कॉन्फ़िगरेशन) या जब आपको स्कीमा के बिना तेज़ इटरेशन चाहिए।

फ़ंक्शन टूल्स (JSON Schema): स्ट्रक्चर्ड डेटा भेजें

JSON Schema के साथ फ़ंक्शन टूल्स का उपयोग करने से आप मॉडल से अनुमान-योग्य और स्ट्रक्चर्ड परिणाम प्राप्त कर सकते हैं। मॉडल आपके घोषित टूल्स का मूल्यांकन करता है, तय करता है कब किसका उपयोग करना है, JSON-वैलिडेटेड आर्ग्युमेंट्स प्रस्तावित करता है, और फिर आपके कोड में संबंधित फ़ंक्शन चलाता है। 

इसके बाद, आप मॉडल से केवल टूल द्वारा लौटाए गए डेटा के आधार पर प्रतिक्रिया बनाने के लिए कह सकते हैं, जिससे आउटपुट ग्राउंडेड, मशीन-रीडेबल और एकीकृत करना आसान बनता है।

यह उदाहरण कई प्रमुख अवधारणाओं को दर्शाता है:

• टूल डिस्कवरी और आर्ग्युमेंट जनरेशन: मॉडल उपयुक्त टूल चुनता है और उसके JSON-टाइप्ड आर्ग्युमेंट्स स्वतः भरता है।
• टूल निष्पादन लूप: आपका एप्लिकेशन अनुरोधित टूल(s) चलाता है और परिणाम मॉडल को वापस भेजता है।
• स्कीमा-आकारित अंतिम उत्तर: अंतिम प्रतिक्रिया केवल टूल्स के आउटपुट पर आधारित होती है, जो त्रुटियों को कम करती है और विश्वसनीयता सुनिश्चित करती है।

1. सेटअप

1. OpenAI खाता बनाएँ और प्लेटफ़ॉर्म डैशबोर्ड पर एक API कुंजी जनरेट करें। डैशबोर्ड में API सेक्शन खोलें, फिर “View API keys” पर जाएँ, और “Create new secret key” पर क्लिक करें।
2. अपने खाते में भुगतान विधि या क्रेडिट्स जोड़ें ताकि API कॉल्स चल सकें; उपयोग के साथ आपकी प्रीपेड बैलेंस से कटौती होती जाएगी।
3. अपनी ऐप शुरू करने से पहले अपनी API कुंजी को OPENAI_API_KEY नाम के एन्वायरनमेंट वेरिएबल के रूप में सेव करें। 
4. आधिकारिक OpenAI Python SDK इंस्टॉल करें: pip install openai.

2. टूल्स परिभाषित करें

आप टूल्स की सूची देते हैं—नाम, विवरण, और पैरामीटर्स के लिए JSON Schema के साथ। स्कीमा मॉडल को सुव्यवस्थित आर्ग्युमेंट्स सप्लाई करने में मदद करता है।

• make_coffee एक स्ट्रिंग पैरामीटर अपेक्षित करता है: coffee_type।
• random_coffee_fact को कोई पैरामीटर नहीं चाहिए (खाली ऑब्जेक्ट)। ये परिभाषाएँ API कॉल में tools आर्ग्युमेंट के जरिए भेजी जाती हैं ताकि मॉडल को पता हो कि क्या उपलब्ध है।

import os
from openai import OpenAI
import json

client = OpenAI(api_key = os.environ["OPENAI_API_KEY"])

tools = [
    {
        "type": "function",
        "name": "make_coffee",
        "description": "Gives a simple recipe for making a coffee drink.",
        "parameters": {
            "type": "object",
            "properties": {
                "coffee_type": {
                    "type": "string",
                    "description": "The coffee drink, e.g. espresso, cappuccino, latte"
                }
            },
            "required": ["coffee_type"],
        },
    },
    {
        "type": "function",
        "name": "random_coffee_fact",
        "description": "Returns a fun fact about coffee.",
        "parameters": {"type": "object","properties":{}}
    }
]
संचालित द्वारा

3. टूल्स इम्प्लिमेंट करें

आप वे Python फ़ंक्शंस इम्प्लिमेंट करते हैं जो वास्तविक काम करते हैं:

• make_coffee(coffee_type) अनुरोधित ड्रिंक के अनुसार एक संक्षिप्त रेसिपी स्ट्रिंग लौटाता है।
• random_coffee_fact() एक छोटा-सा तथ्य पेलोड लौटाता है। 

दोनों JSON-सीरियलाईज़ेबल डिक्ट्स लौटाते हैं, जो मॉडल को वापस फीड करने के लिए उपयुक्त हैं।

def make_coffee(coffee_type):
    recipes = {
        "espresso": "Grind fine, 18g coffee → 36g espresso in ~28s.",
        "cappuccino": "Brew 1 espresso shot, steam 150ml milk, pour and top with foam.",
        "latte": "Brew 1 espresso shot, steam 250ml milk, pour for silky texture.",
    }
    return {"coffee_type": coffee_type, "recipe": recipes.get(coffee_type.lower(), "Unknown coffee type!")}

def random_coffee_fact():
    return {"fact": "Coffee is the second most traded commodity in the world, after oil."}संचालित द्वारा

4. बातचीत शुरू करें

बातचीत उपयोगकर्ता के प्रश्न से प्रारंभ करें: {"role": "user", "content": "How do I make a latte?"}

मॉडल ऐसे संदेश लौटा सकता है जिसमें function_call आइटम शामिल हो, जैसे make_coffee के साथ {"coffee_type":"latte"}। फिर आपको मॉडल के संदेशों को वापस input_list: input_list += response.output में जोड़ना चाहिए। यह अगले टर्न के लिए बातचीत की स्टेट बनाए रखने में मदद करता है।

# Track used tools
used_tools = []

input_list = [{"role": "user", "content": "How do I make a latte?"}]

response = client.responses.create(
    model="gpt-5",
    tools=tools,
    input=input_list,
)
input_list += response.outputसंचालित द्वारा

5. टूल कॉल्स चलाएँ और आउटपुट संलग्न करें

आपको response.output पर इटररेट करना चाहिए और उन आइटम्स को पहचानना चाहिए जहाँ item.type "function_call" के बराबर हो। इन आइटम्स के लिए, item.arguments पार्स करें और अनुरोधों को अपने Python फ़ंक्शंस को डिस्पैच करें। 

make_coffee फ़ंक्शन के लिए, इसे make_coffee(args["coffee_type"]) से कॉल करें। random_coffee_fact फ़ंक्शन के लिए, बस random_coffee_fact() कॉल करें। 

फ़ंक्शंस चलाने के बाद, एक function_call_output संदेश जोड़ें जिसमें निम्न शामिल हों: 

• call_id (जो इस आउटपुट को मॉडल के अनुरोध से लिंक करता है) 
• output (आपके फ़ंक्शन परिणाम का JSON स्ट्रिंग)।

for item in response.output:
    if getattr(item, "type", "") == "function_call":
        used_tools.append(item.name)
        args = json.loads(item.arguments or "{}")

        if item.name == "make_coffee":
            result = make_coffee(args["coffee_type"])
        elif item.name == "random_coffee_fact":
            result = random_coffee_fact()
        else:
            result = {"error": f"Unknown tool {item.name}"}

        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(result)
        })संचालित द्वारा

6. अंतिम उत्तर जनरेट करें

आप एक दूसरी client.responses.create कॉल करते हैं, अपडेटेड input_list पास करते हुए, जिसमें अब टूल आउटपुट शामिल है।

used_tools वेरिएबल उन टूल्स के नाम कैप्चर करता है जो मॉडल के फ़ंक्शन कॉल्स में आए। हम इसका उपयोग दिखाने के लिए करेंगे कि कौन से टूल्स प्रयुक्त हुए। 

final = client.responses.create(
    model="gpt-5",
    tools=tools,
    input=input_list,
    instructions="Answer using only the tool results."
)

print("Final output:\n", final.output_text)

print("\n--- Tool Usage ---")
for t in tools:
    status = "USED ✅" if t["name"] in used_tools else "NOT USED ❌"
    print(f"{t['name']}: {status}")संचालित द्वारा

क्योंकि उपयोगकर्ता ने लाटे के बारे में पूछा था, मॉडल ने make_coffee को coffee_type = "latte" के साथ चुना, आपका कोड चला, और अंतिम प्रतिक्रिया केवल उसी टूल परिणाम से बनी।

Final output:
 {"coffee_type":"latte","recipe":"Brew 1 espresso shot, steam 250ml milk, pour for silky texture."}

--- Tool Usage ---
make_coffee: USED ✅
random_coffee_fact: NOT USED ❌संचालित द्वारा

कस्टम टूल्स (फ्री-फॉर्म): रॉ टेक्स्ट भेजें

GPT-5 के फ्री-फॉर्म कस्टम टूल्स का उपयोग करें ताकि मॉडल आपका रॉ टेक्स्ट सीधे टूल को भेज सके—जैसे कोड, SQL, शेल कमांड्स, या साधारण CSV—बिना JSON Schema की आवश्यकता के। 

यह क्षमता पुराने केवल-JSON फ़ंक्शन कॉल्स से आगे जाती है, और आपको एग्जीक्यूटर्स, क्वेरी इंजन, या डोमेन-स्पेसिफिक लैंग्वेज (DSL) इंटरप्रिटर्स के साथ इंटीग्रेशन के लिए अधिक लचीलापन देती है। 

फ्री-फॉर्म मोड में, मॉडल एक कस्टम टूल कॉल जनरेट करता है जिसमें अनस्ट्रक्चर्ड टेक्स्ट पेलोड होता है जिसे आप अपने रनटाइम तक रूट कर सकते हैं। फिर आप परिणाम लौटाते हैं ताकि मॉडल उपयोगकर्ता-उन्मुख उत्तर को अंतिम रूप दे सके।

अब हम वह कोड लिखेंगे जो मॉडल को उपयुक्त टूल्स चुनने में सक्षम बनाता है और आउटपुट के रूप में अनस्ट्रक्चर्ड रॉ टेक्स्ट लौटाता है। यह आउटपुट फिर एक Python फ़ंक्शन को पास किया जाएगा ताकि परिणाम जनरेट किया जा सके। इस तरह, उपयोगकर्ता अपने पास मौजूद सामग्री दे सकते हैं, और मॉडल उनकी ज़रूरतों के अनुरूप रेसिपीज़ बनाएगा।

इस उदाहरण कोड में, हमारे पास है:

1. OpenAI क्लाइंट को इनिशियलाइज़ किया और meal_planner नामक एकमात्र कस्टम टूल परिभाषित किया जो रॉ टेक्स्ट इनपुट स्वीकार करता है।
2. Python plan_meal बनाया जो सामग्री की कॉमा-सेपरेटेड स्ट्रिंग लेता है और एक भोजन का आइडिया लौटाता है।
3. बातचीत उपयोगकर्ता संदेश से शुरू की जिसमें उपलब्ध सामग्री सूचीबद्ध थी।
4. पहली मॉडल कॉल की, GPT-5 को केवल साफ-सुथी सामग्री सूची का उपयोग कर टूल बुलाने का निर्देश देते हुए, और मॉडल का आउटपुट बातचीत के इतिहास में जोड़ा।
5. इमिट किए गए कस्टम टूल कॉल का पता लगाया और रॉ कॉमा-सेपरेटेड इनपुट स्ट्रिंग निकाली।
6. सूची को plan_meal में पास करके टूल चलाया, फिर परिणाम को call_id से लिंक किए गए function_call_output के रूप में मॉडल को वापस भेज दिया।
7. अंतिम मॉडल कॉल की ताकि टूल के रॉ आइडिया को 3–4 चरणों वाली संक्षिप्त रेसिपी में बदला जा सके, और टूल कॉल विवरण तथा अंतिम आउटपुट प्रिंट किया।

from openai import OpenAI
import json
import random

client = OpenAI()

# --- Custom tool ---
tools = [
    {
        "type": "custom",
        "name": "meal_planner",
        "description": "Takes ONLY a comma-separated list of ingredients and suggests a meal idea."
    }
]

# --- Fake meal planner ---
def plan_meal(ingredients: str) -> str:
    ideas = [
        f"Stir-fry: {ingredients} with garlic & soy sauce.",
        f"One-pot rice: cook {ingredients} together in broth until fluffy.",
        f"Soup: simmer {ingredients} in stock with herbs.",
        f"Sheet-pan bake: roast {ingredients} at 200°C for ~20 min."
    ]
    return random.choice(ideas)

# --- Start conversation ---
messages = [
    {"role": "user", "content": "I only have chicken, rice, and broccoli. Any dinner ideas?"}
]

# 1) Ask model with clear instruction
resp = client.responses.create(
    model="gpt-5",
    tools=tools,
    input=messages,
    instructions="If the user mentions ingredients, call the meal_planner tool with ONLY a comma-separated list like 'chicken, rice, broccoli'."
)

messages += resp.output

# 2) Find the tool call
tool_call = next((x for x in resp.output if getattr(x, "type", "") == "custom_tool_call"), None)
assert tool_call, "No tool call found!"

# Get clean CSV input
ingredients_csv = tool_call.input.strip()

# 3) Run the tool
meal_result = plan_meal(ingredients_csv)

# 4) Send tool output back
messages.append({
    "type": "function_call_output",
    "call_id": tool_call.call_id,
    "output": meal_result
})

# 5) Final model response
final = client.responses.create(
    model="gpt-5",
    tools=tools,
    input=messages,
    instructions="Turn the meal idea into a short recipe with 3-4 steps."
)

print("\n--- Tool Call ---")
print("Name:", tool_call.name)
print("Input:", ingredients_csv)
print("Output:", meal_result)


print("\n--- Final Output ---\n", final.output_text)संचालित द्वारा

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

--- Tool Call ---
Name: meal_planner
Input: chicken, rice, broccoli
Output: One-pot rice: cook chicken, rice, broccoli together in broth until fluffy.

--- Final Output ---
 One-Pot Chicken, Rice & Broccoli

- Season bite-size chicken pieces with salt and pepper; sear in a little oil in a pot until lightly browned.
- Add 1 cup rinsed rice and 2 cups broth (or water + salt). Bring to a boil, then cover and simmer on low for 12 minutes.
- Scatter 2 cups small broccoli florets on top, cover, and cook 5-7 more minutes until rice is fluffy and broccoli is tender.
- Rest 5 minutes off heat, fluff, and adjust seasoning. Optional: stir in a knob of butter or a splash of soy.संचालित द्वारा

ग्रामर बाधाएँ (Lark): टूल आउटपुट को सीमित करें

अब GPT-5 आउटपुट फ़ॉर्मैट्स को सख्ती से नियंत्रित करने के लिए कॉन्टेक्स्ट-फ्री ग्रामर (CFG) का समर्थन करता है। 

अपनी प्रतिक्रियाओं पर कोई ग्रामर—जैसे SQL या डोमेन-स्पेसिफिक लैंग्वेज (DSL)—लागू करके, GPT-5 यह सुनिश्चित करता है कि आउटपुट लगातार अपेक्षित संरचना का पालन करें। CFG खास तौर पर ऑटोमेटेड प्रक्रियाओं और उच्च-दांव वाले वर्कफ़्लोज़ के लिए महत्वपूर्ण है। 

GPT-5, Lark जैसे फ़ॉर्मैट्स में परिभाषित ग्रामर का उपयोग करके जनरेशन के दौरान टूल के आउटपुट को सीमित कर सकता है। संकुचित डिकोडिंग का यह दृष्टिकोण फ़ॉर्मैट ड्रिफ्ट रोककर विश्वसनीयता बढ़ाता है और संरचनात्मक सुसंगतता सुनिश्चित करता है।

अब हम वह कोड लिखेंगे जहाँ मॉडल एक टूल चुनता है और केवल एक ग्रामर-वैध अंकगणितीय अभिव्यक्ति आउटपुट करता है; फिर इस अभिव्यक्ति का Python में मूल्यांकन होता है, परिणाम बातचीत में लौटाया जाता है, और अंतिम प्रतिक्रिया स्वाभाविक भाषा में स्पष्ट रूप से प्रस्तुत की जाती है।

इस उदाहरण कोड में, हमारे पास है:

1. OpenAI क्लाइंट इनिशियलाइज़ किया और कस्टम टूल math_solver परिभाषित किया, जिसे केवल ग्रामर-वैध अंकगणितीय अभिव्यक्ति (Lark CFG) आउटपुट करनी है।
2. उपयोगकर्ता की प्राकृतिक-भाषा वाली गणित की प्रश्न से बातचीत शुरू की।
3. पहली मॉडल कॉल की, GPT-5 को निर्देश देते हुए कि वह ग्रामर के अनुरूप अभिव्यक्ति के साथ math_solver को कॉल करे।
4. इमिट किए गए टूल कॉल को ढूँढा और टूल पेलोड से रॉ अभिव्यक्ति स्ट्रिंग निकाली।
5. अभिव्यक्ति का लोकली सीमित वातावरण में मूल्यांकन किया और ठोस परिणाम निकाला।
6. टूल निष्पादन परिणाम को मूल call_id से लिंक करके बातचीत में वापस लौटाया।
7. अंतिम मॉडल कॉल की ताकि मूल्यांकित परिणाम स्वाभाविक भाषा में स्पष्ट रूप से प्रस्तुत हो।

from openai import OpenAI
import json

client = OpenAI()

# --- Local fake evaluator ---
def eval_expression(expr: str) -> str:
    try:
        # Evaluate safely using Python's eval on restricted globals
        result = eval(expr, {"__builtins__": {}}, {})
        return f"{expr} = {result}"
    except Exception as e:
        return f"Error evaluating expression: {e}"

# --- Custom tool with grammar constraint ---
tools = [
    {
        "type": "custom",
        "name": "math_solver",
        "description": "Solve a math problem by outputting ONLY a valid arithmetic expression.",
        "format": {
            "type": "grammar",
            "syntax": "lark",
            "definition": r"""
start: expr

?expr: term
     | expr "+" term   -> add
     | expr "-" term   -> sub

?term: factor
     | term "*" factor -> mul
     | term "/" factor -> div

?factor: NUMBER
       | "(" expr ")"

%import common.NUMBER
%ignore " "
"""
        },
    }
]

# --- User asks ---
msgs = [
    {"role": "user", "content": "What is (12 + 8) * 3 minus 5 divided by 5?"}
]

# 1) First model call: GPT-5 must emit a grammar-valid expression
resp = client.responses.create(
    model="gpt-5",
    tools=tools,
    input=msgs,
    instructions="Always call the math_solver tool with a grammar-valid arithmetic expression like '(12 + 8) * 3 - 5 / 5'."
)

msgs += resp.output

tool_call = next(
    x for x in resp.output
    if getattr(x, "type", "") in ("custom_tool_call", "tool_call", "function_call")
)

expr = getattr(tool_call, "input", "") or getattr(tool_call, "arguments", "")
print("\n=== Grammar-Constrained Expression ===")
print(expr)

# 2) Run the local evaluator
tool_result = eval_expression(expr)
print("\n=== Tool Execution Result ===")
print(tool_result)

# 3) Return tool output
msgs.append({
    "type": "function_call_output",
    "call_id": tool_call.call_id,
    "output": tool_result
})

# 4) Final pass: GPT-5 presents answer nicely
final = client.responses.create(
    model="gpt-5",
    input=msgs,
    tools=tools,
    instructions="Present the evaluated result clearly in natural language."
)

print("\n=== Final Output ===")
print(final.output_text)संचालित द्वारा

जैसा कि आप देख सकते हैं, मॉडल ने टूल चुना और फिर ग्रामर-सीमित अभिव्यक्ति जनरेट की। उसके बाद, इसे Python फ़ंक्शन से गुजारा गया ताकि उत्तर निकले। अंत में, हमें स्वाभाविक भाषा में सही उत्तर मिलता है।

=== Grammar-Constrained Expression ===
(12 + 8) * 3 - 5 / 5

=== Tool Execution Result ===
(12 + 8) * 3 - 5 / 5 = 59.0

=== Final Output ===
59संचालित द्वारा

टूल अलौलिस्ट्स: सुरक्षित रूप से मॉडल के उपयोग को सीमित करें

allowed_tools सेटिंग आपको अपने पूरे टूलकिट से सुरक्षित टूल्स के चयन तक मॉडल को सीमित करने देती है। यह अनुमान-योग्यता बढ़ाती है और अनचाहे टूल कॉल्स को रोकती है, जबकि मॉडल को अनुमत सेट के भीतर लचीलापन देती है। 

आप मॉडल को अनुमत टूल्स में से चुनने दे सकते हैं या किसी एक का उपयोग अनिवार्य कर सकते हैं—अन्य स्टैक्स में दिखने वाले “force tool” व्यवहार जैसा—और टूल कॉलिंग ऑर्केस्ट्रेशन की सर्वश्रेष्ठ प्रथाओं के अनुरूप।

अब हम वह कोड लिखेंगे जहाँ हम एक ही टूल की अनुमति देते हैं, मॉडल केवल उसी टूल को कॉल करता है, हम उसे चलाते हैं, परिणाम वापस फीड करते हैं, और फिर संक्षिप्त, उपयोगकर्ता-उन्मुख सार प्रस्तुत करते हैं।

ध्यान दें: कृपया एक निःशुल्क Firecrawl खाता बनाएँ, API कुंजी जनरेट करें, उसे FIRECRAWL_API_KEY एन्वायरनमेंट वेरिएबल के रूप में सेव करें, और Firecrawl Python SDK इंस्टॉल करें: pip install firecrawl-py।

इस उदाहरण कोड में, हमारे पास है:

1. पूरे टूलसेट में dummy_web_search और firecrawl_search दोनों परिभाषित किए।
2. tool_choice = { type: "allowed_tools", mode: "required", tools: [...] } के जरिए मॉडल को केवल firecrawl_search तक सीमित किया।
3. पहली मॉडल कॉल जारी की, टूल कॉल का नाम और आर्ग्युमेंट्स कैप्चर किए, और दृश्यता के लिए उन्हें प्रिंट किया।
4. जब firecrawl_search बुलाया गया, आर्ग्युमेंट्स डीसिरियलाईज़ किए, Firecrawl चलाया, उसके रिस्पॉन्स को JSON-सीरियलाईज़ेबल डिक्ट में बदला, और सुरक्षित डेटा पेलोड निकाला।
5. call_id से लिंक किए function_call_output का उपयोग करके टूल परिणामों को बातचीत में वापस फीड किया, फिर 3–4 बिंदुओं में Markdown लिंक्स के साथ सारांश बनाने के लिए अंतिम मॉडल कॉल की।
6. एक फॉलबैक ब्रांच भी शामिल की जो डम्मी टूल चलाती—हालाँकि इस रन में अलौलिस्ट इसे रोकती है।
7. अंतिम स्वाभाविक-भाषा उत्तर प्रिंट किया।

from openai import OpenAI
from firecrawl import Firecrawl
import json
import os

client = OpenAI()
firecrawl = Firecrawl(api_key=os.environ["FIRECRAWL_API_KEY"])

# --- Full toolset ---
tools = [
    {
        "type": "function",
        "name": "dummy_web_search",
        "description": "A fake web search that always returns static dummy results.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "limit": {"type": "integer"}
            },
            "required": ["query"]
        },
    },
    {
        "type": "function",
        "name": "firecrawl_search",
        "description": "Perform a real web search using Firecrawl.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "limit": {"type": "integer"}
            },
            "required": ["query"]
        },
    },
]

# --- Dummy implementation ---
def dummy_web_search(query, limit=3):
    return {
        "query": query,
        "results": [f"[Dummy] Result {i+1} for '{query}'" for i in range(limit)]
    }

# --- User asks ---
messages = [
    {"role": "user", "content": "Find me the latest info about the stock market."}
]

# --- Restrict to Firecrawl only ---
resp = client.responses.create(
    model="gpt-5",
    tools=tools,
    input=messages,
    instructions="Only the firecrawl_search tool is allowed. Do not use dummy_web_search.",
    tool_choice={
        "type": "allowed_tools",
        "mode": "required",  # force Firecrawl
        "tools": [{"type": "function", "name": "firecrawl_search"}],
    },
)

for item in resp.output:
    if getattr(item, "type", "") in ("function_call", "tool_call"):
        print("\n--- Tool Call ---")
        print("Tool name:", item.name)
        print("Arguments:", item.arguments)

        if item.name == "firecrawl_search":
            args = json.loads(item.arguments)

            # Firecrawl returns a SearchData object → convert it
            results_obj = firecrawl.search(
                query=args["query"],
                limit=args.get("limit", 3),
            )

            # 🔥 Convert to JSON-serializable dict
            if hasattr(results_obj, "to_dict"):
                results = results_obj.to_dict()
            elif hasattr(results_obj, "dict"):
                results = results_obj.dict()
            else:
                results = json.loads(results_obj.json()) if hasattr(results_obj, "json") else results_obj

            print("\n--- Firecrawl Raw Results ---")
            print(json.dumps(results, indent=2)[:500])

            # ✅ Extract only the data portion for summarization
            safe_results = results.get("data", results)

            # Feed back to GPT
            messages += resp.output
            messages.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(safe_results)  # now safe
            })

            # Final pass
            final = client.responses.create(
                model="gpt-5",
                tools=tools,
                input=messages,
                instructions="Summarize the Firecrawl search results into 3-4 bullet points with clickable [Title](URL) links."
            )

            print("\n--- Final Natural Language Answer ---")
            print(final.output_text)

        elif item.name == "dummy_web_search":
            args = json.loads(item.arguments)
            results = dummy_web_search(args["query"], args.get("limit", 3))
            print("\n--- Dummy Web Search Results ---")
            print(json.dumps(results, indent=2))संचालित द्वारा

इसने Firecrawl सर्च चुना, और उसका उपयोग करके अंतिम प्रतिक्रिया मार्कडाउन फ़ॉर्मैट में जनरेट की।

प्रीऐम्बल्स: मॉडल को बताएं कि टूल्स कैसे कॉल करें

प्रीऐम्बल्स वे संक्षिप्त स्पष्टीकरण हैं जिन्हें मॉडल टूल बुलाने से पहले जनरेट करता है, ताकि कॉल करने का कारण स्पष्ट हो। ये पारदर्शिता बढ़ाते हैं, उपयोगकर्ता का भरोसा बनाते हैं, और जटिल वर्कफ़्लोज़ में डिबगिंग को स्पष्ट करते हैं। आप सरल निर्देश, जैसे “टूल कॉल करने से पहले समझाएँ,” देकर इन्हें सक्षम कर सकते हैं—आम तौर पर बिना ध्यान देने योग्य विलंब के। 

अब हम वह कोड लिखेंगे जिसमें मॉडल पहले “Preamble:” पंक्ति में संक्षेप में बताता है कि वह टूल क्यों कॉल कर रहा है, फिर टूल कॉल करता है, आप उसे लोकली चलाते हैं, परिणाम लौटाते हैं, और मॉडल स्पष्ट अंतिम उत्तर उत्पन्न करता है।

इस उदाहरण कोड में, हमारे पास है:

1. OpenAI क्लाइंट इनिशियलाइज़ किया और JSON Schema के साथ सख्त-टाइप्ड फ़ंक्शन टूल (medical_advice) परिभाषित किया।
2. एक सिस्टम निर्देश जोड़ा जो मॉडल से मांगता है कि किसी भी टूल कॉल से पहले एक-लाइन “Preamble:” आउटपुट करे।
3. बातचीत उपयोगकर्ता के लक्षण-संबंधी प्रश्न से शुरू की।
4. पहली मॉडल कॉल की ताकि प्रीऐम्बल और टूल कॉल उसके आर्ग्युमेंट्स सहित प्राप्त हों।
5. टूल कॉल निकाला और लोकली चलाकर सलाह जनरेट की।
6. टूल का आउटपुट call_id से लिंक करके मॉडल को वापस भेजा।
7. अंतिम मॉडल कॉल की ताकि GPT‑5 परिणाम को संक्षिप्त, उपयोगकर्ता-अनुकूल उत्तर के रूप में प्रस्तुत करे।

from openai import OpenAI
import json
import random

client = OpenAI()

# --- Fake tool implementation ---
def medical_advice(symptom: str):
    remedies = {
        "headache": "You can take acetaminophen (paracetamol) or ibuprofen, rest in a quiet room, and stay hydrated.",
        "cough": "Drink warm fluids, use honey in tea, and consider over-the-counter cough syrup.",
        "fever": "Use acetaminophen to reduce fever, stay hydrated, and rest. See a doctor if >39°C.",
    }
    return {"advice": remedies.get(symptom.lower(), "Please consult a healthcare provider for guidance.")}

# --- Tool definition ---
tools = [{
    "type": "function",
    "name": "medical_advice",
    "description": "Provide safe, general over-the-counter advice for common symptoms.",
    "parameters": {
        "type": "object",
        "properties": {"symptom": {"type": "string"}},
        "required": ["symptom"],
        "additionalProperties": False
    },
    "strict": True,
}]

# --- Messages (system preamble instruction) ---
messages = [
    {"role": "system", "content": "Before you call a tool, explain why you are calling it in ONE short sentence prefixed with 'Preamble:'."},
    {"role": "user", "content": "What should I take for a headache?"}
]

# 1) First call: expect preamble + tool call
resp = client.responses.create(model="gpt-5", input=messages, tools=tools)
print("=== First Response ===")
for item in resp.output:
    t = getattr(item, "type", None)
    if t == "message":
        # Extract just the model's text
        content = getattr(item, "content", None)
        text = None
        if isinstance(content, list):
            text = "".join([c.text for c in content if hasattr(c, "text")])
        elif content:
            text = str(content)
        if text:
            # ✅ Only print once
            print(text)
    if t in ("function_call", "tool_call", "custom_tool_call"):
        print("Tool:", getattr(item, "name", None))
        print("Args:", getattr(item, "arguments", None))

# Extract tool call
tool_call = next(x for x in resp.output if getattr(x, "type", None) in ("function_call","tool_call","custom_tool_call"))
messages += resp.output

# 2) Execute tool locally
args = json.loads(getattr(tool_call, "arguments", "{}"))
symptom = args.get("symptom", "")
tool_result = medical_advice(symptom)

# 3) Return tool result
messages.append({
    "type": "function_call_output",
    "call_id": tool_call.call_id,
    "output": json.dumps(tool_result)
})

# 4) Final model call → natural answer
final = client.responses.create(model="gpt-5", input=messages, tools=tools)
print("\n=== Final Answer ===")
print(final.output_text)संचालित द्वारा

आप देख सकते हैं कि टूल कॉल करने से पहले यह बताता है कि वह टूल क्यों कॉल कर रहा है। यह ऑब्ज़र्वेबिलिटी और डिबगिंग के लिए अच्छा है।

सार

GPT-5 अब तक का OpenAI का सबसे उन्नत मॉडल है, विशेष रूप से कोडिंग और एजेंट-आधारित वर्कफ़्लोज़ में उत्कृष्ट। इसकी नवीनतम API विशेषताएँ आरंभ से अंत तक प्रोडक्शन-ग्रेड सिस्टम्स के सीधे विकास की अनुमति देती हैं।

इस ट्यूटोरियल में, आपने सीखा कि कैसे:

1. स्ट्रक्चर्ड आउटपुट लौटाएँ फ़ंक्शन टूल्स और JSON Schema का उपयोग करके, ताकि डाउनस्ट्रीम ऑटोमेशन विश्वसनीय हो।
2. फ्री-फॉर्म सक्षम करें कस्टम टूल्स (रॉ-टेक्स्ट) के साथ, जिससे मॉडल JSON कॉल्स से आगे बढ़कर कोड, SQL, शेल स्क्रिप्ट्स, और CSV फाइलें जनरेट कर सके।
3. सीमित फ़ॉर्मैट्स जब सटीकता महत्वपूर्ण हो—जैसे गणित, SQL, या डोमेन-स्पेसिफिक लैंग्वेज (DSLs)—तो Lark ग्रामर बाधाओं का उपयोग करें।
4. टूल एक्सेस सीमित करें अलौलिस्ट्स (या एकल टूल लागू करके) के साथ, ताकि सुरक्षा, नियंत्रण, और निर्धारणशक्ति बढ़े।
5. पारदर्शिता सुधारें संक्षिप्त प्रीऐम्बल्स के साथ, ताकि मॉडल बताए कि वह किसी विशिष्ट टूल को क्यों कॉल कर रहा है—ऑब्ज़र्वेबिलिटी और डिबगिंग में सहायक।

OpenAI के विभिन्न टूल्स से आप क्या कर सकते हैं, इस बारे में और जानने के लिए, मैं हमारी OpenAI Fundamentals स्किल ट्रैक और Working with the OpenAI API कोर्स लेने की सलाह देता/देती हूँ।