AI SDKs - DeveloPassion

# AI SDKs An *AI SDK* is a programmatic library you embed in your application to talk to AI models, orchestrate tool use, and ; in the agent-runtime variants ; run a full plan-act-observe loop. Where a CLI like [[Claude Code]] or [[GitHub Copilot CLI|gh copilot]] is a *user-facing* product, an SDK is the same machinery exposed for *another program* to drive. The term is broader than it looks. There are at least **three distinct layers** of AI SDK, each solving a different problem, and they often get conflated in marketing copy. Knowing which layer you are working at decides everything else: what you control, what you build yourself, what locks you into a single vendor, and what swaps providers with one flag. ## What An AI SDK Actually Provides Every AI SDK, regardless of layer, gives you some subset of: - **Authenticated transport** ; one place that holds your API key, signs requests, retries on transient errors - **Typed request and response shapes** ; the model's input contract as code, not a JSON blob you assemble by hand - **Streaming** ; SSE-based token-at-a-time output, with hooks the SDK exposes as iterators or callbacks - **Tool use plumbing** ; declare functions, the SDK serializes them to the format the model expects, parses tool-call requests, lets you respond - **Structured output** ; constrain the model to return JSON matching a schema (Zod in TS, [[Pydantic]] in Python) - **Observability** ; logprobs, usage tracking, cost attribution, OpenTelemetry traces The differences between SDKs are which of these are first-class, how opinionated the abstractions are, and whether the SDK stops at "talk to a model" or continues into "run an agent loop for you." ## The Three Layers ### 1. Model SDKs (vendor-specific) The thinnest layer. Direct, typed wrappers around one provider's HTTP API. The provider exposes its full surface area ; vendor-specific features (prompt caching, batch APIs, vision, citations) are first-class. The cost is lock-in: writing against the [[Anthropic SDK]] means rewriting to switch to OpenAI. Use this layer when you need a vendor's full feature set, when migration cost across providers is acceptable, or when you intend to build your own provider abstraction. ### 2. Provider-neutral SDKs A unified shape on top of many model SDKs. One `generateText` / `chat.complete` call against [[Anthropic]], [[OpenAI]], [[Mistral AI|Mistral]], Google, [[Groq]], or anything OpenAI-API-compatible. The SDK handles the dialect translation; vendor-specific features are usually exposed through escape hatches. Trade: you lose access to bleeding-edge vendor features the moment they ship, until the abstraction layer catches up. Gain: provider switching becomes a flag, not a refactor. ### 3. Agent-runtime SDKs The thickest layer. Embeds an entire **plan → call tools → observe → iterate** loop, plus the memory, sandboxing, and permissions that make it production-ready. You hand it tools and a prompt; it runs the agent for you. Think of these as "Claude Code as a library" rather than "the model as a library." Use this layer when the *agent behaviour* itself is the asset you want to embed (an autonomous coding agent inside your IDE, a research agent inside your CRM), not just model access. ## Choosing The Right Layer | Goal | Layer | Examples | |------|-------|----------| | Thin chat UI on one provider | Model SDK | [[Anthropic SDK]], [[OpenAI SDK]] | | Thin chat UI, swap providers freely | Provider-neutral | [[Vercel AI SDK]], [[LiteLLM]] | | Multi-agent app with handoffs and tracing | Agent framework | [[OpenAI Agents SDK]], [[Pydantic AI]], [[Mastra AI]], [[Microsoft Agent Framework]] | | Embed Claude Code / Copilot *behaviour* in your app | Agent-runtime SDK | [[Claude Code SDK]], [[GitHub Copilot SDK]] | | Building an agent harness from scratch | Provider-neutral + your own loop | how [[Cook AI Agent]] is built | The most common mistake is reaching for layer 3 when layer 1 + 100 lines of glue would do. The second most common is reaching for layer 1 when you'll inevitably want to swap providers ; do that with [[Vercel AI SDK]] or [[LiteLLM]] from the start. ## Trends Worth Watching - **The provider-neutral layer is consolidating**: in JS, [[Vercel AI SDK]] has won; in Python, [[LiteLLM]] and the [[OpenAI SDK]] (with `base_url` swap) dominate. Most new tooling targets one of these two surfaces. - **Agent runtimes are becoming embeddable**: it used to be that "agent" meant "CLI." The move from [[Claude Code]] → [[Claude Code SDK]] and [[GitHub Copilot]] → [[GitHub Copilot SDK]] reflects vendors realising the *runtime* is the asset, not just the chat surface. - **MCP as the tool standard**: across all three layers, [[Model Context Protocol (MCP)]] is becoming the lingua franca for tool definition. Expect SDKs to lean into MCP rather than reinvent tool schemas. - **Bring-your-own-gateway**: [[Vercel AI Gateway]], [[LiteLLM]] proxy mode, and similar deployments decouple "which provider" from "which SDK" entirely; the SDK talks to the gateway, the gateway routes. - **Typed I/O is winning**: [[Pydantic]] in Python and Zod in TypeScript are moving from "nice-to-have" to "default contract" for tool schemas and structured outputs. ## Known AI SDKs Auto-populated from the `ai/sdk` tag. To add an SDK to this list, tag the note ; do not edit this section.   - [[Anthropic SDK]] - [[Claude Code SDK]] - [[GitHub Copilot SDK]] - [[Google Gen AI SDK]] - [[LiteLLM]] - [[Mastra AI]] - [[Microsoft Agent Framework]] - [[Mistral SDK]] - [[OpenAI Agents SDK]] - [[OpenAI SDK]] - [[Pydantic AI]] - [[Strands Agents]] - [[Vercel AI SDK]]   ## Related - [[AI Agent Harness]] - [[AI Agents]] - [[Model Context Protocol (MCP)]] - [[Anthropic]] - [[OpenAI]] - [[Mistral AI]] - [[Groq]] - [[Vercel AI Gateway]] - [[Bring Your Own Key (BYOK)]] - [[Pydantic]] - [[TypeScript]] - [[Python]]