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.
Runnerdrives model calls, tool dispatch, and guardrail execution until the model stops calling tools. You never writewhile 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=TrueraisesInputGuardrailTripwireTriggeredand 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
| Dimension | OpenAI Agents SDK | Google ADK | LangGraph |
|---|---|---|---|
| Agent loop | SDK-owned Runner | SDK-owned Runner + events | You own the graph |
| Tool definition | @tool decorator, schema from signature | Plain functions / FunctionTool | @tool from langchain-core |
| State / handoffs | Run result, sessions, handoffs | Sessions keyed by user, sub-agent transfer | Explicit state + checkpointer |
| Guardrails | Tripwire objects, exceptions | Callbacks short-circuiting | Graph nodes |
| Tracing | Built-in, exports to OpenAI platform | Google Cloud / OTel-friendly | LangSmith or your OTel stack |
| Provider coupling | Defaults to OpenAI Responses API; LiteLLM/AnyLLM adapters exist | Gemini-first; model is a string | Model-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
4111check) — trivial to port, but the wiring is per-SDK. - Error handling:
failure_error_functionin 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:
- Add a fourth adapter (PydanticAI is a weekend-sized project) and prove the interface holds.
- Write five eval cases against the
TriageEngineinterface and run them against all adapters — that is your portability regression suite. - Move the guardrail predicate into
core.pyif it is not already, and note how each SDK’s wiring differs. - Replace one adapter’s tracing with OpenTelemetry and observe how much of the SDK’s observability you were renting.