Modern agent SDKs

1 · Why another agent framework? essential

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

These frameworks differ less in what they do (loop over a model + tools) than in how much they impose and what they buy you. Read the row you'd reach for first, then read up.

3 · Typed structured output (Pydantic AI shape) essential

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

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

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 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

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