Provider SDK or Agent Framework? How to Decide

// In plain English

You've decided to build an AI agent — a program that lets a model call tools, read the results, and keep going until a task is done. Now you face an early fork in the road. You can use the provider's own agent SDK (the toolkit shipped by the company that makes the model — like Anthropic's Claude Agent SDK, the OpenAI Agents SDK, or Google's ADK), or you can use a third-party framework that sits on top of many models (like LangGraph or LangChain). Both build agents. They are not the same kind of thing.

Think of it like building a kitchen. A provider SDK is the appliance brand's own fitted range — built by the same company that makes the stove, perfectly matched to it, and ready the moment you plug it in. A framework is a modular kitchen system from an independent supplier: it works with any brand of appliance, comes with far more cabinets and fittings, but you spend more time deciding how the pieces go together. Neither is "better" — they answer different questions. The provider SDK asks "do you want the smoothest path on one model?" The framework asks "do you want one design that survives swapping the model out?"

// Why it matters

Picking wrong is not catastrophic, but it is expensive to undo. The choice quietly sets your switching cost — how hard it is to change your mind later — and your ceiling — how complex an agent you can build before the tool fights you. Three real pressures push on this decision.

• Vendor lock-in vs best-of-breed. A provider SDK is tuned for one model family. That tuning is a feature on day one and a tax on the day you want to route some requests to a cheaper or faster model from a different vendor. A framework abstracts the model behind a common interface, so swapping is usually a config change — but you pay for that flexibility with an extra layer between you and the model.
• Orchestration complexity. A single "call a tool, loop, answer" agent is easy in either. But once you need branching, parallel sub-agents, human-in-the-loop approval gates, durable state across restarts, or a graph of steps that can retry — frameworks built for orchestration give you those as named primitives. Hand-rolling them on a bare SDK is possible but is work you now own.
• Ecosystem pull. If your team already runs LangChain for retrieval, or you need 200 pre-built integrations to databases and APIs, the framework's ecosystem is a genuine head start. If you need exactly one model and its native tools (web search, code execution, computer use), the provider SDK reaches those first and most reliably, often before any framework wraps them.

Who cares most? Teams shipping a real product, not a demo. A weekend prototype runs fine on whatever you grabbed first. The cost of the wrong choice shows up at month three, when you want to add a second model, or a fifth orchestration branch, and discover your toolkit makes the easy thing easy and the needed thing hard.

// How the two differ under the hood

Both end up making the same kind of HTTP calls to a model and running the same kind of agent loop. The difference is what sits between your code and that loop, and how many models that layer can talk to.

A provider SDK: one model, deepest integration

A provider SDK is built by the model's own maker, so it exposes that model's full feature set first — adaptive thinking, native server-side tools, prompt caching, structured outputs — usually the day those features ship. There is no translation layer guessing how to map a generic concept onto this model. The trade is that it speaks one model family fluently and the others not at all.

A framework: many models, one abstraction

A framework defines its own vocabulary — a "chat model" interface, a "tool" interface, a graph or chain of steps — and writes an adapter for each provider behind it. Your agent logic is written once against the framework's vocabulary; the adapter handles the per-provider wire details. That's what makes the model swappable, and also what adds a layer you must learn and occasionally fight when a provider feature has no clean slot in the abstraction.

Here is the same simple agent expressed against a provider SDK. The model string and the SDK's tool_runner come from the provider; the loop is handled for you.

from anthropic import Anthropic

client = Anthropic()  # reads ANTHROPIC_API_KEY from env

def get_weather(city: str) -> str:
    """Look up the current weather for a city."""
    return f"18C and clear in {city}"

# The SDK's tool runner handles the call -> tool -> result -> loop cycle.
final = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[get_weather],
    messages=[{"role": "user", "content": "What's the weather in Lisbon?"}],
)
print(final)

A framework version of the same agent is written against the framework's model-agnostic interface. The only line that names a vendor is the one that constructs the model — point it at a different provider and the rest is unchanged. That single swappable line is the whole value proposition of the framework, made visible.

// A side-by-side decision table

The fastest way to choose is to score your project on the few axes that actually move the needle. Read each row as "if this is true for me, lean toward this column."

// Common mistakes when choosing

• Reaching for a framework "just in case" you go multi-model — when you never will. If you're confident you'll stay on one model family, the framework's abstraction is pure overhead: a layer to learn, an adapter that can lag the model's newest features, and one more thing in every stack trace. Multi-model optionality is only worth paying for if it's a real plan.
• Picking a provider SDK, then bolting on multi-model with string hacks. Once you find yourself writing if model.startswith("claude"): ... else: ... branches around a provider SDK, you've reinvented a worse framework. That's the signal to adopt a real one.
• Confusing "framework" with "orchestration framework." LangChain (a broad toolkit of components) and LangGraph (a graph-based orchestration engine) solve different problems. If your real need is complex control flow, evaluate the orchestration tool, not the general one.
• Assuming the framework's model abstraction is leak-free. Provider-specific features — a particular thinking mode, a native server tool, a caching trick — often don't map cleanly onto the framework's common interface. You may reach past the abstraction to the raw provider anyway, which dilutes the portability you bought.
• Underestimating native-tool access. Server-side tools like web search, code execution, and computer use are reached most reliably through the provider's own SDK. If those are core to your agent, a framework wrapper may expose them late, partially, or not at all.

// Going deeper

The cleanest mental model is a spectrum of control, not a binary. At one end is a raw API loop — maximum control, you own everything. Next is a provider SDK, which keeps you close to one model while handling the loop, tool dispatch, and that model's native features for you. Further along is a framework, which trades closeness-to-the-metal for portability and orchestration primitives. Knowing where a tool sits on that spectrum tells you what it gives and what it costs — see the agent framework mental models for the full map.

They are not mutually exclusive. A common mature pattern: use a framework for the outer orchestration (the graph of steps, the human approval gate, the durable state) while letting it call a provider's SDK or native features for the inner model work where fidelity matters. The framework supplies the skeleton; the provider SDK supplies the muscle on the one model you most care about.

The decision is reversible, but asymmetrically. Moving from a provider SDK to a framework later is mostly additive — you wrap your existing calls. Moving from a framework back to a bare SDK means unwinding an abstraction your whole codebase assumed. So if you're genuinely unsure and the project is small, starting closer to the metal (provider SDK or even a raw loop) keeps your options more open than starting heavy.

Watch the velocity of native features. Model makers ship new capabilities through their own SDKs first; frameworks wrap them on a delay that varies by how popular the feature is. If your edge depends on being early to a new model capability, the provider SDK is structurally ahead. If your edge depends on orchestration and integrations, the framework is. Match the tool to where your project's hard part actually lives.

Where to go next: compare the major providers' own toolkits in the Claude Agent SDK, OpenAI Agents SDK, and Google ADK explainers; then read the framework side via LangGraph.