ai-sdk

Visão geral da skill ai-sdk

O que esta skill ai-sdk ajuda você a fazer

A skill ai-sdk é um guia prático para desenvolvedores que estão criando com o AI SDK da Vercel, especialmente quando você precisa de orientação atual, sensível à versão em uso, em vez de conselhos genéricos sobre LLMs. Na prática, ela serve para ajudar você a escolher o formato de API certo, validar a sintaxe mais recente e evitar padrões desatualizados ao adicionar chat, streaming, tools, geração estruturada, embeddings ou agents a uma aplicação.

Quem deve instalar esta skill ai-sdk

Os perfis que mais se beneficiam incluem:

• desenvolvedores full-stack avaliando ai-sdk for Full-Stack Development
• equipes migrando código antigo do AI SDK para APIs mais novas
• desenvolvedores usando generateText, streamText, tools, ToolLoopAgent ou useChat
• quem está comparando configuração de providers entre OpenAI, Anthropic, Google e acesso via gateway
• builders que querem menos tentativas erradas do que com um simples prompt do tipo “write me AI code”

Por que esta skill é mais útil do que um prompt genérico

O principal diferencial é que a skill deixa explícito que o conhecimento interno do modelo sobre o AI SDK costuma estar desatualizado. Em vez de confiar na memória, ela direciona você para a documentação local do pacote, inspeção do código-fonte e referências pontuais como mudanças comuns de API, uso de gateway, devtools e padrões de agents com tipagem segura. Isso torna esta ai-sdk skill mais confiável para decidir se vale instalar e para executar a implementação do que um prompting comum.

O que mais importa antes de adotar

O que normalmente vem primeiro para quem está avaliando:

• se faz sentido instalar apenas ai no começo
• como escolher pacotes de provider depois, em vez de instalar demais logo de início
• quais APIs mudaram recentemente
• se exemplos de useChat encontrados online ainda são válidos
• como depurar tool loops e execuções com streaming
• se o SDK se encaixa em rotas de servidor, interfaces React ou nos dois cenários

Se esses são os seus bloqueios, esta página vai poupar tempo.

Como usar a skill ai-sdk

Comece pelo caminho mínimo de instalação do ai-sdk

Use primeiro o menor passo de instalação possível:

pnpm add ai

A orientação do repositório é intencional aqui: instale primeiro apenas o pacote principal ai. Não adicione imediatamente @ai-sdk/openai, @ai-sdk/react ou outros pacotes de provider/client até que seu caso de uso realmente exija isso. Isso reduz suposições equivocadas e mantém sua implementação alinhada com a documentação atual.

Se você estiver instalando a própria skill do GitHub no seu fluxo de agentes, use:

npx skills add vercel/ai --skill ai-sdk

Verifique a documentação localmente antes de pedir código

O padrão de uso mais importante não é “perguntar de memória”. É este:

1. Confirmar que node_modules/ai/docs/ existe.
2. Pesquisar em node_modules/ai/docs/ e node_modules/ai/src/.
3. Só então recorrer a ai-sdk.dev ou às referências do repositório.

Esse é o comportamento prático mais importante no ai-sdk guide, porque as APIs do AI SDK evoluem rápido e muitos exemplos públicos ficam defasados.

Leia estes arquivos primeiro

Se você quer se situar rapidamente, comece nesta ordem:

1. skills/use-ai-sdk/SKILL.md
2. skills/use-ai-sdk/references/common-errors.md
3. skills/use-ai-sdk/references/ai-gateway.md
4. skills/use-ai-sdk/references/devtools.md
5. skills/use-ai-sdk/references/type-safe-agents.md

Por que essa ordem funciona:

• SKILL.md mostra em que situações acionar a skill e qual fluxo seguir
• common-errors.md ajuda a identificar cedo armadilhas de renomeação de API
• ai-gateway.md acelera o caminho até um modelo funcionando
• devtools.md melhora a depuração quando o código já está rodando
• type-safe-agents.md importa quando tipos de UI e de agent precisam permanecer alinhados

Entenda a divergência atual da API antes de escrever código

Um dos maiores bloqueios de adoção é copiar exemplos antigos. As referências destacam várias mudanças que afetam materialmente o ai-sdk usage:

• maxTokens → maxOutputTokens
• maxSteps → stopWhen: stepCountIs(n)
• parameters em tool → inputSchema
• alguns padrões antigos de geração de objetos mudaram
• useChat mudou bastante e deve ser verificado antes de reutilizar exemplos

Se o seu primeiro prompt para a skill já incluir a versão atual dos pacotes e qualquer código legado, a ajuda para migração tende a ser muito melhor.

Use AI Gateway quando você precisar de uma primeira vitória rápida

Para muitas equipes, o caminho mais rápido é começar com uma configuração baseada em gateway. A skill inclui uma referência útil para Vercel AI Gateway, em que um modelo pode ser selecionado com uma string como:

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  prompt: 'What is love?',
});

Isso ajuda quando sua decisão tem menos a ver com a infraestrutura específica de SDK de provider e mais com validar rapidamente o comportamento do produto.

Antes de fixar qualquer model ID no código, busque a lista atual de modelos. A referência alerta explicitamente para não confiar na memória quando se trata de nomes de modelos.

Que entrada fornecer para a skill ai-sdk

Dê contexto suficiente para que a skill escolha o formato de pacote e o padrão de API corretos. Um pedido forte normalmente inclui:

• runtime: Next.js, Node.js, Vercel, edge/serverless etc.
• objetivo: chat UI, agent, RAG, extração estruturada, tool calling
• versões atuais dos pacotes
• se você precisa de streaming
• preferência por provider ou uso de gateway
• requisitos de frontend, como hooks de React ou uso apenas no servidor
• qualquer código com falha e a mensagem de erro exata

Entrada fraca:

• “Help me use AI SDK”

Entrada forte:

• “I have a Next.js app router project on AI SDK 6, need streaming chat with tool calling, want to start with gateway, and my old useChat code no longer works. Show the minimal server route and UI shape.”

O segundo prompt permite que a skill vá direto para a documentação certa e para os nomes de API atuais.

Transforme um objetivo vago em um prompt melhor para ai-sdk

Uma boa fórmula:

• contexto da aplicação
• experiência de usuário desejada
• estado atual da implementação
• restrições
• formato esperado da resposta

Exemplo:

I'm building a customer-support assistant in Next.js. I need ai-sdk usage for streamed responses, one weather tool, and a React chat UI. Keep packages minimal, prefer gateway first, and explain any AI SDK 6 changes from older examples. Return the file list, install commands, and the smallest working path.

Isso funciona melhor do que pedir “um agent”, porque dá estrutura suficiente para a skill evitar scaffolding genérico.

Escolha o fluxo certo para tarefas comuns

Use a skill de forma diferente conforme o tipo de trabalho:

• Para instalação inicial: peça o conjunto mínimo de pacotes e uma única chamada funcionando
• Para migração: cole o código antigo e peça renomeações de API e mudanças de comportamento
• Para tool calling: peça o formato do schema da tool e as condições de parada
• Para chat no frontend: peça especificamente os padrões atuais de useChat
• Para depuração: pergunte como inspecionar execuções com DevTools e onde os traces ficam armazenados

É nesse prompting orientado à tarefa que a ai-sdk skill entrega mais valor do que uma leitura rápida do repositório.

Use DevTools quando o código roda, mas o comportamento está errado

Quando o código compila, mas o modelo se comporta de forma inesperada, a referência de DevTools tem alto valor. Ela captura chamadas do SDK, steps e interações com tools em:

.devtools/generations.json

Isso é especialmente útil para:

• loops ocultos de tool calls
• saídas estruturadas malformadas
• incompatibilidade entre prompt e tool
• comportamento de streaming confuso
• inspeção de tokens e steps durante execuções de agents

Para decisão de adoção, isso importa porque reduz o custo de depuração depois da instalação inicial.

Use padrões de agents com tipagem segura quando a renderização da UI importa

Se você está construindo uma UI baseada em agents, a referência de agents com tipagem segura é um sinal forte de que a skill vai além de exemplos triviais. Ela mostra um padrão em que definições de agent exportam tipos UIMessage inferidos, tornando a renderização com useChat mais confiável.

Isso é especialmente relevante para ai-sdk for Full-Stack Development, em que a configuração do agent no backend e a renderização de mensagens no frontend precisam permanecer alinhadas.

Casos em que esta skill não é a melhor escolha

Não escolha esta skill se você precisa principalmente de:

• documentação de SDKs específicos de provider sem relação com o pacote ai
• orientação geral de prompt engineering sem trabalho de implementação
• guidance para aplicações de IA com foco principal em Python
• teoria de LLM agnóstica de framework

Esta skill funciona melhor quando sua dúvida é especificamente sobre implementar ou depurar o AI SDK em uma stack JavaScript/TypeScript.

FAQ da skill ai-sdk

Esta skill ai-sdk é boa para iniciantes?

Sim, desde que você já tenha familiaridade com JavaScript ou TypeScript básico. A skill é amigável para iniciantes no sentido de organizar os primeiros passos, mas parte do princípio de que você consegue editar arquivos do projeto, instalar pacotes e seguir convenções do framework.

A skill ai-sdk substitui a leitura da documentação?

Não. Ela funciona melhor como uma camada de direcionamento, dizendo onde olhar e em quais padrões atuais confiar. O valor principal é reduzir desvios e retrabalho, não substituir a documentação-fonte.

Qual é o maior alerta antes da instalação do ai-sdk?

Não confie em exemplos antigos nem na memória do modelo sobre a sintaxe do AI SDK. O repositório reforça repetidamente a importância de verificar primeiro a documentação instalada e o código-fonte. Isso não é um detalhe; é central para um ai-sdk install correto e para uma implementação certa.

Devo instalar todos os pacotes de provider logo de cara?

Em geral, não. Comece com ai e só depois adicione pacotes de provider ou client quando o seu caso de uso realmente exigir. Isso mantém a escolha de dependências intencional e evita carregar suposições desatualizadas para dentro da sua configuração.

Isso serve principalmente para apps de chat?

Não. Chat é um caso comum, mas a skill também se encaixa em geração estruturada, tool calling, agents, embeddings, acesso a modelos via gateway e respostas de servidor com streaming.

Em que isso difere de pedir a um LLM que escreva código com AI SDK?

Um prompt genérico pode gerar APIs obsoletas com confiança total. Esta skill é melhor porque impõe um fluxo de verificação: documentação local, referências atuais, armadilhas conhecidas de migração e leitura direcionada de arquivos. Isso aumenta a confiança e reduz retrabalho.

Ela ajuda com React e useChat?

Sim, mas com uma ressalva: useChat mudou bastante. Trate snippets antigos com desconfiança e use a skill para verificar o formato atual antes de copiar exemplos de UI.

Quando eu não deveria usar este guia ai-sdk?

Evite se o seu problema for principalmente billing de fornecedor, estratégia de avaliação de modelos ou integração com plataformas que não sejam JS. Use quando o seu bloqueio estiver em detalhes atuais de implementação do AI SDK.

Como melhorar o uso da skill ai-sdk

Forneça contexto versionado, não apenas objetivos

A forma mais rápida de melhorar os resultados é incluir versões exatas, especialmente de ai e de quaisquer pacotes relacionados. Muitas falhas acontecem porque a pessoa pede “código com AI SDK” sem dizer se está em uma release mais nova ou migrando código antigo.

Peça primeiro recortes mínimos que funcionem

Melhor do que “construa meu app completo com agent”:

• “show the smallest generateText example”
• “add one tool”
• “then stream it”
• “then wire useChat”

Esse fluxo incremental torna o ai-sdk guide muito mais eficaz, porque cada etapa pode ser conferida na documentação atual antes que a complexidade se acumule.

Mostre os erros literalmente

Se algo quebrar, inclua o erro exato e o trecho relevante. A referência common-errors.md existe porque muitos problemas surgem de nomes de API quase corretos, mas não exatamente. Um erro preciso muitas vezes já diz à skill se você está usando documentação antiga, imports de pacote incorretos ou opções desatualizadas.

Diga se você quer gateway ou configuração direta com provider

Muita ambiguidade desaparece se você especificar logo de início uma destas opções:

• “Use Vercel AI Gateway first”
• “Use direct OpenAI provider package”
• “Keep provider choice abstract for now”

Isso muda comandos de instalação, seleção de modelo e a estrutura dos exemplos.

Seja explícito sobre runtime e limites do framework

Para receber ajuda mais forte com ai-sdk usage, informe:

• somente servidor ou cliente + servidor
• Next.js App Router ou outro framework
• runtime edge ou Node
• nível de rigor do TypeScript
• se as tools chamam APIs internas ou serviços externos

Esses detalhes afetam diretamente o que conta como código “correto”.

Modos de falha comuns para observar

Os principais fatores que derrubam a qualidade são:

• confiar em exemplos antigos de useChat
• copiar nomes de opções já deprecated
• fixar model IDs antigos no código
• instalar pacotes demais cedo demais
• pedir código de agent sem definir tools e condições de parada
• depurar com logs de console em vez de traces de execução

Se você evitar esses pontos, a ai-sdk skill se torna muito mais confiável.

Peça à skill para comparar dois caminhos de implementação

Uma tática forte para melhorar o resultado é pedir uma decisão, não apenas código. Por exemplo:

Compare ai-sdk usage for (A) gateway-first quick setup and (B) direct provider setup in my Next.js app. Recommend one based on fast prototyping, future portability, and minimal package count.

Esse tipo de prompt produz uma orientação de adoção melhor do que “me mostre a documentação”.

Itere após a primeira resposta com evidências

Depois da primeira resposta, melhore a qualidade retornando com um destes itens:

• árvore atual de arquivos
• lista de pacotes instalados
• requisição exata que está falhando
• trecho capturado de .devtools/generations.json
• trecho da documentação local em node_modules/ai/docs/

Essa iteração baseada em evidências é a melhor forma de transformar a ai-sdk skill de uma orientação geral em ajuda realmente útil para implementação.