Modern agent SDKs

1 · Why another agent framework? essential

Here's the moment that sends people looking for a framework. You built an agent by hand in Chapter 4 — a loop that calls the model, parses the tool it asked for, runs it, feeds the result back, and repeats. It worked beautifully in the demo. Then the requirements arrived: this reply has to come back as a validated object, not a string you regex; a "billing" question should be handed to a different agent than a "bug report"; a prompt containing a password must never reach the model; and when it misbehaves in production you need to see every step it took, not sprinkle print everywhere. Suddenly your tidy 40-line loop is 400 lines of glue you now have to test and maintain — and none of that glue is your actual product.

Think of it like web servers. You can write raw socket code that parses HTTP by hand, and doing it once teaches you what a request really is. But nobody ships a product that way — they reach for a framework that has already solved the boring, error-prone parts (routing, parsing, sessions) so they can spend their effort on the thing that's actually theirs. Agent SDKs are that same jump for agents: they hand you the repetitive machinery — typed outputs, routing between agents, guardrails, conversation memory, tracing — as a few named primitives, so you write the behaviour and not the plumbing.

So what precisely is an "agent SDK"? It's a library that wraps the model→tool→model loop you already understand and gives its recurring pieces first-class names and types. The newer SDKs — the OpenAI Agents SDK and Pydantic AI — are deliberately small: they picked a handful of concepts (agent, tool, handoff, guardrail, output type, session) and stopped there, betting that fewer ideas you fully understand beats a sprawling toolkit you use 10% of. The word doing the heavy lifting is typed: because your tools and outputs have declared shapes, a whole class of "the model returned something weird and it exploded three functions later" bugs turns into a loud, immediate failure at author time. That is the pitch — not that they do something the raw loop can't, but that they make the parts you'd get wrong hard to get wrong.

The common mistake to name now: beginners assume "OpenAI Agents SDK" means "locked to OpenAI's models" and skip it if they use Claude. That's wrong, and it's worth un-learning before we go further — the SDK reaches Claude and other models through a model adapter, so the name describes who built it, not who you can call.

You already met the raw agent loop (call the model, run a tool, feed the result back, repeat) and the heavier stacks — LangChain/LangGraph and CrewAI/AutoGen. The newer SDKs — OpenAI Agents SDK and Pydantic AI — sit between them: more structure than a hand-written loop, far less machinery than LangChain. Their pitch is typed, lightweight, and few-concepts: a handful of primitives you can hold in your head, with types doing the heavy lifting so bugs surface at author time, not in production.

Two things to fix up front. Despite the name, the OpenAI Agents SDK is provider-agnostic — it runs against Claude and other models through a model-adapter, not just OpenAI. And Pydantic AI is model-agnostic too, built by the Pydantic team around the same validation library that already powers structured outputs across the ecosystem.

2 · The framework landscape essential

The hardest part of this whole topic isn't using any one framework — it's the paralysis of choosing. A new engineer opens the ecosystem and finds a raw loop, LangChain, LangGraph, CrewAI, AutoGen, the OpenAI Agents SDK, Pydantic AI, and a dozen more, each with a landing page insisting it's the one true way. The instinct is to pick the most popular or the most powerful and force every project through it. That's how teams end up running a full stateful-graph engine to answer one FAQ, or hand-rolling routing in a bare loop when a first-class primitive existed. The cure is a map, not a favourite.

Here's the unifying idea that makes the map readable: they all run the same loop underneath — model, tool, result, back to the model. None of them invented a new way to think; they differ only in how much structure they impose and what that structure buys you in return. So instead of memorizing feature lists, place them on a single axis of weight — how much of your code the framework owns. At the light end is the raw loop (it owns nothing; you write everything). At the heavy end sits LangGraph (it owns your control flow as an explicit graph). Everything else lands in between, and the trade is always the same shape: more weight means more done-for-you but more of your code shaped by, and locked to, the framework.

Read the table below as a decision tool, not a leaderboard. The instinct that will serve you: identify your project's single hardest requirement first — "I need validated typed outputs," or "I need one agent to hand a conversation to another," or "my control flow is a genuinely branchy state machine" — then pick the lightest framework whose column already solves that. Weight you don't need is not neutral; it's code you maintain, concepts your teammates must learn, and a bigger rewrite the day you leave. The columns ("Typed?", "Handoffs", "Guardrails") are exactly the recurring needs the rest of this chapter unpacks, so this table doubles as its outline.

3 · Typed structured output (Pydantic AI shape) essential

Every engineer who has parsed an LLM reply by hand knows this pain. You ask the model to "return the urgency and category as JSON," it does — beautifully, ninety-nine times. Then on the hundredth it wraps the JSON in a chatty preamble, or spells urgency "Urgent" instead of "high", or drops the category entirely. Your json.loads and your response["category"] sail right past the check and hand corrupt data to the next function, which stores it, which surfaces it in a dashboard three days later as a silent wrong number. The failure happened at the boundary but detonated far away — the worst kind of bug to trace.

The fix is a discipline you already trust everywhere else: validate untrusted input at the door. A model's reply is untrusted input — it's generated by a probabilistic system you don't control — so you treat it exactly as you'd treat a form submission or an API payload: define the shape you require, and reject anything that doesn't fit before it can travel any further. Think of it as a bouncer with a guest list at the entrance to your program. Nobody malformed gets past the first line.

That's what a typed output means in Pydantic AI, and it's worth being precise about the mechanism because it's easy to under-sell. You don't parse the reply yourself; you declare the type you expect — a schema with named fields and their kinds — and hand it to the agent as its output_type. From then on the SDK makes the model responsible for producing data that validates against that schema, coercing and checking it before your code ever sees it. A field of the wrong type or an out-of-range value raises a validation error at the edge, loudly, where it's cheap to catch — instead of quietly poisoning everything downstream. The name for this is "parse, don't validate later": the boundary is the one place you look, and past it every object is guaranteed well-formed.

In the lab we model that shape with a plain dataclass plus a hand-written check, so it runs offline with no external install — the manual validate function stands in for what Pydantic does automatically. The common mistake it guards against, and the one to watch for in your own code: treating the model's string as if it were already trustworthy. The typed approach flips that assumption; the reply is guilty until it validates.

Pydantic AI's headline feature: you declare the output type, and the agent is responsible for returning data that validates against it — no fragile string parsing. We model that shape with a plain dataclass + manual validation (no external pydantic import) so it runs offline. The real SDK does this for you with a Pydantic model.

typed_output.pyfrom dataclasses import dataclass

@dataclass
class Triage:
    urgency: str      # low | medium | high
    category: str

def validate(d):
    """Stand-in for Pydantic validation: enforce the schema by hand."""
    if d.get("urgency") not in {"low", "medium", "high"}:
        raise ValueError(f"bad urgency: {d.get('urgency')!r}")
    if not d.get("category"):
        raise ValueError("category required")
    return Triage(urgency=d["urgency"], category=d["category"])

def run_agent(ticket):
    """Pretend the model returned this dict; the SDK would coerce+validate it."""
    raw = {"urgency": "high", "category": "billing"} if "refund" in ticket \
          else {"urgency": "low", "category": "general"}
    return validate(raw)

r = run_agent("I need a refund now")
print(type(r).__name__, "->", r.urgency, "/", r.category)
try:
    validate({"urgency": "URGENT", "category": "x"})
except ValueError as e:
    print("rejected:", e)

Triage -> high / billing
rejected: bad urgency: 'URGENT'

pydantic_ai_real.py# needs the SDK:  pip install pydantic-ai
from pydantic import BaseModel
from pydantic_ai import Agent

class Triage(BaseModel):
    urgency: str
    category: str

agent = Agent("anthropic:claude-sonnet-4-5", output_type=Triage)
result = agent.run_sync("I need a refund now")
print(result.output.urgency)   # -> "high"  (validated Triage instance)

4 · Handoffs — one agent routes to another intermediate

You've called a company's support line and heard it: "Press 1 for billing, press 2 for technical support." The first voice you reach isn't there to solve your problem — it's there to figure out who should, and then transfer you. Once you're transferred, that specialist owns the rest of the call; the switchboard is out of the picture. Agents hit the same wall the moment they grow past one job. A single agent stuffed with instructions for billing and refunds and crash reports and shipping becomes a bloated, unreliable generalist — its prompt is a mess, and it's mediocre at everything. The natural fix is the switchboard: a small triage agent that reads the request and routes it to a focused specialist.

A handoff is that transfer made into a first-class primitive. The triage agent doesn't answer the billing question itself — it hands the entire conversation to the billing agent, which takes over and owns the turn from there. The key word is transfers control: after a handoff, the specialist is driving, not the router. That's a genuinely different move from the "sub-agent as a tool" pattern you may have seen, where the caller invokes a helper, gets a value back, and stays in charge — and the note after the lab draws that line sharply, because mixing them up is the classic confusion here.

Why make it a primitive at all, rather than just writing an if/else on keywords like our lab does? Because at real scale the routing logic gets rich — it depends on the model's judgement about the request, not just string matching — and because the SDK can then give you the surrounding machinery for free: it records the handoff in the trace, carries the conversation context across the transfer, and lets the routing be declarative (you list the candidate specialists; the triage agent decides). This sits deliberately between two neighbours you've met: it's more structured than CrewAI's looser message-passing between roles, and lighter than wiring explicit edges in a LangGraph state machine. Our runnable model below strips it to the essence — a triage function returns a target name instead of a final answer, and a tiny harness dispatches to it — including a hops counter, because the one thing that will bite you in routing is agents bouncing a request back and forth forever, so a loop guard is not optional.

The OpenAI Agents SDK makes handoffs a first-class primitive: a triage agent decides which specialist should take over and hands the conversation off to it. That's more structured than CrewAI's message-passing between roles and lighter than wiring LangGraph edges. Model the routing shape: an agent returns a target instead of a final answer, and the harness dispatches to it.

handoff.pydef triage(query):
    """Return either a final answer, or a handoff target for a specialist."""
    q = query.lower()
    if "refund" in q or "charge" in q:
        return ("handoff", "billing")
    if "error" in q or "crash" in q:
        return ("handoff", "tech")
    return ("answer", "Thanks! A general agent can help with that.")

SPECIALISTS = {
    "billing": lambda q: f"[billing] Looking into the charge for: {q!r}",
    "tech":    lambda q: f"[tech] Reproducing the crash for: {q!r}",
}

def run(query, hops=0):
    kind, payload = triage(query)
    if kind == "answer":
        return payload
    if hops > 3:
        return "escalate to human"          # loop guard
    return SPECIALISTS[payload](query)       # hand off to the specialist

for q in ["I want a refund", "the app crashes on login", "what are your hours?"]:
    print(run(q))

[billing] Looking into the charge for: 'I want a refund'
[tech] Reproducing the crash for: 'the app crashes on login'
Thanks! A general agent can help with that.

5 · Guardrails — validate before and after advanced

Picture the two failures that keep an agent's owner up at night. First: a user pastes their password, or a Social Security number, or a prompt-injection payload straight into the chat — and your agent dutifully ships it off to the model, logging sensitive data and burning a paid API call on a request you never should have accepted. Second: the model, having answered, returns a 4,000-word ramble, or a reply containing a slur, or JSON that isn't quite JSON — and your UI renders it, or your parser chokes, in front of a customer. Both are avoidable, and both are avoided in the same place: at the edges of the agent, not inside the prompt.

A guardrail is a check that runs around the agent rather than within it, and the mental model is a factory line with an inspector at each end. The input guardrail inspects the request before it reaches the model: if it violates policy — banned terms, PII, an obviously malicious instruction — it stops the line then and there, which crucially means you never pay for the model call. The output guardrail inspects the reply before it leaves: it can block an unsafe answer, or — and this is the subtler, more useful move — repair it, clamping an over-long response to a length limit or stripping a disallowed field so a fixable problem doesn't become a rejected one.

Why is this a separate concept instead of "just put the rules in the system prompt"? Because a prompt is a request to the model, and the model can ignore it — prompts are persuasion, guardrails are enforcement. A guardrail is your own code, running deterministically outside the model's discretion, so its verdict doesn't depend on the model cooperating. That distinction is the whole reason both SDKs make guardrails first-class: the Agents SDK as explicit input/output guardrail functions (a tripped "tripwire" halts the run), Pydantic AI as validators attached to the output type. The runnable lab models both ends as a guarded wrapper — the classic decorator shape where the input guard, the call, and the output guard nest around any agent function — so you can see that a guardrail is, structurally, nothing more exotic than input validation applied to a model instead of a form.

A guardrail is a check that runs around the agent: an input guardrail can reject a prompt before it costs a model call; an output guardrail can block or repair an unsafe/malformed response. Both SDKs support this — Agents SDK as explicit input/output guardrails, Pydantic AI via validators on the output type. Model a wrapper that enforces both.

guardrail.pyBANNED = {"password", "ssn"}

def input_guard(prompt):
    if any(w in prompt.lower() for w in BANNED):
        raise ValueError("input blocked: sensitive term")
    return prompt

def output_guard(reply):
    if len(reply) > 200:
        return reply[:197] + "..."      # repair: clamp length
    return reply

def guarded(agent):
    """Wrap an agent fn with input + output guardrails."""
    def wrapped(prompt):
        input_guard(prompt)
        return output_guard(agent(prompt))
    return wrapped

agent = lambda p: f"Echo: {p} " + "x" * 300     # a chatty agent
safe = guarded(agent)

print(safe("hello there")[:40], "...len", len(safe("hello there")))
try:
    safe("what is my password")
except ValueError as e:
    print(e)

Echo: hello there xxxxxxxxxxxxxxxxxxxxxx ...len 200
input blocked: sensitive term

6 · Sessions & tracing (Agents SDK) professional

Two things reliably go wrong the first time an agent meets real users, and neither shows up in a demo. The first: a user says "my name is Dana," then in the next message asks "what's my name?" — and the agent has no idea, because each call started from a blank slate. LLMs are stateless; the model remembers nothing between requests unless you re-send the whole conversation every time. The second: the agent gives a bafflingly wrong answer in production, and you have no way to see why — which tool it called, what the model actually returned, where the handoff went. You're left adding print statements and re-running, hoping to reproduce a non-deterministic failure. These are the two problems sessions and tracing solve, and they're exactly the tedious, easy-to-botch parts you'd otherwise hand-roll.

A session is persistent memory for a conversation: it stores the running transcript so each new turn automatically arrives with the earlier turns as context, and it survives across separate calls (and even process restarts, if backed by something like SQLite). Think of it as the difference between a goldfish and a colleague — the goldfish greets you fresh every morning; the colleague remembers yesterday's decision. This is the same long-term-memory problem the memory chapter tackles from scratch, except the SDK hands it to you as one object you thread into each run, so you stop manually rebuilding the message list every turn (and stop getting it subtly wrong).

Tracing is the flight recorder. It captures every step of a run — each model call, each tool invocation, each handoff, each guardrail decision — as a structured, viewable timeline. When something misbehaves, debugging becomes reading the trace instead of guessing: you see the exact point the agent took the wrong branch. This is genuinely the strongest argument for adopting an SDK over your hand-built loop once you're past learning: not that it does more, but that observability comes free. Rebuilding trustworthy tracing by hand is a hundred fiddly lines you'll get wrong under pressure, precisely when you need it most — which is why the tip after the (SDK-only) lab urges you not to try.

Two production affordances the Agents SDK ships out of the box. Sessions persist conversation history so multi-turn state survives across calls (the same problem the memory chapter tackles, handled for you). Tracing records every step — model calls, tool calls, handoffs, guardrail decisions — as a viewable trace, so debugging a misbehaving agent is reading a timeline instead of scattering print statements. This is the real reason to adopt an SDK over a hand-rolled loop at scale: the observability comes free.

agents_sdk_real.py# needs the SDK:  pip install openai-agents
from agents import Agent, Runner, handoff

billing = Agent(name="Billing", instructions="Handle refunds and charges.")
tech    = Agent(name="Tech",    instructions="Handle crashes and errors.")
triage  = Agent(name="Triage", instructions="Route to the right specialist.",
                handoffs=[handoff(billing), handoff(tech)])

# provider-agnostic despite the name: point at any model, e.g. Claude
result = Runner.run_sync(triage, "I want a refund")
print(result.final_output)

7 · Choosing — and the lock-in question tech-lead

Every lead eventually inherits the codebase that answers this section's warning by counter-example. Someone picked the framework that was trending on the day they started, wired its abstractions through every file, and now — two quarters later — that framework is unmaintained, or the team needs a capability it doesn't have, and migrating means rewriting the whole application because the framework is the application. The framework was chosen for its logo, not its fit, and the bill came due. Choosing well is the tech-lead skill this whole chapter has been building toward, and it has two halves: pick for the requirement, and plan for the exit.

The first half is discipline against fashion. Map each candidate to the one need it's best at — raw loop for learning or a single tightly-scoped agent; Pydantic AI when your value is reliable typed outputs and clean dependency injection; OpenAI Agents SDK when you want multi-agent handoffs, guardrails, sessions and tracing with little ceremony; LangGraph when you genuinely have a complex stateful graph; CrewAI/AutoGen for role-playing multi-agent conversations — and when two would fit, take the lighter one, because unused power is pure liability. The runnable selector below encodes exactly this as ordered ifs, which makes the priority explicit: the decision is a policy you can defend, not a vibe.

The second half is the one juniors miss: lock-in is real, and it lives in a specific place. Here's the crucial distinction — the model is swappable (both these SDKs are provider-agnostic, so moving from Claude to another model is a config change), but the framework is not. Its Agent/Runner/handoff types thread through your control flow, so switching frameworks later is a rewrite, not a setting. You can't eliminate that cost, but you can bound it, and the technique is the same one good engineers use for any dependency: keep the framework a thin shell and your value underneath it portable. Concretely — push your domain logic (tool functions, prompts, validation rules, business decisions) into plain functions the framework merely orchestrates. A Pydantic output type and a plain tool function travel to any framework; only the orchestration around them has to be rewritten. Adopt a framework because you need what it adds, keep your logic framework-agnostic, and a future migration stays a bounded job instead of a full stop.

A lead's job here is a deliberate choice, not a fashion follow. Rough guidance: raw loop for learning or a single tightly-controlled agent; Pydantic AI when your value is in reliable typed outputs and clean dependency injection; OpenAI Agents SDK when you want multi-agent handoffs, guardrails, sessions and tracing with little ceremony; LangGraph when you genuinely need a complex stateful graph; CrewAI/AutoGen for role-playing multi-agent conversations. When two fit, prefer the lighter one.

choose_framework.pydef choose(multi_agent, need_handoffs, typed_output, complex_state, learning):
    if learning:
        return "raw loop (Ch04) — understand the mechanics first"
    if complex_state:
        return "LangGraph — you need an explicit stateful graph"
    if multi_agent and need_handoffs:
        return "OpenAI Agents SDK — first-class handoffs + tracing"
    if typed_output:
        return "Pydantic AI — type-safe structured outputs + DI"
    if multi_agent:
        return "CrewAI / AutoGen — role-based multi-agent"
    return "raw loop — one agent, full control"

print(choose(False, False, False, False, True))    # learning
print(choose(True,  True,  False, False, False))    # handoffs
print(choose(False, False, True,  False, False))    # typed
print(choose(False, False, False, True,  False))    # stateful graph

raw loop (Ch04) — understand the mechanics first
OpenAI Agents SDK — first-class handoffs + tracing
Pydantic AI — type-safe structured outputs + DI
LangGraph — you need an explicit stateful graph

On lock-in: an SDK owns your control flow (its Agent/Runner/handoff types thread through everything), so switching later is a rewrite, not a config change. Mitigate it the way you would any dependency — keep your domain logic (tools, prompts, validation, business rules) in plain functions the SDK merely orchestrates, so the framework is a thin shell you can peel off. The typed shapes actually help here: a Pydantic output type or a plain tool function is portable; the orchestration around it is what you'd rewrite.

def choose_framework(need):
    table = {
        "learning / total control":       "Raw loop (Ch04)",
        "complex stateful graph":         "LangChain / LangGraph",
        "multi-agent role play":          "CrewAI / AutoGen",
        "typed multi-agent + handoffs":   "OpenAI Agents SDK",
        "type-safe structured output":    "Pydantic AI",
    }
    return table.get(need, "Raw loop — start simple, add structure only when it hurts")

print(choose_framework("type-safe structured output"))  # Pydantic AI
print(choose_framework("complex stateful graph"))        # LangGraph

from pydantic import BaseModel
from pydantic_ai import Agent

class Ticket(BaseModel):
    category: str
    priority: int      # 1-5
    needs_human: bool

agent = Agent(
    "anthropic:claude-sonnet-4-5",   # model-agnostic; Claude here
    output_type=Ticket,               # output is validated into Ticket
)
result = agent.run_sync("Card declined twice, customer furious.")
print(result.output.category, result.output.priority)   # a validated Ticket

from agents import Agent, Runner

billing = Agent(name="Billing", instructions="Handle refunds and charges.")
tech    = Agent(name="Tech",    instructions="Handle login and errors.")

triage = Agent(
    name="Triage",
    instructions="Route the user to the right specialist.",
    handoffs=[billing, tech],      # first-class: triage can hand off to either
)

result = Runner.run_sync(triage, "I was double-charged for my subscription.")
print(result.final_output)          # answered by the Billing agent after handoff

from agents import Agent, Runner, input_guardrail, GuardrailFunctionOutput

@input_guardrail
def block_pii(ctx, agent, user_input: str) -> GuardrailFunctionOutput:
    contains_ssn = any(part.isdigit() and len(part) == 9
                       for part in user_input.split())
    return GuardrailFunctionOutput(
        output_info={"pii": contains_ssn},
        tripwire_triggered=contains_ssn,      # True -> halt before the model runs
    )

agent = Agent(name="Support", instructions="Help the user.",
              input_guardrails=[block_pii])
# Runner.run_sync raises if the tripwire trips, stopping unsafe input early.

from agents import Agent, Runner, SQLiteSession

agent = Agent(name="Assistant", instructions="Be helpful and remember context.")
session = SQLiteSession("user-123", "conversations.db")  # persisted across runs

# Turn 1
Runner.run_sync(agent, "My name is Dana.", session=session)
# Turn 2 — the session carries the earlier turn's context automatically
r = Runner.run_sync(agent, "What's my name?", session=session)
print(r.final_output)     # knows "Dana" from the persisted session

# Tracing is built in: each run records steps/tool-calls for later inspection.

def evaluate(need, team_wants_types, multi_agent):
    if need == "structured output" and team_wants_types:
        fw, lockin = "Pydantic AI", "LOW — Pydantic models are portable"
    elif multi_agent:
        fw, lockin = "OpenAI Agents SDK", "MEDIUM — handoffs/sessions are SDK-specific"
    else:
        fw, lockin = "Raw loop (Ch04)", "NONE — you own the loop"
    plan = ("keep tool functions + prompts framework-agnostic so the model→tool→model "
            "core ports even if you switch")
    return fw, lockin, plan

fw, lock, plan = evaluate("structured output", team_wants_types=True, multi_agent=False)
print("framework:", fw)
print("lock-in  :", lock)
print("migration:", plan)

Knowledge check check yourself