Skip to content
Blog

Building the Same Agent in Three SDKs: A Portability Case Study

Build one support triage agent three times — OpenAI Agents SDK, Google ADK, and LangGraph — then extract a portability checklist for isolating SDK-specific code.

Published on • November 16, 2026

AI Assistant

You picked an agent framework because the demo took twenty minutes. Six months later, procurement wants a second model provider, and suddenly every Runner.run_sync call in your codebase is a decision you have to defend. The uncomfortable truth: agent frameworks leak. The only question is how much of your code is yours versus theirs.

In this post, you will learn how to build the same practical agent — a support triage agent with one tool, structured output, and one guardrail — three times, using the OpenAI Agents SDK, Google ADK, and LangGraph. Along the way you will compare their agent loop abstractions, tool definitions, state and handoff models, guardrails, tracing, and provider coupling, and walk away with a portability checklist plus a pattern for hiding SDK-specific code behind a Protocol.

Prerequisites

  • Python 3.11+ and a virtual environment.
  • API keys for OpenAI and Google (a Gemini key works for ADK; LangGraph can run against either provider).
  • Packages: pip install openai-agents google-adk langgraph langchain-openai pydantic.
  • Working knowledge of Pydantic models and one agent concept: an LLM loop that can call tools.

Nothing here assumes you have used any of the three SDKs before.

The shared task: define the portable core first

Before touching an SDK, write down the contract that must survive a framework swap:

from pydantic import BaseModel, Field

class Triage(BaseModel):
    category: Literal["billing", "bug", "how_to", "other"]
    priority: int = Field(ge=1, le=4)
    summary: str

def lookup_ticket(ticket_id: str) -> dict:
    """Look up a support ticket by ID. Returns id, status, and prior replies."""
    return {"id": ticket_id, "status": "open", "replies": 2}

Triage is your structured output, lookup_ticket is your one tool, and the guardrail’s job is to refuse tickets containing credit-card-like strings before the expensive path runs. That trio — schema, tool, guardrail — is the entire agent. Notice that none of it imports an SDK. Keep it that way; it is the part you will never rewrite.

Implementation 1: OpenAI Agents SDK

The OpenAI Agents SDK markets itself on having very few primitives: agents, handoffs, and guardrails, plus built-in tracing. Tools are plain Python functions — the SDK derives the JSON schema from your signature and docstring using inspect and griffe, and validates arguments with Pydantic:

from agents import Agent, Runner, function_tool
from agents import input_guardrail, GuardrailFunctionOutput

@function_tool
def lookup_ticket(ticket_id: str) -> dict:
    """Look up a support ticket by ID."""
    return {"id": ticket_id, "status": "open", "replies": 2}

@input_guardrail
async def block_card_numbers(ctx, agent, user_input) -> GuardrailFunctionOutput:
    text = user_input if isinstance(user_input, str) else str(user_input)
    return GuardrailFunctionOutput(
        tripwire_triggered="4111" in text,
        output_info={"reason": "possible card number"},
    )

triage = Agent(
    name="Triage",
    instructions="Classify the support ticket. Use lookup_ticket for IDs.",
    tools=[lookup_ticket],
    output_type=Triage,
    input_guardrails=[block_card_numbers],
)

result = Runner.run_sync(triage, "Ticket TK-991 keeps timing out on checkout.")
decision = result.final_output          # validated Triage instance

Key mechanics worth noting:

  • The loop is owned by the SDK. Runner drives model calls, tool dispatch, and guardrail execution until the model stops calling tools. You never write while True.
  • Structured output is output_type=Triage; the final output arrives validated.
  • Guardrails are tripwires. As the guardrails docs describe, an input guardrail returning tripwire_triggered=True raises InputGuardrailTripwireTriggered and halts the run. Input guardrails run in parallel with the agent by default (run_in_parallel=True) or blocking (False) when you must prevent any token spend.

Implementation 2: Google ADK

Google ADK uses the same “agent = instructions + tools” shape but wraps everything in an explicit Runner + session runtime. Tools are again plain functions; guardrails are callbacks rather than tripwire objects:

from google.adk.agents import LlmAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

def guard_input(callback_context) -> types.Content | None:
    text = callback_context.user_content.parts[0].text or ""
    if "4111" in text:
        return types.Content(role="model", parts=[types.Part(text="Refused: sensitive data.")])
    return None  # None lets the agent run normally

triage = LlmAgent(
    name="triage",
    model="gemini-2.5-flash",
    instruction="Classify the support ticket. Use lookup_ticket for IDs.",
    tools=[lookup_ticket],
    output_schema=Triage,
    before_agent_callback=guard_input,
)

service = InMemorySessionService()
runner = Runner(agent=triage, app_name="support", session_service=service)

async def triage_ticket(text: str) -> Triage:
    await service.create_session(user_id="u1", session_id="s1")
    final = None
    async for event in runner.run_async(
        user_id="u1", session_id="s1",
        new_message=types.Content(role="user", parts=[types.Part(text=text)]),
    ):
        if event.is_final_response():
            final = event.content.parts[0].text
    return Triage.model_validate_json(final)

The differences bite quickly: guardrails are callbacks that can short-circuit (return Content and the agent never runs) instead of exceptions; state lives in a session keyed by user_id/session_id rather than in the run result; and the loop is still SDK-owned, but you consume it as an async event stream, which is what you want for UIs and voice pipelines.

Implementation 3: LangGraph

LangGraph inverts the model: you own the graph. Nodes are functions over a TypedDict state, edges decide the next step, and a checkpointer can persist any point in the run. Structured output is wired through a submit tool because you still need the model to call lookup_ticket first:

from typing import TypedDict, Annotated
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def lookup_ticket(ticket_id: str) -> dict:
    """Look up a support ticket by ID."""
    return {"id": ticket_id, "status": "open", "replies": 2}

def submit_triage(category: str, priority: int, summary: str) -> Triage:
    """Emit the final triage decision."""
    return Triage(category=category, priority=priority, summary=summary)

class State(TypedDict):
    messages: Annotated[list, add_messages]

def guard(state: State) -> State:
    if "4111" in str(state["messages"][0].content):
        return {"messages": [{"role": "assistant", "content": "Refused: sensitive data."}]}
    return state

def triage_node(state: State) -> State:
    model = ChatOpenAI(model="gpt-4.1-mini").bind_tools([lookup_ticket, submit_triage])
    return {"messages": [model.invoke(state["messages"])]}

def route(state: State) -> str:
    last = state["messages"][-1]
    if getattr(last, "tool_calls", None):
        return "tools"
    return END

graph = StateGraph(State)
graph.add_node("guard", guard)
graph.add_node("triage", triage_node)
graph.add_node("tools", ToolNode([lookup_ticket, submit_triage]))
graph.add_edge(START, "guard")
graph.add_edge("guard", "triage")
graph.add_conditional_edges("triage", route, {"tools": "tools", END: END})
graph.add_edge("tools", "triage")
app = graph.compile()

app.invoke({"messages": [...]}) returns the full message history; the final submit_triage tool call carries your Triage. The guardrail is just a node — the most portable possible form of the idea.

What actually differs

DimensionOpenAI Agents SDKGoogle ADKLangGraph
Agent loopSDK-owned RunnerSDK-owned Runner + eventsYou own the graph
Tool definition@tool decorator, schema from signaturePlain functions / FunctionTool@tool from langchain-core
State / handoffsRun result, sessions, handoffsSessions keyed by user, sub-agent transferExplicit state + checkpointer
GuardrailsTripwire objects, exceptionsCallbacks short-circuitingGraph nodes
TracingBuilt-in, exports to OpenAI platformGoogle Cloud / OTel-friendlyLangSmith or your OTel stack
Provider couplingDefaults to OpenAI Responses API; LiteLLM/AnyLLM adapters existGemini-first; model is a stringModel-agnostic via langchain-* providers

Two patterns jump out. First, tool definitions are genuinely portable — all three parse Python signatures into JSON schemas, so your tools move untouched. Second, guardrails are the least portable concept: three SDKs, three execution models (exception, callback, node), and semantics that differ under the hood (parallel vs. blocking execution in the Agents SDK, short-circuit returns in ADK, plain control flow in LangGraph).

The portability checklist

Portable (keep SDK-free):

  • Tool functions and their Pydantic/TypedDict schemas.
  • The output contract (Triage) and validation logic.
  • Prompt/instruction text and few-shot examples.
  • Eval datasets — they assert on behavior, not APIs.

Semi-portable (re-express, don’t rewrite):

  • Guardrail predicates (the 4111 check) — trivial to port, but the wiring is per-SDK.
  • Error handling: failure_error_function in the Agents SDK vs. callbacks in ADK vs. node returns in LangGraph.

Not portable (budget real migration work):

  • Runner/session APIs and persistence (ADK sessions, Agents SDK sessions, LangGraph checkpointers).
  • Handoff graphs and sub-agent transfer protocols.
  • Tracing exporters and span conventions.
  • Streaming event types you surface to a UI.

Isolating SDK-specific code behind an interface

The mitigation is boring and effective: define a Protocol at your domain boundary and put each SDK behind an adapter.

from typing import Protocol

class TriageEngine(Protocol):
    async def triage(self, ticket_text: str) -> Triage: ...

class OpenAITriageEngine:
    def __init__(self) -> None:
        self._agent = triage  # the Agent built above

    async def triage(self, ticket_text: str) -> Triage:
        result = await Runner.run(self._agent, ticket_text)
        return result.final_output

def get_engine(provider: str) -> TriageEngine:
    return {"openai": OpenAITriageEngine, "adk": ADKTriageEngine,
            "langgraph": LangGraphTriageEngine}[provider]()

Your application code then depends only on TriageEngine.triage(). Swapping providers becomes a config change, and you can A/B two implementations against the same eval set — which is exactly the leverage you want when procurement asks “can we run this on Gemini?”

Putting It All Together

The final layout separates three layers:

triage/
  core.py        # Triage, lookup_ticket, guard predicate — zero SDK imports
  engines/
    openai.py    # OpenAITriageEngine
    adk.py       # ADKTriageEngine
    langgraph.py # LangGraphTriageEngine
  app.py         # depends only on the TriageEngine Protocol

Run the same ticket through all three and you get the same shape out:

Input: "Ticket TK-991 keeps timing out on checkout."
OpenAI Agents SDK: Triage(category='bug', priority=2, summary='Checkout timeout on TK-991')
Google ADK:        Triage(category='bug', priority=2, summary='Checkout timeout on TK-991')
LangGraph:         Triage(category='bug', priority=2, summary='Checkout timeout on TK-991')

Identical outputs, three different runtimes, one portable core. The adapters are ~30 lines each — a small price for never being captive to a framework’s release notes.

Conclusion and Next Steps

You built one support triage agent three times and discovered the real portability boundary: data contracts and tools travel; runtimes, guardrail wiring, and tracing do not. The fix is structural — keep core.py free of SDK imports and force every framework behind a TriageEngine protocol.

Your homework:

  1. Add a fourth adapter (PydanticAI is a weekend-sized project) and prove the interface holds.
  2. Write five eval cases against the TriageEngine interface and run them against all adapters — that is your portability regression suite.
  3. Move the guardrail predicate into core.py if it is not already, and note how each SDK’s wiring differs.
  4. Replace one adapter’s tracing with OpenTelemetry and observe how much of the SDK’s observability you were renting.