Chapter 32: OpenAI Agents SDK, Tool Integration aur Function Calling
MODULE 9 | WEEK 32
Chapter 32: OpenAI Agents SDK, Tool Integration aur Function Calling
Ab tak LLM sirf text ke badle text deta tha. Asli applications me use kaam karna hota hai: mausam dekhna, hisaab karna, database se data nikalna, email bhejna. Is chapter me seekhenge ke LLM tools (functions) ko kaise istemal karta hai ( function calling ), phir OpenAI Agents SDK se chand lines me agent banayenge jo tools chalata hai, doosre agents ko kaam handoff karta hai, aur guftagu yaad rakhta hai. Pehle function calling zero se (bina API key ke, asli outputs ke saath) samjhenge, phir SDK.
32.1 LLM se Agent tak
Sirf LLM sawal ka jawab apni yaaddasht se deta hai. Agent wo system hai jahan LLM tools istemal kar sakta hai aur ek loop me tab tak kaam karta rehta hai jab tak kaam mukammal na ho.
DIAGRAM

32.2 Function Calling kaise kaam karta hai
Sab se aham baat: model khud function nahi chalata. Wo sirf likh kar batata hai ke "falan function ko ye arguments de kar chalao." Function tumhara code chalata hai aur natija model ko wapas deta hai. Flow:
DIAGRAM

-
Tum model ko sawal + tools ki list (schema) bhejti ho.
-
Model faisla karta hai: seedha jawab dun ya tool chalane ko kahun? Tool ke liye wo function_call (naam + JSON arguments) bhejta hai.
-
Tumhara code function chalata hai.
-
Natija function_call_output ke taur par model ko wapas jata hai.
-
Model ab final jawab likhta hai (ya aur tools mangta hai).
Is dhanchay ko samajhne ke liye LLM ki jagah ek saada rule-based nakal (fake_model) lagate hain. Asli model wohi message format deta hai, farq sirf ye hai ke faisla wo "samajh kar" karta hai:
import json
def get_weather(city: str) -> str:
data = {"karachi": "32 C, saaf", "lahore": "28 C, dhund",
"islamabad": "24 C, baarish"}
return data.get(city.lower(), "is shehar ka data nahi")
TOOLS = {"get_weather": get_weather}
def fake_model(messages):
"""Asli LLM ki jagah: sawal me shehar ho to tool mangta hai, warna jawab deta hai."""
last = messages[-1]
if last["role"] == "user":
for city in ["karachi", "lahore", "islamabad"]:
if city in last["content"].lower():
return {"type": "function_call", "name": "get_weather",
"arguments": json.dumps({"city": city})}
return {"type": "message", "content": "Mujhe shehar ka naam batao."}
return {"type": "message", "content": "Natija: " + last["content"]}
def run_agent(question, max_turns=5):
messages = [{"role": "user", "content": question}]
for turn in range(1, max_turns + 1):
reply = fake_model(messages)
if reply["type"] == "message":
# final jawab
print(f"[{turn}] MODEL -> jawab: {reply['content']}")
return reply["content"]
args = json.loads(reply["arguments"])
print(f"[{turn}] MODEL -> function_call: {reply['name']}({args})")
result = TOOLS[reply["name"]](**args) # tumhara code chalta hai
print(f"[{turn}] TOOL -> {result}")
messages.append({"role": "tool", "content": result})
return "max_turns khatam" run_agent("Karachi ka mausam kaisa hai?")
print()
run_agent("Mausam batao")
OUTPUT [1] MODEL -> function_call: get_weather({'city': 'karachi'}) [1] TOOL -> 32 C, saaf [2] MODEL -> jawab: Natija: 32 C, saaf [1] MODEL -> jawab: Mujhe shehar ka naam batao.
32.3 Tool ki JSON Schema
Model ko tool ke bare me text description milti hai, jise JSON Schema kehte hain: naam, kaam ka bayan, aur har argument ki qism aur matlab . Ye hi wo maloomat hai jis se model faisla karta hai ke tool kab aur kaise chalana hai. Is liye schema aur docstring jitni saaf, model utna sahi.
Dil-chaspi ki baat ye hai ke tumhein ye schema haath se nahi likhna parta : Python function ke naam, type hints aur docstring se khud ban jati hai. Isay Python ke inspect module se khud banate hain (bilkul wohi kaam jo SDK ka @function_tool andar karta hai):
import inspect
TYPE_MAP = {str: "string", int: "integer", float: "number", bool: "boolean"}
def schema_from_function(fn):
sig = inspect.signature(fn)
props, required = {}, []
for name, param in sig.parameters.items():
props[name] = {"type": TYPE_MAP[param.annotation]}
if param.default is inspect.Parameter.empty:
required.append(name) # default
nahi => zaroori
return { "type": "function", "name": fn.__name__, "description": inspect.getdoc(fn), "parameters": {"type": "object", "properties": props, "required": required}, }
def convert_currency(amount: float, rate: float, round_to: int = 2) -> str:
"""Rupee ki raqam ko kisi doosri currency me badalta hai (amount / rate)."""
return str(round(amount / rate, round_to))
print(json.dumps(schema_from_function(convert_currency), indent=2, ensure_ascii=False))
OUTPUT { "type": "function", "name": "convert_currency", "description": "Rupee ki raqam ko kisi doosri currency me badalta hai (amount / rate).", "parameters": { "type": "object", "properties": {
"amount": {
"type": "number"
},
"rate": {
"type": "number"
},
"round_to": {
"type": "integer"
}
},
"required": [
"amount",
"rate"
]
}
}
Dekho: amount aur rate required hain jab ke round_to ka default hai, is liye wo optional . Ab asli OpenAI Responses API me function calling (Colab me chalao; jawab model par depend karta hai):
import json
from openai import OpenAI
client = OpenAI()
MODEL = "gpt-5.4-mini"
tools = [{ "type": "function", "name": "get_weather", "description": "Kisi shehar ka maujooda mausam batata hai.", "parameters": { "type": "object", "properties": {"city": {"type": "string", "description": "Shehar ka naam"}}, "required": ["city"], "additionalProperties": False, }, "strict": True, }]
input_list = [{"role": "user", "content": "Karachi ka mausam kaisa hai?"}]
response = client.responses.create(model=MODEL, input=input_list, tools=tools) input_list += response.output # model ke items history me rakho
for item in response.output:
if item.type == "function_call":
args = json.loads(item.arguments)
result = get_weather(**args) # tumhara function chalta hai input_list.append({"type": "function_call_output", "call_id": item.call_id, "output": result})
final = client.responses.create(model=MODEL, input=input_list, tools=tools)
print(final.output_text)
OUTPUT (namoona) Karachi me abhi 32 C hai aur mausam saaf hai.
Achi tool design Kharab tool design Saaf naam: get_weather, search_course Mubham naam: do_it, tool1 Mukhtasar aur maqsad wali docstring ("kab istemal karo") Khali ya be-matlab description Chhote, ek kaam wale tools Ek bara tool jo 10 kaam kare Strict types aur enum (maslan unit: "C" ya "F") Sab kuch str me
| Achi tool design | Kharab tool design |
|---|---|
| Errors ko text me wapas karo: "shehar nahi mila" | Exception phenk do aur agent ko crash karao |
| Kam ijazat(sirf parhne wala) | Sab kuch delete/send karne ki ijazat |
32.4 OpenAI Agents SDK: setup aur pehla Agent
Upar ka loop khud likhna seekhne ke liye tha. Asli kaam me OpenAI Agents SDK ye sara loop sambhal leta hai. Ye ek halki Python library hai jis ke teen bunyadi tukray hain: Agent (model + hidayat + tools), Runner (loop chalata hai), aur tools/handoffs . Install: pip install openai-agents (API key wohi OPENAI_API_KEY):
# pip install openai-agents
from agents import Agent, Runner
agent = Agent(
name="Tutor",
instructions="Tum Roman Urdu me mukhtasar jawab dene wale AI tutor ho.",
model="gpt-5.4-mini", # docs me aaj ka naam dekho
)
result = Runner.run_sync(agent, "Gradient descent ko ek jumle me samjhao.")
print(result.final_output)
OUTPUT (namoona)
Gradient descent wo tareeqa hai jis me model apne weights ko loss ki dhalan ke ulta rukh
chhote chhote qadam me badal kar loss kam karta hai.
32.5 @function_tool: tools banana aur test karna
SDK me tool banana sab se asaan hai: ek normal Python function likho ( type hints aur docstring ke saath) aur us par @function_tool lagao. Hum teen kaam ke tools banate hain. Aham usool: tool ko agent me lagane se pehle seedha chala kar test karo :
import ast, operator, random
# --- Tool 1:
course ke kisi hafte ka mawad (syllabus se) ---
SYLLABUS = {
29: "Transformers aur Attention Mechanism, Self-Attention, Positional Encoding",
30: "Large Language Models (GPT, BERT), LLM Applications",
31: "Text Generation aur Fine-tuning using OpenAI API",
32: "OpenAI Agent SDK, Tool Integration aur Function Calling",
33:
"Agentic AI: Autonomous Agents, Planning, Memory, Multi-Agent Systems", }
def course_lookup(week: int) -> str:
"""Course ke kisi hafte (29 se 33) ka mawad batata hai."""
return SYLLABUS.get(week, f"Week {week} ka data mere paas nahi (sirf 29 se 33).") # --- Tool 2:
mehfooz calculator (eval kabhi nahi!) --OPS = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.Pow: operator.pow, ast.USub: operator.neg}
def _eval(node):
if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
return node.value
if isinstance(node, ast.BinOp) and type(node.op) in OPS:
return OPS[type(node.op)](_eval(node.left), _eval(node.right))
if isinstance(node, ast.UnaryOp) and type(node.op) in OPS:
return OPS[type(node.op)](_eval(node.operand)) raise ValueError("sirf + - * / ** ki ijazat hai")
def safe_calculate(expression: str) -> str:
"""Ek hisabi expression ka jawab nikalta hai, maslan '(5 / 49) * 100'."""
try:
return str(round(_eval(ast.parse(expression, mode="eval").body), 4))
except Exception as e:
return f"Hisaab nahi ho saka: {e}" # --- Tool 3:
mashq ka sawal --QUIZ = { "attention": ("Attention me sqrt(d_k) se kyun bhaagte hain?", "Softmax ko saturate hone se bachane ke liye"), "lora": ("LoRA me asli weights ka kya hota hai?", "Freeze rehte hain, sirf chhote A, B seekhe jate hain"), }
def make_quiz(topic: str) -> str:
"""Kisi topic (attention ya lora) ka ek mashq sawal deta hai."""
item = QUIZ.get(topic.lower())
return item[0]
if item
else "Is topic ka sawal nahi; attention ya lora try karo."
print(course_lookup(32))
print(course_lookup(5))
print(safe_calculate("(5 / 49) * 100"))
print(safe_calculate("__import__('os').system('ls')")) # hamla: rok diya gaya
print(make_quiz("lora"))
OUTPUT OpenAI Agent SDK, Tool Integration aur Function Calling Week 5 ka data mere paas nahi (sirf 29 se 33). 10.2041 Hisaab nahi ho saka: sirf + - * / ** ki ijazat hai LoRA me asli weights ka kya hota hai?
32.6 Runner ka run loop
Runner.run(agent, input) andar ye loop chalata hai (jo humne 32.2 me hath se likha tha):
-
Agent ko instructions + input + tools de kar model ko call karo.
-
Agar model final jawab de to ruk jao aur
resultwapas do. -
Agar model tool calls de to unhein chalao , natijon ko history me jodo aur qadam 1 par wapas jao.
-
Agar model handoff kare to naya agent loop sambhal leta hai (32.8).
-
Agar loop
max_turns(default 10) se zyada chala to MaxTurnsExceeded error aata hai.
result ki cheez | Matlab |
|---|---|
result.final_output | Final jawab (text ya output_type ka object) |
result.last_agent | Aakhri jawab dene wala agent (handoff ke baad kaam ata hai) |
result.new_items | Is run me bane tamam items: messages, tool calls, tool outputs |
result.to_input_list() | Is run ka poora record, agli run ke input ke taur par |
Runner.run(agent, input, max_turns=5) se loop ki had khud tay karo. Har tool call par paise aur waqt lagte hain, is liye max_turns ek hifazati had bhi hai.
32.7 Instructions ka design aur Structured Output
Agent ki instructions uska "job description" hain. Achi instructions me:
-
Kirdar aur maqsad: "Tum course ke student ki madadgar ho."
-
Tools ke qawaid: "Hisaab ke liye hamesha calculator tool, khud se andaza nahi."
-
Hadood: "Sirf course se mutaliq sawal; baqi par maazrat."
-
Jawab ka andaz aur zabaan: "Roman Urdu, 3 jumle se kam."
-
Anjaan sawal par kya kare: "Pata na ho to kaho pata nahi, jhoot mat bolo."
Agar agent ka jawab kisi aur code ke istemal ke liye chahiye to output_type me Pydantic class do. result.final_output text nahi, object hoga:
from pydantic import BaseModel
from agents import Agent, Runner
class StudyPlan(BaseModel):
weeks:
int hours_per_week:
int topics:
list[str]
planner = Agent( name="Planner", instructions="Student ke waqt ke mutabiq mukhtasar study plan banao.", output_type=StudyPlan, model="gpt-5.4-mini", )
result = await Runner.run(planner, "2 hafte, roz 1 ghanta. Transformers seekhne hain.")
plan = result.final_output # StudyPlan object
print(plan.weeks, plan.hours_per_week, plan.topics)
OUTPUT (namoona) 2 7 ['Self-Attention', 'Multi-Head aur Positional Encoding', 'Transformer block']
32.8 Multi-Agent: Handoffs aur Agents-as-Tools
Ek agent ko sab kuch sikhane ke bajaye maahir agents banao aur kaam unme taqseem karo. Is ke do bunyadi tareeqe hain:
| Handoff | Agent as Tool | |
|---|---|---|
| Control | Kaamnaye agent ko mukammal chala jata hai | Manager agentcontrol apne paas rakhta hai |
| Jawab kaun deta? | Naya (specialist) agent seedha user ko | Manager, specialist ka natija le kar |
| Misaal | Reception sedoctorke paas bhejna | Manager katranslatorse tarjuma karwa kar report banana |
| Code | Agent(handoffs=[a, b]) | agent.as_tool(tool_name=..., tool_description=...) |
from agents import Agent, Runner
python_tutor = Agent( name="Python Tutor", handoff_description="Python aur programming ke sawal", instructions="Tum Python ke tutor ho. Roman Urdu me aasan misal do.", model="gpt-5.4-mini", )
stats_tutor = Agent( name="Stats Tutor", handoff_description="Statistics aur probability ke sawal", instructions="Tum statistics ke tutor ho. Roman Urdu me aasan misal do.", model="gpt-5.4-mini", )
triage = Agent( name="Triage", instructions="Sawal dekho aur sahi tutor ko handoff do. Khud jawab mat do.", handoffs=[python_tutor, stats_tutor], model="gpt-5.4-mini", )
result = await Runner.run(triage, "Standard deviation kya hoti hai?")
print("Jawab dene wala:", result.last_agent.name)
print(result.final_output)
OUTPUT (namoona) Jawab dene wala: Stats Tutor
Standard deviation batati hai ke data apne average se kitna bikhra hua hai ...
Agent as tool ka tareeqa: specialist ko manager ka tool bana do:
translator = Agent(
name="Translator",
instructions="Roman Urdu text ko saaf English me translate karo.",
model="gpt-5.4-mini",
)
manager = Agent(
name="Manager",
instructions="Student ka jawab dene ke liye translate_to_english tool istemal karo.",
tools=[translator.as_tool(
tool_name="translate_to_english",
tool_description="Roman Urdu text ko English me badalta hai",
)],
model="gpt-5.4-mini",
)
32.9 Sessions, Tracing aur Guardrails
Sessions: agent ko yaaddasht dena
Bina session ke har Runner.run naye sire se hoti hai (jaise Chapter 31 me history khud bhejni thi). Session history khud store aur dobara bhejta hai:
from agents import Agent, Runner, SQLiteSession
agent = Agent(name="Tutor", instructions="Roman Urdu me mukhtasar jawab do.",
model="gpt-5.4-mini")
session = SQLiteSession("sara_chat") # file ke liye:
SQLiteSession("id", "chat.db")
r1 = await Runner.run(agent, "Mera naam Sara hai.", session=session)
r2 = await Runner.run(agent, "Mera naam kya tha?", session=session)
print(r2.final_output)
OUTPUT (namoona) Aap ka naam Sara hai.
Tracing: agent ne kya kya kiya?
SDK har run ka trace khud record karta hai: kaun sa model call hua, kaun sa tool, kya arguments, kya natija. OpenAI dashboard ke Traces hissay me ye nazar aata hai. Debugging ke liye ye bohat qeemti hai ("agent ne ghalat tool kyun chuna?"). Ehtiyat: traces me prompts aur data hota hai, is liye hassas data ke saath is ka istemal soch samajh kar karo (tracing band bhi ki ja sakti hai).
Guardrails: hifazati jaanch
Guardrails wo checks hain jo agent ke input se pehle ya output ke baad chalte hain: maslan "sawal course se mutaliq hai?", "jawab me nijee data to nahi?". SDK me input guardrails aur output guardrails hote hain jo ghalat cheez par run rok dete hain (tripwire). Asal tafseel SDK ke docs me hai; yahan idea ko saade Python check se samjho (asli guardrail me ye faisla aksar ek chhota LLM karta hai):
BLOCKED = ["password", "card number", "cnic"]
TOPICS = ["python", "numpy", "pandas", "transformer", "llm", "agent",
"api", "model", "week"]
def input_guard(text):
t = text.lower()
if any(b in t for b in BLOCKED):
return False, "hassas maloomat mat bhejo"
if not any(k in t for k in TOPICS):
return False, "ye sawal course se mutaliq nahi lagta"
return True, "OK"
for q in ["Week 30 me kya hai?", "Meri cnic ye hai 42101...", "Biryani ki recipe batao"]:
print(f"{q:28s} ->", input_guard(q))
OUTPUT Week 30 me kya hai? -> (True, 'OK') Meri cnic ye hai 42101... -> (False, 'hassas maloomat mat bhejo') Biryani ki recipe batao -> (False, 'ye sawal course se mutaliq nahi lagta')
| SDK ka hissa | Kya deta hai? | Kab kaam aata hai? |
|---|---|---|
| Sessions | Guftagu ki yaaddasht | Chatbot, tutor, support |
| Tracing | Har qadam ka record | Debugging, monitoring, evaluation |
| Guardrails | Input/output ki jaanch | Safety, topic ki hadd, nijee data |
Hosted tools (jaiseWebSearchTool) | OpenAI ke tayyar tools (web search waghera) | Jahan khud tool likhna zaroori na ho |
32.10 Mini Project: Study Buddy Agent
Ab sab kuch jod kar ek chhota mukammal project banate hain. Maqsad: ek agent jo course ka mawad batata hai, hisaab karta hai, mashq sawal deta hai, aur guftagu yaad rakhta hai , aur jis ke hadood ke guardrails hain.
| Hissa | Tafseel |
|---|---|
| Agent | Study Buddy, Roman Urdu, mukhtasar jawab |
| Tools | course_lookup, safe_calculate, make_quiz (32.5 ke, pehle test shuda) |
| Yaaddasht | SQLiteSession (har student ke liye alag id) |
| Guardrail | input_guard (32.9) agent se pehle chalao |
| Loop | Terminal/Colab me sawal jawab ka chakkar |
# study_buddy.py (pip install openai-agents; OPENAI_API_KEY set ho)
import asyncio
from agents import Agent, Runner, SQLiteSession, function_tool
# course_lookup, safe_calculate, make_quiz aur input_guard upar wale code se copy karo
agent = Agent(
name="Study Buddy",
instructions=(
"Tum course ke student ki madadgar ho. Roman Urdu me, 3 jumlon se kam. "
"Mawad ke liye course_lookup, hisaab ke liye safe_calculate, "
"mashq ke liye make_quiz tool use karo. Pata na ho to kaho 'maloom nahi'."
),
tools=[function_tool(course_lookup), function_tool(safe_calculate),
function_tool(make_quiz)],
model="gpt-5.4-mini",
)
async def main():
session = SQLiteSession("student_1")
while True:
question = input("Tum: ")
if question.lower()
in ("exit", "quit"):
break
ok, why = input_guard(question)
if not ok:
print("Study Buddy:", why) continue
result = await Runner.run(agent, question, session=session, max_turns=6)
print("Study Buddy:", result.final_output)
asyncio.run(main())
OUTPUT (namoona) Tum: Week 31 me kya hai? Study Buddy: Week 31 me OpenAI API se text generation aur fine-tuning parhna hai. Tum: Mujhe attention ka ek sawal do Study Buddy: Attention me sqrt(d_k) se kyun bhaagte hain? Tum: Biryani ki recipe batao Study Buddy: ye sawal course se mutaliq nahi lagta
Iske baad: (1) QUIZ me 10 topics jodo, (2) course_lookup ko poore 49 hafton ke syllabus se bharo, (3) answer check karne ka tool (check_answer) banao, (4) 10 sawalon ka test set bana kar agent ko parkho (Chapter 33.7).
32.11 Aam Galtiyan aur Hands-on
AAM GALTIYAN
-
Samajhna ke model khud function chalata hai. Function tumhara code chalata hai.
-
Tool ka docstring/naam mubham rakhna (model sahi tool nahi chunta).
-
eval()ya shell command model ke arguments par chalana. -
Tool me exception phenkna (agent crash ho jata hai); string me error wapas karo.
-
Colab me
run_sync(event loop error):await Runner.run(...)likho. -
max_turnsya budget na lagana (agent chakkar me phans kar paise jala sakta hai). -
Har kaam ke liye multi-agent (zyada kharcha, zyada ghaltiyan). Pehle ek agent.
-
Tools ko zaroorat se zyada ijazat dena (delete, email, payment).
Hands-on
-
fake_model: 32.2 me
lahoreaurmultanka sawal try karo; "multan" par kya hua aur kyun? -
Schema:
schema_from_functionkoboolargument wale function par chalao aurrequiredka farq dekho. -
Calculator:
safe_calculateme**aur-5ke test jodo; 3 khatarnaak expressions block karke dikhao. -
Tool: apna 4th tool banao (maslan
study_plan(hours_per_day: int, weeks: int)) aur seedha test karo. -
Agent: Study Buddy me 4th tool lagao (agar API key ho).
-
Handoff: teen specialist agents (Python, Stats, ML) ka triage design banao, aur 5 test sawal likho jo har agent ko jayen.
KEY TAKEAWAYS
-
Function calling: model likh kar tool batata hai (naam + JSON arguments); function tumhara code chalata hai.
-
Tool ki JSON Schema naam, type hints aur docstring se bantiye; saaf description = sahi tool selection.
-
Agent = LLM + tools + loop. Runner loop chalata hai jab tak final jawab na aaye;
max_turnshifazati had hai. -
OpenAI Agents SDK:
Agent(name, instructions, tools, handoffs, output_type, model)aurRunner.run / run_sync. -
Tools ko pehle seedha test karo , errors string me wapas karo, aur
evalkabhi nahi. -
Handoff (control doosre agent ko) vs agent as tool (manager control rakhta hai).
-
Sessions (yaaddasht), Tracing (record) aur Guardrails (hifazati jaanch) production ke liye zaroori hain.
-
Pehle ek saada agent , phir zaroorat par tools aur multi-agent barhao.