Installing the Agents SDK

The Agents SDK is a separate package from the base openai package this course has used since Unit 1, installed independently.

pip install openai-agents

Note: The exact package name and installation command can change between versions and providers of agent frameworks built on this platform. Confirm the current package name against the current official documentation before installing it in a real project.

Having both openai and openai-agents installed is normal and expected — the Agents SDK builds on top of the same underlying model and API access this course has used throughout, rather than replacing it. Authentication continues to work the same way Unit 1, Lesson 3 established: an API key available as an environment variable, which the Agents SDK reads the same way the base SDK's client does.

Defining an Agent

An Agent is defined with, at minimum, a name and a set of instructions — conceptually the same instructions parameter Unit 2, Lesson 2 introduced for client.responses.create(), just attached to a reusable object rather than passed fresh on every call.

from agents import Agent

support_agent = Agent(
    name="Support Agent",
    instructions="You help customers with questions about their orders. Be concise and friendly.",
    model="gpt-5.6-terra",
)

The name field isn't just documentation — it's what appears in tracing (Lesson 6) and in handoff-related output (Lesson 4) when multiple agents are involved in a single interaction, so a clear, specific name pays off as soon as a system has more than one agent. The instructions field plays exactly the role Unit 3 established for prompting generally: it's where an agent's persistent behavior, tone, and scope get defined, distinct from the input a specific run provides.

Running an Agent

An agent, once defined, is run against a specific input using the SDK's Runner.

from agents import Agent, Runner

support_agent = Agent(
    name="Support Agent",
    instructions="You help customers with questions about their orders. Be concise and friendly.",
    model="gpt-5.6-terra",
)

result = Runner.run_sync(support_agent, "Where is my order #4471?")
print(result.final_output)

Runner.run_sync() is the synchronous entry point: it blocks until the agent has finished running — potentially after several internal steps, as Lesson 1 described — and returns a result object once a final answer is ready. result.final_output holds the agent's final response, the same underlying value response.output_text gave you in every prior unit's client.responses.create() calls, just accessed through the Agents SDK's own result object rather than the base SDK's response object.

Running an Agent Asynchronously

Real applications, particularly ones serving multiple users concurrently, often need to run agents without blocking the rest of the program while waiting for a response. The Agents SDK provides an async equivalent for exactly this case.

import asyncio
from agents import Agent, Runner

support_agent = Agent(
    name="Support Agent",
    instructions="You help customers with questions about their orders.",
    model="gpt-5.6-terra",
)

async def main():
    result = await Runner.run(support_agent, "Where is my order #4471?")
    print(result.final_output)

asyncio.run(main())

Runner.run() (as opposed to Runner.run_sync()) is a coroutine, following the same synchronous-versus-asynchronous distinction Unit 12 covers in depth for the base SDK's own async client — a synchronous call is simpler to reason about and appropriate for a script or a single-request context, while an asynchronous call is what a production server handling many concurrent requests generally needs, so as not to block on one user's agent run while another user's request is waiting.

What the Result Object Contains

Beyond final_output, a run's result carries additional information about what happened during the run — useful for debugging or for building on top of the interaction rather than just displaying the final text.

result = Runner.run_sync(support_agent, "Where is my order #4471?")

print(f"Final output: {result.final_output}")
print(f"Last agent that responded: {result.last_agent.name}")

Note: The exact fields available on a run's result object, and their names, can vary by SDK version. Confirm the current result object's shape against the current official documentation before relying on a specific field in production code.

result.last_agent matters once handoffs are introduced in Lesson 4: a run might start with one agent and end with a different one after a handoff occurs, and knowing which agent actually produced the final answer is often necessary for logging, analytics, or deciding how to route a follow-up message.

Controlling How Many Steps a Run Can Take

Lesson 1's hand-rolled loop used a max_rounds parameter as a safety cap against a runaway interaction that never produces a final answer. The Runner provides an equivalent safeguard, since an agent that keeps calling tools without ever settling on a final response is just as much a real risk here as it was for the manual loop in Unit 8, Lesson 3.

result = Runner.run_sync(support_agent, "Where is my order #4471?", max_turns=10)

Note: The exact parameter name and default value for limiting the number of steps in a run can vary by SDK version. Confirm the current parameter name and its default against the current official documentation.

This exists for exactly the same reason Unit 8, Lesson 3 introduced max_rounds: without some bound, an agent stuck in a loop — repeatedly calling a tool, never satisfied with the result, never producing a final answer — would otherwise run indefinitely, consuming cost and time with no useful outcome. Setting this explicitly, rather than relying purely on whatever default the SDK ships with, is a reasonable habit for any agent that has access to tools it could plausibly call more than a handful of times.

Comparing an Agent Run to client.responses.create() Directly

It's worth being explicit about what maps to what, since nearly everything here has a direct counterpart from earlier units.

The practical upshot: everything you already know about writing good instructions (Unit 3), choosing an appropriate model (Unit 2, Lesson 5), and reasoning about what a response contains (Unit 2, Lesson 3) transfers directly — the Agents SDK changes how a multi-step interaction is orchestrated, not the underlying skills for getting good output from the model.

Common Mistakes

Treating the Agents SDK as an entirely separate skill from what this course has already covered, rather than recognizing that instructions, models, and the fundamentals of getting good output from the API (Units 1 through 7) apply unchanged.

Using Runner.run_sync() inside a server handling many concurrent requests, blocking the entire process on one user's agent run rather than using the async Runner.run() appropriately.

Ignoring result.last_agent in a system that uses handoffs (Lesson 4), losing track of which specific agent actually produced the final response.

Giving an agent a vague, generic name, making later tracing output (Lesson 6) and multi-agent logs harder to read than they need to be.

Best Practices

Give every agent a clear, specific name, since it appears throughout tracing output and matters immediately once a system involves more than one agent.

Use Runner.run_sync() for scripts and simple, single-request contexts, and Runner.run() for a server handling concurrent requests, following the same synchronous-versus-asynchronous reasoning Unit 12 covers for the base SDK.

Carry forward everything already established about writing effective instructions (Unit 3), since an Agent's instructions field plays exactly the same role as the instructions parameter used throughout Units 1 through 10.

Inspect the full result object, not just final_output, when debugging a multi-agent or multi-step run, since fields like last_agent carry information a single text string doesn't.