Como escolher um SDK de IA: por que o medo de lock-in é um erro e como decidir pelo formato do seu app

Por muito tempo eu fiz uma conta errada na cabeça. Quando ia começar um app com IA, eu descartava o Claude Agent SDK e o Vercel AI SDK quase por reflexo — “esses aí devem estar presos ao provedor deles”, eu pensava. Aí ia de Genkit, achando que era a única opção “livre”. Até o dia em que o launcher do Ollama me mostrou, na cara, que eu estava errado o tempo todo.

A premissa que me custou caro

A pergunta que travava tudo era: “e se um dia eu quiser trocar de modelo? Vou ficar refém da Anthropic / da Vercel?”. Com esse medo, o critério de escolha virava o vendor — e não o problema que eu estava resolvendo. É um erro silencioso, porque ele parece prudência.

O Ollama derrubou a premissa

Rodei o ollama launch e o menu me ofereceu, entre outras coisas, “Launch Claude Code (minimax-m3:cloud)” e “Launch OpenCode”. Repara no detalhe: ele estava prestes a rodar o Claude Code — que usa o Claude Agent SDK por baixo — com um modelo minimax-m3, que não é da Anthropic. Como? Ele só troca o apontamento da URL base.

# É só isto que o launcher do Ollama faz por baixo dos panos:export ANTHROPIC_BASE_URL=http://localhost:11434   # endpoint Anthropic-compat do Ollamaexport ANTHROPIC_MODEL=minimax-m3:cloudclaude            # Claude Code rodando um modelo NÃO-Claude, com subagentes e tudo

Zero código. Um modelo de terceiro rodando sob o harness do Claude Code, só porque o Ollama expõe um endpoint compatível com o protocolo da Anthropic. Se isso vale pro Claude Code, vale pra qualquer app construído sobre o mesmo SDK.

A camada agnóstica existe em todos

Depois dessa ficha cair, fui olhar os outros. Todos têm o mesmo mecanismo fundamental: apontar para um endpoint + uma camada de normalização. Só muda o nome:

“O vendor não é critério. A escolha real é qual batteries-included bate com o formato do app.

— a régua que eu deveria ter usado desde o começo

Os quatro SDKs e o que cada um já traz pronto

Eles não estão no mesmo nível de abstração — e é exatamente isso que decide a escolha. Não é “qual é mais livre” (todos são), e sim “qual já resolve o tipo de app que eu estou construindo”.

claude-agent-sdk — “Claude Code como biblioteca”

É um harness de agente completo. Te dá de graça as cinco primitivas mais chatas de construir: hooks de tool (guard determinístico), aprovação human-in-the-loop, AskUserQuestion como protocolo, subagentes via tool nativa e MCP in-process. Encaixa em: agente de código autônomo com segurança e aprovação.

Genkit — framework de app GenAI

Forte em RAG first-class (retriever/indexer/embedder), flows de orquestração e observabilidade OpenTelemetry com dev UI. Encaixa em: geração de conteúdo, RAG, pipelines, tracing. Foi a escolha certa pro meu editorial — só que pelo motivo errado na época.

pydantic-ai — agentes tipados em Python

Agents e tools tipados, structured output validado por Pydantic, multi-agent. Leve, sem RAG/flows/observabilidade prontos. Encaixa em: lógica de agente tipada. Cheguei a testar no editorial e não encaixou — ele é bateria pra outro formato.

Vercel AI SDK — modelo + tools + provider (+ UI)

streamText/generateText com parts neutras, ToolLoopAgent, a melhor story de provider agnóstico e UI hooks (useChat). Encaixa em: provider-neutro de verdade (OpenAI-native de primeira classe) + integração de UI React.

A régua de decisão

Depois de tudo isso, a pergunta que eu faço hoje, antes de qualquer linha de código, é uma só: qual é o formato do app?

• Agente de código autônomo (segurança, aprovação, subagentes) → claude-agent-sdk

• Conteúdo + RAG + flows + observabilidade → Genkit

• Lógica de agente tipada (Python) → pydantic-ai

• Provider-neutro de verdade + UI → Vercel AI SDK

Bônus: a pegadinha do settingSources

Uma surpresa técnica que vale guardar, se você for de claude-agent-sdk: um agente seu herda o ambiente do Claude Code (hooks, plugins, CLAUDE.md, regras de permissão) mesmo não sendo o Claude Code. E não é por causa da API key — é o default de settingSources.

// sdk.d.ts: "When omitted, all sources are loaded (matches CLI defaults).//           Pass [] to disable filesystem settings (SDK isolation mode)."buildAgentOptions({  // settingSources OMITIDO  -> carrega ~/.claude inteiro (hooks/CLAUDE.md/perms)  settingSources: [],        // <- modo ISOLAMENTO: só as regras do teu app})

O que eu levo pra todo projeto novo

• Vendor não é critério. Todo SDK de agente é agnóstico via base-URL / gateway / plugins.

• Decida pelo formato do app, não pela marca nem pelo medo de lock-in.

• Batteries-included > agnosticismo teórico. O que vem pronto economiza semanas.

• Testar e migrar sem culpa é seleção correta, não erro (foi assim que saí do pydantic-ai pro Genkit num app de conteúdo).

• O reaproveitável é UI/infra, não o motor: extraia chat, streaming e retriever num pacote comum.

A parte boa de descobrir que você estava errado é que a régua que sobra é simples e reutilizável. Não “qual SDK é o melhor” — e sim qual SDK é o melhor pra este app.