SDK vs API for AI agents: which interface actually holds up in production

Agent teams keep asking the same question in different words: should we build against the raw API, or should we use the vendor's agent SDK? The framing sounds like a tools question. It's actually a control question — where the retry logic lives, where auth refresh happens, where the schema comes from when the vendor ships a breaking change on a Tuesday.

This piece is for the engineer or architect picking between the two for a production agent. Not a prototype. Something that has to run, keep running, and pass a security review on the way in.

The short version: an agent SDK wins when its abstractions match your control model and the surface is small. The raw API wins when you need control over identity, retries, and schema — which is most established SaaS agent work.

How an agent SDK works

An agent SDK is a client library shipped to make tool calling easier. These fall into two camps worth distinguishing. Vendor-specific SDKs — like Anthropic's Claude Agent SDK — wrap one provider's HTTP API. Provider-agnostic SDKs — like OpenAI's Agents SDK (which supports the OpenAI APIs plus 100+ other LLMs via LiteLLM and custom model providers), LangChain, and CrewAI — abstract across providers. Both camps add opinionated pieces on top of the wire: tool schema formats, message loop management, retry defaults, sometimes streaming and structured output helpers.

The pitch is time-to-first-call. You import a package, define a few tools in the SDK's shape, hand them to a client object, and the SDK handles the request/response cycle. The tool-call loop — model produces a tool call, you execute it, you feed the result back — is either handled for you or reduced to a callback.

What you're actually adopting is a set of abstractions. The SDK decides how a tool schema looks, how errors surface, how retries happen, and how the message history is structured. Some of those decisions match your production reality. Some don't. And when they don't, you're either patching around the SDK or dropping to the underlying API for that specific call — which is when the SDK stops saving you time.

How the raw API works

The raw API is the HTTP contract the model provider actually exposes. Anthropic's Messages API, OpenAI's Responses API, Google's Gemini API. You send a JSON body with messages, tool definitions, and parameters. You get back a response with either a completion or a tool-call request. You execute the tool call yourself. You append the result to the message history and send the next request.

There's no library between you and the wire. You write the HTTP client, the retry policy, the tool-call loop, the schema formatting, the auth refresh, the observability hooks. Everything the SDK would have decided for you is now a decision you make explicitly.

That sounds like more work because it is more work — on day one. The question is whether that work compounds into control you need, or into maintenance you didn't want. For a single-model prototype it's usually the latter. For a multi-product agent that runs as the authenticated user, calls into systems your team owns, and gets audited quarterly, it's usually the former.

How they compare on the dimensions that matter

The pattern in that table is worth naming: the SDK wins on speed and consistency; the raw API wins on control and portability. Neither wins on both. Anyone selling you both is selling something else.

When to choose an agent SDK

Pick the SDK when its assumptions match your reality. Concretely:

• You're prototyping. Getting an agent working end-to-end in an afternoon matters more than architectural purity. Ship it, learn from it, decide later whether to keep the SDK.
• You're single-model and expect to stay that way, or a provider-agnostic SDK covers your models. If Claude or GPT is the answer for the foreseeable future, a vendor SDK's provider lock-in isn't a cost you'll pay. If you need to route across models, a provider-agnostic SDK may still fit — provided its abstraction over model differences matches how you want to work.
• Your tool surface is small and stable. A dozen tools that don't change often fit inside most SDKs comfortably. The SDK's schema format is fine when you're not maintaining 200 tools across a product portfolio.
• Your auth model is simple. If the agent runs as a service account against your own backend, the SDK's default auth handling is usually enough. Once you need to execute tool calls as the authenticated end user — with their permissions and their audit trail — most SDK auth models start to strain.
• You're building on the model provider's platform and want their optimisations. Prompt caching, structured output, streaming — the vendor SDK gets these first and gets them right.

Read the SDK's retry policy and identity model before you commit. If those two match your requirements, the rest usually follows.

When to choose the raw API

Pick the raw API when the control questions matter more than the speed questions. Concretely:

• You need identity to flow to the tool call. Agents in enterprise SaaS almost always need to execute as the authenticated user, not as a shared service account. That means the auth token the agent uses to call the model is different from the credential the tool call executes under. Most agent SDKs don't have a clean seam for this. The raw API does, because you're wiring it yourself. This is the boundary security reviews will demand, and it's the single most common reason teams drop back to the raw API.
• You want provider portability on your own terms. Provider-agnostic SDKs help here, but you're still adopting their view of what a model, a tool, and a message look like. If there's any chance you'll route to different models for different tasks — Claude for reasoning, GPT for structured output, a smaller model for cheap classifications — and you want the seam under your control rather than the SDK's, the raw API keeps it clean.
• Your tool surface is large or changing. Once you have dozens of tools across multiple products, the SDK's schema format becomes a translation layer you didn't want. Owning the schema means you can generate it from your codebase, keep it in sync automatically, and change it without waiting for an SDK release.
• You need production-grade retry, circuit breaking, and observability. SDK defaults are fine for prototypes. Production wants explicit control — exponential backoff tuned to your tool latencies, circuit breakers per downstream, and traces that actually let you debug a failed tool call at 2am.
• You're building infrastructure other teams will use. Wrapping your own agent runtime around the raw API means every team in your organisation gets the same auth, retry, and observability behaviour. Wrapping it around an SDK means you inherit that SDK's opinions and pass them on.

The common thread: raw API when you own the operating conditions.

How Pontil fits

The SDK-vs-API framing usually ends here, with a recommendation and a shrug. That's because the real question isn't which client library to use — it's how to get from a working tool call to a working tool layer that scales across a portfolio of products.

That's the layer Pontil operates on. We're a Tools-as-a-Service platform: we make SaaS products accessible to agents by generating tools from the APIs and codebases you already have, running them through a managed runtime, and keeping them current as your products change. The runtime executes tool calls as the authenticated user, which is the auth model most agent SDKs don't natively support. And because the tools sit behind a stable interface, you can change the model provider — or the client SDK — without rewriting the tool layer underneath.

If you're deciding between raw API and SDK today, the choice matters. If you're deciding how to scale agent tooling across three products and eighteen months, the client library isn't the interesting question. The tools layer is.

What we'd choose

For a prototype: the SDK. Every time. You'll learn faster and the cost of switching later is lower than the cost of over-engineering now.

For production, in the kind of established SaaS environment where agents need to run as authenticated users, call into multiple products, and survive quarterly security reviews: the raw API. Not because SDKs are bad — they're mostly good, and getting better — but because the control seams you need in production are the exact seams SDKs abstract away. When those seams matter, having them under your own instrumentation is worth the extra code.

The honest test: draw the boundary between the agent's identity and the user's identity on a whiteboard. If your SDK has a clean answer for that, use it. If you find yourself explaining the workaround, you've already picked the raw API — you just haven't written the code yet.