Chapter 32: OpenAI Agents SDK, Tool Integration and Function Calling
MODULE 9 | WEEK 32
Chapter 32: OpenAI Agents SDK, Tool Integration and Function Calling
Until now the LLM only gave text in return for text. Real applications need work to be done: checking the weather, doing calculations, getting data from a database, sending an email. In this chapter we learn how an LLM uses tools (functions) (function calling), then with the OpenAI Agents SDK we build, in a few lines, an agent that runs tools, hands work over to other agents, and remembers the conversation. First we will understand function calling from zero (without an API key, with real outputs), and then the SDK.
TOPIC CHECKLIST (tick as you go)
-
Difference between an LLM and an Agent
-
Flow of function calling
-
JSON Schema of a tool (and what @function_tool does inside)
-
Setup of the Agents SDK and the first agent
-
Making tools with @function_tool and testing them
-
The run loop of the Runner
-
Instructions and structured output
-
Handoffs and agents-as-tools
-
Sessions (memory), tracing and guardrails
-
Mini Project: Study Buddy Agent
32.1 From LLM to Agent
Alone, an LLM answers a question only from its own memory. An Agent is a system in which the LLM can use tools and keeps working in a loop until the task is complete.
<mark>ANALOGY</mark>
An LLM is a very well-read advisor who only talks. An Agent is a personal assistant who has a phone, a calculator and a calendar (tools). You say "look at tomorrow's meeting time and remind me": the assistant opens the calendar, checks the time, and then tells you. It both thinks and acts.
DIAGRAM: User question -> Agent (LLM) -> Tool call -> Tool result -> Agent -> Final answer
32.2 How Function Calling works
The most important point: the model does not run the function itself. It only writes down: "run this function with these arguments." The function is run by your code, and the result goes back to the model. The flow:
DIAGRAM: You -> Model (question + tool list) -> function_call -> Your code runs function -> function_call_output -> Model -> Final answer (or another tool)
-
You send the question and the list of tools (schema) to the model.
-
The model decides: should it answer directly or ask for a tool? For a tool, it sends a function_call (name + JSON arguments).
-
Your code runs the function.
-
The result goes back to the model as function_call_output.
-
The model now writes the final answer (or asks for more tools).
To understand this flow, we use a simple rule-based imitation ( fake_model ) in place of the LLM. The real model gives the same message format; the only difference is that it makes the decision by "understanding":
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(), "data for this city is not available")
TOOLS = {"get_weather": get_weather}
def fake_model(messages):
"""In place of a real LLM: if the question has a city, it asks for the tool; otherwise it
answers."""
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 answer
print(f"[{turn}] MODEL -> answer: {reply['content']}")
return reply["content"]
args = json.loads(reply["arguments"])
print(f"[{turn}] MODEL -> function_call: {reply['name']}({args})")
result = TOOLS[reply["name"]](**args) # your code runs
print(f"[{turn}] TOOL -> {result}")
messages.append({"role": "tool", "content": result})
return "max_turns finished"
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 -> answer: Natija: 32 C, saaf
[1] MODEL -> answer: Mujhe shehar ka naam batao.
<mark>REMEMBER</mark>
Agent = a loop. The model asks for a tool, your code runs it, the result goes back, and this repeats until the model gives the final answer. max_turns always guarantees that this loop stops.
32.3 JSON Schema of a Tool
The model gets a text description of each tool, called a JSON Schema: the name, what it does, and the type and meaning of each argument. This is the information on which the model decides when and how to run the tool. So the clearer the schema and docstring, the more correctly the model works.
The interesting thing is that you do not have to write this schema by hand: it is made automatically from the Python function's name, type hints and docstring. Here we build it with Python's inspect module (exactly the work that the SDK's @function_tool does inside):
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) # no
default => required
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:
"""Converts a rupee amount into another currency (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": "Converts a rupee amount into another currency (amount / rate).",
"parameters": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"rate": {
"type": "number"
},
"round_to": {
"type": "integer"
}
},
"required": [
"amount",
"rate"
]
}
}
See: amount and rate are required, while round_to has a default, so it is optional.
Now function calling in the real OpenAI Responses API (run in Colab; the answer depends on the model):
import json
from openai import OpenAI
client = OpenAI()
MODEL = "gpt-5.4-mini"
tools = [{
"type": "function",
"name": "get_weather",
"description": "Gives the current weather of a city.",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": "Name of the city"}},
"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 # keep the model's items in history
for item in response.output:
if item.type == "function_call":
args = json.loads(item.arguments)
result = get_weather(**args) # your function runs
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 (sample)
Karachi me abhi 32 C hai aur mausam saaf hai.
| Good tool design | Bad tool design |
|---|---|
Clear name:get_weather,search_course | Vague name:do_it,tool1 |
| Short docstring with purpose ("when to use it") | Empty or meaningless description |
| Small tools, one job each | One big tool that does 10 jobs |
Strict types and enums (for exampleunit: "C" or "F") | Everything asstr |
| Return errors as text: "city not found" | Throw an exception and crash the agent |
| Limited permission (read only) | Permission to delete/send everything |
32.4 OpenAI Agents SDK: Setup and the First Agent
The loop above was written by hand to learn the idea. In real work, the OpenAI Agents SDK handles all this loop. It is a light Python library with three basic parts: Agent (model + instructions + tools), Runner (runs the loop), and tools/handoffs. Install: pip install openai-agents (the API key is the same 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", # check today's name in docs
)
result = Runner.run_sync(agent, "Gradient descent ko ek jumle me samjhao.")
print(result.final_output)
OUTPUT (sample)
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.
<mark>NOTE</mark>
• Do not run run_sync in Colab/Jupyter. A notebook already has an event loop running, so Runner.run_sync gives an error. There, write
result = await Runner.run(agent, "...")
. In a normal .py script, run_sync works fine.
| Agent parameter | Meaning |
|---|---|
name | Name of the agent (shown in tracing) |
instructions | Instructions of the agent: role, rules, limits |
model | Which LLM to use |
tools | The functions the agent can run |
handoffs | The other agents to which work can be given |
output_type | Structured shape of the final answer (Pydantic class) |
handoff_description | Description of this agent, on which another agent decides whether to give it work |
32.5 @function_tool: Making and Testing Tools
In the SDK, making a tool is the easiest part: write a normal Python function (with type hints and docstring) and put @function_tool on it. We make three useful tools. The important rule: test the tool by running it directly before giving it to the agent.
import ast, operator, random
# --- Tool 1:
content of a course week (from the syllabus) ---
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:
"""Tells the content of a course week (29 to 33)."""
return SYLLABUS.get(week, f"Data for week {week} is not with me (only 29 to 33).")
# --- Tool 2:
safe calculator (never eval!) ---
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("only + - * / ** are allowed")
def safe_calculate(expression: str) -> str:
"""Gives the answer of a calculation expression, for example '(5 / 49) * 100'."""
try:
return str(round(_eval(ast.parse(expression, mode="eval").body), 4))
except Exception as e:
return f"Could not calculate: {e}"
# --- Tool 3:
practice question ---
QUIZ = {
"attention": ("Why do we divide by sqrt(d_k) in attention?",
"To stop softmax from saturating"),
"lora": ("What happens to the original weights in LoRA?",
"They stay frozen, only the small A, B are learned"),
}
def make_quiz(topic: str) -> str:
"""Gives a practice question on a topic (attention or lora)."""
item = QUIZ.get(topic.lower())
return item[0]
if item
else "No question for this topic; try attention or lora."
print(course_lookup(32))
print(course_lookup(5))
print(safe_calculate("(5 / 49) * 100"))
print(safe_calculate("__import__('os').system('ls')")) # attack: blocked
print(make_quiz("lora"))
OUTPUT
OpenAI Agent SDK, Tool Integration aur Function Calling
Week 5 data is not with me (only 29 to 33).
10.2041
Could not calculate: only + - * / ** are allowed
What happens to the original weights in LoRA?
<mark>REMEMBER</mark>
Never pass an argument sent by the model into eval() . Text that comes from the model or the user can be dangerous code. The safe_calculate above allows only + - * / and blocks everything else, as seen in the attack line. Now we attach these to the agent as tools. function_tool(...) can be used as a decorator ( @function_tool ) or called directly on a function:
from agents import Agent, Runner, function_tool
study_agent = Agent(
name="Study Buddy",
instructions=(
"Tum course ke student ki madadgar ho. Roman Urdu me jawab do. "
"Course ke mawad ke liye course_lookup, hisaab ke liye safe_calculate, "
"aur mashq ke liye make_quiz tool istemal karo. Khud se hisaab mat karo."
),
tools=[function_tool(course_lookup), function_tool(safe_calculate),
function_tool(make_quiz)],
model="gpt-5.4-mini",
)
question = "Week 32 me kya parhna hai? Aur 49 hafton me se 5 kitne percent hain?"
result = await Runner.run(study_agent, question)
print(result.final_output)
OUTPUT (sample)
Week 32 me OpenAI Agent SDK, Tool Integration aur Function Calling parhna hai.
Aur 49 hafton me se 5 hafte taqreeban 10.2% banate hain.
The agent chose two tools (course_lookup and safe_calculate) by itself and combined their results into the answer. The string returned by a tool goes to the model; so return errors as strings too (as safe_calculate does), so that the agent can understand them and correct itself.
32.6 The Runner's Run Loop
Runner.run(agent, input) runs this loop inside (which we wrote by hand in 32.2):
-
Call the model with the agent's instructions, the input and the tools.
-
If the model gives a final answer, stop and return the
result. -
If the model makes tool calls, run them, add the results to the history, and go back to step 1.
-
If the model makes a handoff, a new agent takes over the loop (32.8).
-
If the loop runs more than
max_turns(default 10), a MaxTurnsExceeded error comes.
Item in**result** | Meaning |
|---|---|
result.final_output | Final answer (text or the object ofoutput_type) |
result.last_agent | The agent that gave the last answer (useful after a handoff) |
result.new_items | All the items made in this run: messages, tool calls, tool |
| outputs | |
result.to_input_list() | Full record of this run, to be used as the input of the next run |
You can set the limit of the loop yourself with Runner.run(agent, input, max_turns=5) . Each tool call costs money and time, so max_turns is also a safety limit.
32.7 Designing Instructions and Structured Output
The instructions of an agent are its "job description". Good instructions include:
-
Role and purpose: "You are a helper for the course student."
-
Rules for tools: "For calculation, always use the calculator tool, do not estimate yourself."
-
Limits: "Only questions related to the course; for others, apologize."
-
Style and language of the answer: "Roman Urdu, fewer than 3 sentences."
-
What to do with an unknown question: "If you don't know, say you don't know; do not lie."
If the agent's answer is needed by other code, give a Pydantic class in output_type . Then result.final_output will be an object, not text:
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="Make a short study plan according to the student's time.",
output_type=StudyPlan,
model="gpt-5.4-mini",
)
result = await Runner.run(planner, "2 weeks, 1 hour a day. I want to learn Transformers.")
plan = result.final_output # StudyPlan object
print(plan.weeks, plan.hours_per_week, plan.topics)
OUTPUT (sample)
2 7 ['Self-Attention', 'Multi-Head aur Positional Encoding', 'Transformer block']
32.8 Multi-Agent: Handoffs and Agents-as-Tools
Instead of teaching one agent everything, make expert agents and divide the work among them. There are two basic ways:
| Handoff | Agent as Tool | |
|---|---|---|
| Control | The task is fully passed to the new agent | The manager agent keeps control |
| Who gives the answer? | The new (specialist) agent talks directly to the user | The manager makes the report, using the specialist's result |
| Example | Sending a patient from reception to a doctor | The manager gets a translator to translate and then writes the report |
| 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="Questions about Python and programming",
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="Questions about statistics and probability",
instructions="Tum statistics ke tutor ho. Roman Urdu me aasan misal do.",
model="gpt-5.4-mini",
)
triage = Agent(
name="Triage",
instructions="Look at the question and hand it to the right tutor. Do not answer yourself.",
handoffs=[python_tutor, stats_tutor],
model="gpt-5.4-mini",
)
result = await Runner.run(triage, "Standard deviation kya hoti hai?")
print("Who answered:", result.last_agent.name)
print(result.final_output)
OUTPUT (sample)
Who answered: Stats Tutor
Standard deviation batati hai ke data apne average se kitna bikhra hua hai ...
The agent-as-tool method: turn the specialist into a tool of the manager:
translator = Agent(
name="Translator",
instructions="Translate Roman Urdu text into clear English.",
model="gpt-5.4-mini",
)
manager = Agent(
name="Manager",
instructions="Use the translate_to_english tool to answer the student.",
tools=[translator.as_tool(
tool_name="translate_to_english",
tool_description="Converts Roman Urdu text into English",
)],
model="gpt-5.4-mini",
)
<mark>NOTE</mark>
• When to use which? When the specialist should continue the conversation with the user, use a handoff. When the specialist only does one helping job and the manager combines everything into the answer, use agent as tool.
32.9 Sessions, Tracing and Guardrails
Sessions: giving the agent memory
Without a session, every Runner.run starts afresh (as in Chapter 31, where you had to send the history yourself). A session stores the history and sends it again automatically:
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") #
for a file:
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 (sample)
Aap ka naam Sara hai.
Tracing: what did the agent do?
The SDK records a trace of every run by itself: which model call happened, which tool, what arguments, what result. It appears in the Traces section of the OpenAI dashboard. For debugging this is very valuable ("why did the agent choose the wrong tool?"). Caution: traces contain prompts and data, so use them carefully with sensitive data (tracing can also be turned off).
Guardrails: protective checks
Guardrails are the checks that run before the agent's input or after its output: for example, "is the question related to the course?", "is there personal data in the answer?". In the SDK there are input guardrails and output guardrails, which stop the run when something wrong is found (tripwire). The details are in the SDK docs; here we understand the idea with a simple Python check (in a real guardrail, a small LLM often makes this decision):
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, "do not send sensitive information"
if not any(k in t for k in TOPICS):
return False, "this question does not seem related to the course"
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, 'do not send sensitive information')
Biryani ki recipe batao -> (False, 'this question does not seem related to the
course')
| Part of the SDK | What it gives? | When is it useful? |
|---|---|---|
| Sessions | Memory of the conversation | Chatbot, tutor, support |
| Tracing | Record of each step | Debugging, monitoring, evaluation |
| Guardrails | Check of input/output | Safety, topic limits, personal data |
Hosted tools (such asWebSearchTool) | Ready-made tools from OpenAI (web search etc.) | Where you do not need to write the tool yourself |
32.10 Mini Project: Study Buddy Agent
Now we put everything together into one small complete project. Goal: an agent that tells the course content, does calculations, gives practice questions, remembers the conversation, and has guardrails for its limits.
| Part | Detail |
|---|---|
| Agent | Study Buddy, Roman Urdu, short answers |
| Tools | course_lookup,safe_calculate,make_quiz(from |
| 32.5, already tested) | |
| Memory | SQLiteSession(a separate id for each student) |
| Guardrail | input_guard(32.9) runs before the agent |
| Loop | Question-answer cycle in Terminal/Colab |
# study_buddy.py (pip install openai-agents; OPENAI_API_KEY must be set)
import asyncio
from agents import Agent, Runner, SQLiteSession, function_tool
# copy course_lookup, safe_calculate, make_quiz and input_guard from the code above
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 (sample)
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
After this, you can: (1) add 10 topics to QUIZ , (2) fill course_lookup with the syllabus of all 49 weeks, (3) make an answer-checking tool ( check_answer ), (4) make a test set of 10 questions and test the agent on it (Chapter 33.7).
32.11 Common Mistakes and Hands-on
<mark>COMMON MISTAKES</mark>
-
<mark>Thinking that the model runs the funct</mark> i <mark>on itself. Your code runs the functon.</mark> i
-
Keeping the tool's name or docstring vague (the model then chooses the wrong tool).
-
Running
eval()or a shell command on the arguments given by the model. -
Throwing an exception from a tool (the agent crashes); return the error as a string.
-
Using
run_syncin Colab (event loop error): writeawait Runner.run(...). -
Not setting
max_turnsor a budget (the agent can get stuck in a loop and burn money). -
Using multi-agent for every task (more cost, more mistakes). Start with one agent.
-
Giving tools more permission than needed (delete, email, payment).
<mark>HANDS-ON</mark>
-
<mark>fake_model: in 32.2, try the queston with</mark> i
lahore<mark>and</mark>multan<mark>; what happened with "multan" and why?</mark> -
Schema: run
schema_from_functionon a function with aboolargument and see the difference inrequired. -
Calculator: add tests for
**and-5tosafe_calculate; show 3 dangerous expressions being blocked. -
Tool: make your own 4th tool (for example
study_plan(hours_per_day: int, weeks: int)) and test it directly. -
Agent: add the 4th tool to Study Buddy (if you have an API key).
-
Handoff: design a triage with three specialist agents (Python, Stats, ML), and write 5 test questions that go to each agent.
<mark>KEY TAKEAWAYS</mark>
-
<mark>Functon calling: the model writes which tool to use (name + JSON arguments); your funct</mark> i i <mark>on runs the code.</mark>
-
The JSON Schema of a tool is made from the name, type hints and docstring; a clear description means correct tool selection.
-
Agent = LLM + tools + loop. The Runner runs the loop until a final answer comes;
max_turnsis a safety limit. -
OpenAI Agents SDK:
Agent(name, instructions, tools, handoffs, output_type, model)andRunner.run -
/ run_sync. -
Test tools directly first, return errors as strings, and never use
eval. -
Handoff (control goes to the other agent) vs agent as tool (manager keeps control).
-
Sessions (memory), Tracing (record) and Guardrails (protective checks) are necessary for production.
-
Start with a simple single agent, then add tools and multi-agent as needed.