Choosing an SDK for tool-calling

"The official SDK" sounds like the obviously correct default. In practice, a framework-level SDK that abstracts over multiple model providers can be the more reliable engineering choice — for reasons that have nothing to do with the model itself.

Beginner

3 min read

Two different kinds of SDK

Official provider SDK  - e.g. the vendor's own client library, built
                          and maintained specifically for that
                          provider's API (Anthropic's, OpenAI's, etc.)

Framework-level SDK     - e.g. the Vercel AI SDK, an abstraction layer
                          sitting above multiple providers, offering
                          one consistent interface (streamText, tool
                          definitions, a stop-condition primitive) that
                          works the same way regardless of which
                          underlying model is plugged in

Both are legitimate, real choices — the "official is always more correct" instinct isn't automatically true in practice, and picking between them is a genuine engineering decision, not just a preference.

A real reason to choose the framework-level option: build-tooling compatibility

A team can run into a completely mundane, non-AI-related problem with an official provider SDK: a default-class-import pattern that fails to type-check in a specific build environment (a real, documented instance: TypeScript errors TS2709/TS2351 surfacing specifically in one deployment platform's build pipeline). Switching to a framework-level SDK's provider adapter for that same model resolved the issue entirely, because the abstraction layer's own import pattern didn't trigger the same build-tool quirk. This is a genuinely unglamorous, real-world class of reason to prefer one library over another — completely unrelated to model quality, and easy to underestimate until it actually blocks a deploy.

What a framework-level SDK actually standardizes

streamText({
  model: someProvider("model-name"),
  system: systemPrompt,
  messages: conversationHistory,
  tools: { get_available_slots: toolDefinition, ... },
  stopWhen: stepCountIs(5),
})

One shape for defining tools — name, description, argument schema, an execute function — regardless of which model provider is actually plugged in underneath.
A stop condition primitive (a step-count cap, in the example above) that bounds how many tool-call round-trips a single request is allowed to take before the loop is forced to stop and return whatever it has. Without an explicit cap, a model that keeps deciding it needs "just one more tool call" has no built-in limit, which is a real cost and latency risk, not just a theoretical one.
A consistent streaming interface across providers, so switching models later doesn't mean rewriting the streaming plumbing.

Why "switch providers easily" matters in practice, not just in theory

Products built directly against one vendor's SDK end up with that vendor's specific types, response shapes, and streaming conventions woven through the application code. A framework-level abstraction keeps that provider-specific detail contained to one small adapter layer — swapping a smaller, cheaper model in for a narrow-scope task (a marketing chat widget using a lighter model than a full booking assistant, for instance) becomes a configuration change rather than a rewrite.

This is a build decision, not a permanent architectural commitment

Nothing about choosing a framework-level SDK locks a team out of dropping to a provider's native SDK later for a feature that genuinely needs something the abstraction doesn't expose yet — these choices are worth revisiting as a product's needs change, not treated as irreversible on day one.