OpenAI Agents SDK · Chapter 22 of 24
An agent behind an API
By the end of this chapter you can put an agent behind a web API with FastAPI, answer a parent's question on a POST route, stream the answer as it is written with server-sent events, give every request its own student as context and every student a session of their own, and explain why one agent object serves every parent at once. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Production
- 4 tasks
- Python
- In the all labs plan
The first 2 chapters of OpenAI Agents SDK are free. This one comes with the all labs plan.
Why you need this
The helpdesk has lived in scripts you run in a terminal. Parents do not have your terminal. Shikhar's WhatsApp service, the student app and Bhanu's desk tablet all need to reach the assistant the same way: send an HTTP request, get an answer back. Kavita wants all three live before the next batch starts.
An API is a program that waits for requests and answers each one. Many parents write at the same moment, so it answers many at once, and each answer must be about the student who asked. That last part is where an agent behind an API usually goes wrong, and nothing in a one-at-a-time test shows it.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
api.py: a POST route for the agent
Make a FastAPI app named app, and an agent for lab-chat with the instructions You are Shikhar Classes' helpdesk assistant. Answer in one or two sentences. made once at the top of the file.
POST /ask takes a JSON body with one field, message (1 to 500 characters; anything else answers 422 without asking the model). An async route awaits Runner.run on the message and answers {"reply": the final output, "input_tokens": N, "output_tokens": N}, the tokens from the run's usage.
- Task 2
stream.py: stream the answer
Make an app with POST /ask/stream, the same body as task 1, and an agent for lab-chat with the instructions You are Shikhar Classes' helpdesk assistant. The route streams the run's text as server-sent events (text/event-stream): one event per text delta, data: {"text": "<the delta>"} followed by a blank line, then a last event, data: [DONE].
The check joins your pieces and compares them with what the model streamed, and refuses an empty message with 422 before asking the model.
- Task 3
sessions.py: each request's student, each student's session
POST /chat takes {"student_id": ..., "message": ...} (message 1 to 500 characters). For an id that is not a student (not in shikhar.STUDENTS), answer 404 without asking the model. Otherwise make the student's context, a dataclass Student with their id, name and language from shikhar.get_student, and run the agent with it and with that student's own session, answering {"reply": the final output}.
The agent, made once, has dynamic instructions from the context that start You are Shikhar Classes' helpdesk assistant. Use the tools. and name the student and ask for a reply in their language, and a tool fee_status with no parameters that returns json.dumps of shikhar.fee_status for the student in the context. The check asks for S2041 twice, then for S2053: S2041's second request must carry the first message, S2053's must not.
- Task 4 · interview question
Interview: shared.py, what each request must have of its own
shared.py holds an API that was right in testing and told a parent another student's fees on Monday morning. Fix it: make the agent once, at the top level of the file; pass each request's student to the run as its context, so that the instructions (The student is <name>.) and the fee_status tool read it from the run, never from a global; and give each student a session of their own. POST /chat with {"student_id": ..., "message": ...} still answers {"reply": the final output}.
The check sends three students' messages at the same moment, twice. The interviewer will ask: what may every request share, and what must each request have of its own?
What you will learn
- FastAPI in brief: an app, a route, a body checked by Pydantic.
- Async all the way: await Runner.run in an async def route.
- Streaming an answer as server-sent events, from run_streamed.
- Per request: the student as the run's context, the student's own session.
- One agent for every request, and what must never be shared.
More in Production
Build "An agent behind an API" 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.
The first 2 chapters of OpenAI Agents SDK are free. This one comes with the all labs plan.