Skip to main content

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)

  1. You send the question and the list of tools (schema) to the model.

  2. The model decides: should it answer directly or ask for a tool? For a tool, it sends a function_call (name + JSON arguments).

  3. Your code runs the function.

  4. The result goes back to the model as function_call_output.

  5. 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 designBad tool design
Clear name:get_weather,search_courseVague name:do_it,tool1
Short docstring with purpose ("when to use it")Empty or meaningless description
Small tools, one job eachOne 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 parameterMeaning
nameName of the agent (shown in tracing)
instructionsInstructions of the agent: role, rules, limits
modelWhich LLM to use
toolsThe functions the agent can run
handoffsThe other agents to which work can be given
output_typeStructured shape of the final answer (Pydantic class)
handoff_descriptionDescription 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):

  1. Call the model with the agent's instructions, the input and the tools.

  2. If the model gives a final answer, stop and return the result .

  3. If the model makes tool calls, run them, add the results to the history, and go back to step 1.

  4. If the model makes a handoff, a new agent takes over the loop (32.8).

  5. If the loop runs more than max_turns (default 10), a MaxTurnsExceeded error comes.

Item in**result**Meaning
result.final_outputFinal answer (text or the object ofoutput_type)
result.last_agentThe agent that gave the last answer (useful after a handoff)
result.new_itemsAll 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:

HandoffAgent as Tool
ControlThe task is fully passed to the new agentThe 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
ExampleSending a patient from reception to a
doctor
The manager gets a translator to
translate and then writes the report
CodeAgent(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 SDKWhat it gives?When is it useful?
SessionsMemory of the conversationChatbot, tutor, support
TracingRecord of each stepDebugging, monitoring, evaluation
GuardrailsCheck of input/outputSafety, 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.

PartDetail
AgentStudy Buddy, Roman Urdu, short answers
Toolscourse_lookup,safe_calculate,make_quiz(from
32.5, already tested)
MemorySQLiteSession(a separate id for each student)
Guardrailinput_guard(32.9) runs before the agent
LoopQuestion-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_sync in Colab (event loop error): write await Runner.run(...) .

  • Not setting max_turns or 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_function on a function with a bool argument and see the difference in required .

  • Calculator: add tests for ** and -5 to safe_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_turns is a safety limit.

  • OpenAI Agents SDK: Agent(name, instructions, tools, handoffs, output_type, model) and Runner.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.