OpenAI Agents SDK · Chapter 1 of 24

Your first agent

By the end of this chapter you can say what an agent is in the OpenAI Agents SDK and what the SDK adds on top of a model, make an agent and run it on a parent's question, give it instructions, say what the Responses API is and read the request the SDK sends, read what a run cost, give an agent another model, and explain why it answers questions about Shikhar confidently and wrongly. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Your first agents
  • 4 tasks
  • Python
  • Free chapter

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.

Why you need this

Shikhar Classes is a JEE and NEET coaching institute in Talwandi, Kota, with about 400 students and its own boys' and girls' hostels. Students and their parents write on WhatsApp all day, in Hindi, Hinglish and English: "JEE ka naya batch kab start hoga?", "fees 10 din late ho gayi, kitna fine lagega?", "girls hostel me AC room khali hai?". Bhanu, who runs student support, answers them between hostel rounds. Kavita, the founder, wants every parent answered fast and correctly: a wrong refund amount or a missed instalment date costs a family real money, and a parent who was told wrong stops trusting the institute.

Karthik, Shikhar's staff AI engineer, will build the helpdesk assistant with the OpenAI Agents SDK, and you build it with him. The Agents SDK is OpenAI's own Python library for agents: a small set of pieces (agents, tools, handoffs, guardrails, sessions) and a runner that drives them, all plain Python. You do not need to have used a model before. This chapter starts at the beginning.

The lesson

A model writes text

A language model is a program trained on a huge amount of text to write what most likely comes next. A chat model continues a conversation: you send messages, it writes the next one. It runs on a server; your program sends it a request and waits for the reply.

Two facts carry this whole lab:

  • The model only writes text. It cannot look up a student's fees or book a doubt session. If it says "your refund is on its way", nothing was sent.
  • It knows only its training text and what you send it. Shikhar's fees, timetable and policy were in neither.

This lab has its own model, lab-chat, running inside your lab with the same API as OpenAI's models. It behaves like a real model for everything the lab teaches; point your code at OpenAI later and the same code talks to a real model.

What an agent is

In the Agents SDK an agent is a model set up for one job: a name, its instructions, the model it uses, and later its tools (functions it can ask your code to run), the type of answer it must give and the other agents it can hand a conversation to. You make an agent once and run it many times. The Runner is what runs it:

from agents import Agent, Runner

agent = Agent(name="Shikhar helpdesk", model="lab-chat")
result = Runner.run_sync(agent, "Does the hostel give meals?")
print(type(result).__name__)
print(result.final_output)
RunResult
Hostel rooms cost ₹8,000 a month, and meals are charged separately.
  • Agent(...) only describes the agent. Nothing is sent when you make it.
  • Runner.run_sync runs the agent once and waits for the answer. (Chapter 7 meets Runner.run, its async twin, and streaming.)
  • It returns a RunResult; result.final_output is the answer.

The package is openai-agents, but you import it as agents. The SDK finds the lab model through two environment variables your lab sets, OPENAI_BASE_URL and OPENAI_API_KEY. Nothing in your code changes when they point at OpenAI instead.

Careful: give the agent its model. Without model=, the SDK asks for OpenAI's current default model, which the lab model does not have:

openai.NotFoundError: Error code: 404 - {'error': {'message': 'The model `gpt-5.6-luna` does not exist or you do not have access to it.', 'type': 'invalid_request_error', 'param': None, 'code': 'model_not_found'}}

The Responses API

OpenAI's models have two APIs for chat. The older one, Chat Completions, takes a list of messages and returns one message. The newer one, the Responses API (POST /v1/responses), is the one OpenAI builds its agent features on: the request carries the instructions on their own, the conversation as a list of input items (messages, and later tool calls and their results), and the response comes back as a list of output items with an id you can point the next request at. The Agents SDK speaks the Responses API by default, and so does the lab model.

lab requests 1 in the terminal shows what the lab model received for the next example, and what it answered (trimmed):

"request": {
  "model": "lab-chat",
  "input": [{"content": "When do test results come out?", "role": "user"}],
  "instructions": "You are Shikhar's helpdesk. Be brief.",
  "tools": []
},
"response": {
  "id": "resp_labf7b400046da4f8bc69661860",
  "status": "completed",
  "output": [{"type": "message", "role": "assistant",
    "content": [{"type": "output_text", "text": "Test results are put up on the notice board every Monday, with every student's rank."}]}],
  "usage": {"input_tokens": 28, "output_tokens": 17, "total_tokens": 45}
}

The agent's name is not in the request: it is for you, the logs and, later, other agents. Your Check reads this same log to see what your code really sent.

Instructions

Instructions tell the model who it is and how to answer. They belong to the agent, so they go where you make it, and travel with every run:

agent = Agent(
    name="Shikhar helpdesk",
    instructions="You are Shikhar's helpdesk. Be brief.",
    model="lab-chat",
)
result = Runner.run_sync(agent, "When do test results come out?")
print(result.final_output)
Test results are put up on the notice board every Monday, with every student's rank.

In the request above, the instructions are the instructions field, sent before the input on every request; the parent's question is the one input item, a message with the role user. The model's answer is the output_text of the one output item, and final_output is that text.

Usage: what a run cost

Models read and write tokens, pieces of words about four characters of English long. Providers charge per token, for what you send (input) and what comes back (output). The response carries the counts, and the SDK adds them up for the whole run on the run's context wrapper, which the result keeps (chapter 5 puts your own data there too):

usage = result.context_wrapper.usage
print(usage.requests, usage.input_tokens, usage.output_tokens)
1 28 17

usage is a value, not a method. requests counts the requests the run made; it is 1 here, and it grows once agents call tools. Instructions are input too, sent on every request, so long instructions cost every time.

A model per agent

The model is part of the agent. To try another model with the same name and instructions, clone the agent: clone() makes a copy with only the fields you give changed.

large = agent.clone(model="lab-chat-large")
print(large.name, large.model)
result = Runner.run_sync(large, "Can my daughter retake a missed test?")
print(result.final_output)
Shikhar helpdesk lab-chat-large
A missed test can be retaken on Monday.

Same instructions, another model. The lab has lab-chat-mini (small and cheap), lab-chat (the everyday one) and lab-chat-large; lab models lists them all with their prices. Chapter 2 also shows how one run can choose the model for every agent in it.

Confident, and wrong

Look at the answers again. "Hostel rooms cost ₹8,000 a month, and meals are charged separately": Shikhar's policy (rule 4.1) charges ₹14,000 a month without AC and ₹18,000 with AC, with three meals a day. "Test results are put up on the notice board every Monday, with every student's rank": rule 3.2 says Tuesday at 6 pm, for the student and the parents only. "A missed test can be retaken on Monday": rule 3.3 says it cannot.

The model is not lying and it is not broken. It never saw Shikhar's policy, so it wrote what such answers usually say, in the confident tone it was trained to use. Every model does this when asked about what it was not given. A parent who believed the first answer would budget for the wrong hostel fee, and one who believed the second would tell their son everyone will see his rank.

So the agent must get Shikhar's facts: tools that look things up (chapter 4), the student it is talking to (chapter 5), and the policy searched for the right rule (chapter 17). That is what this lab builds.

Your turn

Four tasks. Task 1 is your first agent: give it model="lab-chat" and print result.final_output. Task 2 adds instructions and the token counts. Task 3 runs one agent and its clone on two models. Task 4 is an interview question: put the agent's answer about a refund next to rule 2.2 of the policy, and be ready to say why it sounds so sure, and what fixes it.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    first_agent.py: your first agent

    Karthik wants to see what an agent says to a parent's message. Make an Agent from the OpenAI Agents SDK with a name and the lab model, model="lab-chat", run it with the Runner on the parent's question exactly:

    When does the next JEE batch start?

    and print the run's final output, the agent's reply, on one line. Give the agent its model: without one, the SDK asks for OpenAI's default model, which the lab model does not have.

  2. Task 2

    instructions.py: what the agent is, and what it cost

    Make an agent for lab-chat with the instructions: You are Shikhar Classes' helpdesk assistant. Answer in one or two sentences. Run it on the parent's question: Is there a late fee if I pay the instalment late?

    Print the final output, then a second line with the run's tokens from its usage, written as: Tokens: N in, N out (input tokens, then output tokens).

  3. Task 3

    two_models.py: one agent, two models

    Make one agent for lab-chat with the instructions You are Shikhar Classes' helpdesk assistant. and a copy of it for lab-chat-mini made with the agent's clone(). Run the copy, then the agent, on the same question: Do doubt sessions cost extra?

    Do not make a second Agent(...). Print one line per run, in that order: the model's name (lab-chat-mini, lab-chat), a colon and a space, then the final output.

  4. Task 4 · interview question

    Interview: confident.py, confident and wrong

    Run an agent for lab-chat, with no instructions, on: My son wants to leave in the second week. How much of the fees do we get back?

    Then read Shikhar's real rule from /workspace/data/policy.md: the line that starts with 2.2. Print two lines: Model: and the agent's reply, then Policy: and the text of rule 2.2 without its number. Read the rule from the file; do not type it in.

    The interviewer will ask why the agent answers so confidently, and what will fix it.

What you will learn

  • What a model is, and what an agent adds on top of it.
  • Agent and Runner: a question in, a result back, final_output.
  • The Responses API: the request the SDK really sends.
  • Instructions: telling the agent who it is.
  • Usage: what a run cost, in tokens.
  • A model per agent, and a copy of an agent with another one.

More in Your first agents

Build "Your first agent" yourself

Shikhar Classes, a Kota coaching institute, answers parents and students on WhatsApp all day. You build its helpdesk assistant. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.