مین مواد پر جائیں

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​
DIAGRAM: Ye looptab tak chalta hai jab takkaamho na jaye (yamax_turns/budget khatam na ho) THINK ACT OBSERVE Goal/Sawal (LLMsochtahai) (tool chalao) (natijadekho) Kaammukammal?...
DIAGRAM: Ye looptab tak chalta hai jab takkaamho na jaye (yamax_turns/budget khatam na ho) THINK ACT OBSERVE Goal/Sawal (LLMsochtahai) (tool chalao) (natijadekho) Kaammukammal?...

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​
DIAGRAM: User TumhariApp LLM (model) Topl (tumharafunction) Karachi ka mausam? sawal + tools ki list (schema) function_call: get_weather(city="Karachi") function asal me chalao result:...
DIAGRAM: User TumhariApp LLM (model) Topl (tumharafunction) Karachi ka mausam? sawal + tools ki list (schema) function_call: get_weather(city="Karachi") function asal me chalao result:...
  1. Tum model ko sawal + tools ki list (schema) bhejti ho.

  2. Model faisla karta hai: seedha jawab dun ya tool chalane ko kahun? Tool ke liye wo function_call (naam + JSON arguments) bhejta hai.

  3. Tumhara code function chalata hai.

  4. Natija function_call_output ke taur par model ko wapas jata hai.

  5. 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 designKharab 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):

  1. Agent ko instructions + input + tools de kar model ko call karo.

  2. Agar model final jawab de to ruk jao aur result wapas do.

  3. Agar model tool calls de to unhein chalao , natijon ko history me jodo aur qadam 1 par wapas jao.

  4. Agar model handoff kare to naya agent loop sambhal leta hai (32.8).

  5. Agar loop max_turns (default 10) se zyada chala to MaxTurnsExceeded error aata hai.

result ki cheezMatlab
result.final_outputFinal jawab (text ya output_type ka object)
result.last_agentAakhri jawab dene wala agent (handoff ke baad kaam ata hai)
result.new_itemsIs 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:

HandoffAgent as Tool
ControlKaamnaye agent ko mukammal chala jata haiManager agentcontrol apne paas rakhta hai
Jawab kaun deta?Naya (specialist) agent seedha user koManager, specialist ka natija le kar
MisaalReception sedoctorke paas bhejnaManager katranslatorse tarjuma karwa kar report
banana
CodeAgent(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 hissaKya deta hai?Kab kaam aata hai?
SessionsGuftagu ki yaaddashtChatbot, tutor, support
TracingHar qadam ka recordDebugging, monitoring, evaluation
GuardrailsInput/output ki jaanchSafety, topic ki hadd, nijee data
Hosted tools (jaise
WebSearchTool)
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.

HissaTafseel
AgentStudy Buddy, Roman Urdu, mukhtasar jawab
Toolscourse_lookup, safe_calculate, make_quiz (32.5 ke, pehle test shuda)
YaaddashtSQLiteSession (har student ke liye alag id)
Guardrailinput_guard (32.9) agent se pehle chalao
LoopTerminal/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_turns ya 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 lahore aur multan ka sawal try karo; "multan" par kya hua aur kyun?

  • Schema: schema_from_function ko bool argument wale function par chalao aur required ka farq dekho.

  • Calculator: safe_calculate me ** aur -5 ke 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_turns hifazati had hai.

  • OpenAI Agents SDK: Agent(name, instructions, tools, handoffs, output_type, model) aur Runner.run / run_sync.

  • Tools ko pehle seedha test karo , errors string me wapas karo, aur eval kabhi 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.