add-provider-package

Visão geral da skill add-provider-package

A skill add-provider-package é um guia de implementação focado em criar um novo pacote @ai-sdk/<provider> dentro de vercel/ai. Ela é mais indicada para maintainers, contribuidores e equipes de plataforma de API que querem integrar um provider de modelos ao AI SDK com o formato de pacote certo, o layering adequado de adapters e aderência às convenções do repositório.

O que a add-provider-package realmente ajuda você a fazer

O trabalho real aqui não é apenas “escrever um wrapper”. A skill add-provider-package ajuda você a adicionar um pacote de provider que se encaixa na arquitetura interna do AI SDK, exporta a superfície de provider esperada e segue o layout de pacotes, a estratégia de testes e os padrões de implementação usados no repositório.

Quem deve usar add-provider-package

Use a skill add-provider-package se você está:

• adicionando um novo provider de modelos ao monorepo vercel/ai
• criando um pacote de provider third-party inspirado nos pacotes first-party
• tentando mapear uma API externa para abstrações do AI SDK, como language models ou embeddings
• buscando um caminho concreto além de um prompt genérico do tipo “construa um adapter”

Ela é especialmente útil se você já entende a API HTTP do provider, mas precisa de ajuda para traduzir isso para as convenções de pacote do AI SDK.

Casos de uso com melhor aderência

A add-provider-package skill entrega mais valor quando você precisa:

• criar uma nova pasta packages/<provider> com a estrutura esperada
• implementar classes de provider com base nas interfaces de @ai-sdk/provider
• reaproveitar padrões de providers existentes em vez de inventar sua própria abordagem
• entender as expectativas para first-party vs third-party antes de investir tempo

Principais diferenciais em relação a um prompt genérico de código

Um prompt genérico consegue rascunhar código de adapter. A add-provider-package se torna mais valiosa quando você precisa de orientação sensível ao repositório: onde o pacote deve ficar, como a arquitetura de providers é organizada em camadas, quais arquivos normalmente existem e como um pacote de provider completo deve se parecer neste codebase.

Restrição de adoção mais importante

Essa skill é propositalmente específica. Ela foi feita para criação de pacotes @ai-sdk/<provider>, não para design genérico de SDKs de API, wrappers não relacionados ou sistemas arbitrários de plugins. Se o seu objetivo estiver fora da arquitetura de providers do AI SDK, a skill provavelmente vai parecer específica demais.

Como usar a skill add-provider-package

Contexto de instalação da add-provider-package

Essa skill fica em vercel/ai, em skills/add-provider-package. Em um fluxo com Skills habilitadas, instale com:

npx skills add vercel/ai --skill add-provider-package

Se o seu ambiente já expõe skills de repositório automaticamente, talvez você só precise invocá-la pelo nome.

Comece pelo único arquivo que realmente importa

Leia primeiro skills/add-provider-package/SKILL.md. Este snapshot do repositório mostra que a orientação principal da skill está concentrada ali, incluindo:

• expectativas para pacotes first-party vs third-party
• a arquitetura em camadas dos providers
• estrutura do pacote
• orientação passo a passo de implementação
• um PR de referência com um exemplo completo

Como aqui não aparecem resources/, rules/ nem scripts auxiliares adicionais, a maior parte do sinal útil está em SKILL.md mais os pacotes de provider existentes em outras partes do monorepo.

Que tipo de input a add-provider-package precisa de você

Para obter uma saída útil, forneça detalhes concretos sobre o provider, e não apenas algo como “adicione suporte a X”. Os inputs mínimos mais úteis são:

• nome do provider e alvo do pacote, como @ai-sdk/acme
• método de autenticação da API
• tipos de modelo suportados: chat, completion, embeddings, image etc.
• comportamento de streaming
• schemas de request e response
• formato de erro e comportamento de rate limit
• quaisquer particularidades do provider, como tool calling ou diferenças no modo JSON

Sem esses detalhes, a skill consegue esboçar a estrutura, mas não consegue definir o adapter com segurança.

Como transformar um objetivo vago em um prompt forte

Prompt fraco:

Use add-provider-package to add Acme AI to the SDK.

Prompt melhor:

Use add-provider-package to scaffold a new packages/acme provider for vercel/ai. Acme uses API key auth via Authorization: Bearer <key>. It supports text generation and embeddings, with SSE streaming for text. I need the package structure, main source files, likely exports, and the mapping from Acme endpoints to AI SDK model interfaces. Show the repo files I should create first and call out any ambiguous areas I must resolve from the API docs.

Isso funciona melhor porque dá à skill informação suficiente para escolher a superfície correta de provider e expor cedo os riscos de integração ainda em aberto.

Fluxo de trabalho recomendado para usar add-provider-package

Um fluxo prático de add-provider-package usage é:

1. confirmar se você está mirando um pacote first-party ou third-party
2. ler SKILL.md para entender a arquitetura e o layout de pacote esperado
3. inspecionar o PR de exemplo referenciado: https://github.com/vercel/ai/pull/8136/files
4. comparar um ou dois pacotes de provider existentes em packages/
5. pedir à skill para mapear a API do seu provider para as interfaces do AI SDK antes de gerar arquivos
6. só então pedir um esqueleto de pacote, um plano de implementação e um checklist de testes

Essa sequência reduz retrabalho porque incompatibilidades de interface aparecem antes da geração de código.

Caminhos do repositório para inspecionar depois do SKILL.md

Para tomar decisões reais de implementação, o melhor próximo roteiro de leitura costuma ser:

• skills/add-provider-package/SKILL.md
• o PR de referência linkado dentro da skill
• implementações existentes em packages/<provider>/src/* no monorepo
• interfaces compartilhadas em @ai-sdk/provider
• padrões auxiliares em @ai-sdk/provider-utils

A skill descreve explicitamente essa arquitetura em camadas, então ler essas áreas é a melhor forma de validar o código gerado contra os padrões atuais do repositório.

O que a add-provider-package cobre bem

O add-provider-package guide é mais útil para:

• scaffolding de pacote
• aderência arquitetural dentro do AI SDK
• identificar quais interfaces de provider realmente importam
• entender como modelar um provider como adapter, e não como um client bespoke
• usar a adição de um provider existente como implementação de referência

O que ela não decide por você

A skill não elimina a necessidade de interpretar a documentação da API do provider de origem. Você ainda precisa decidir:

• quais capacidades merecem suporte de primeira classe
• como lidar com opções de request específicas do provider
• quais modelos expor
• como traduzir erros fora do padrão e payloads de streaming
• se recursos não suportados devem ser omitidos ou expostos por trás de opções específicas do provider

Padrões de prompt práticos para add-provider-package em API Development

Se você estiver usando add-provider-package for API Development, peça as saídas na ordem das decisões:

1. mapeamento de capabilities
2. plano de pacote/arquivos
3. plano de types/interfaces
4. plano de transformação de request/response
5. testes e edge cases

Exemplo:

Use add-provider-package to plan an @ai-sdk/zen package. First, map Zen's endpoints to AI SDK interfaces. Second, propose the package file tree. Third, list the core transforms for text generation, embeddings, and streaming. Finally, list the top 10 edge cases to test.

Isso gera um resultado mais implementável do que pedir um dump completo de código logo de início.

Bloqueios mais comuns antes de começar a codar

Os maiores bloqueios normalmente não são erros de sintaxe, e sim decisões de produto que ainda faltam:

• isso deve ser first-party ou third-party?
• a API do provider realmente se encaixa bem nas abstrações do AI SDK?
• os eventos de streaming são estáveis o suficiente para adaptar?
• quais capabilities de modelo já estão maduras o bastante para expor?
• existem providers já implementados com um formato mais próximo que você deveria copiar?

Use a skill cedo para trazer essas perguntas à tona antes de montar o pacote.

FAQ da skill add-provider-package

A add-provider-package é só para maintainers da Vercel?

Não. A skill também é útil para contribuidores externos e autores de pacotes third-party. A fonte distingue explicitamente pacotes third-party de pacotes first-party @ai-sdk/<provider> e observa que adições first-party devem ser discutidas antes.

A add-provider-package é boa para iniciantes?

Ela pode ser usada por iniciantes que já conhecem a API do provider-alvo, mas não é um tutorial introdutório de TypeScript, publicação de pacotes ou design de SDK. O valor dela é maior para quem precisa de orientação específica do repositório e aderência arquitetural.

Em que isso difere de pedir a um LLM para criar um wrapper de provider?

Um prompt comum pode gerar código plausível sem respeitar a estrutura de pacote ou as interfaces do AI SDK. A add-provider-package skill ancora o trabalho na arquitetura de adapters do monorepo e aponta você para uma implementação de referência concreta.

Posso usar add-provider-package fora do repositório vercel/ai?

Sim, como referência de padrão. Mas quanto mais próximo o seu projeto estiver das abstrações de provider e do layout de pacotes do AI SDK, mais transferível será a saída. Se o seu codebase usa interfaces ou convenções de publicação diferentes, espere algum trabalho de adaptação.

Quando eu não devo usar add-provider-package?

Ignore essa skill se você estiver:

• construindo um client de API de propósito geral
• integrando um provider fora do modelo do AI SDK
• procurando exemplos de app frontend em vez de código de pacote de provider
• sem disposição para inspecionar implementações de providers existentes em busca de paridade

A add-provider-package inclui um exemplo completo de ponta a ponta?

Ela inclui uma referência para uma adição completa de provider via PR: https://github.com/vercel/ai/pull/8136/files. Essa é uma das partes mais valiosas da skill, porque mostra como uma adição concluída fica no contexto real do repositório.

Como melhorar a skill add-provider-package

Forneça à add-provider-package inputs no nível de capability

A forma mais rápida de melhorar a qualidade da saída é descrever com precisão as capabilities do provider. Em vez de “suporta chat”, informe:

• nomes dos endpoints
• protocolo de streaming
• suporte a tool calling
• comportamento de structured output
• dimensionalidade dos embeddings ou formato da request
• auth e headers
• particularidades de retry ou rate limit

Isso permite que a skill raciocine sobre aderência de interface em vez de adivinhar com base em termos de marketing.

Peça uma análise de gaps antes da geração de código

Um primeiro passo forte é:

Use add-provider-package to identify the gaps between this provider API and AI SDK expectations before proposing code.

Muitas vezes isso é melhor do que pedir scaffolding imediatamente, porque expõe recursos ausentes, formatos de streaming incompatíveis ou áreas que vão exigir opções específicas do provider.

Faça referência a um provider existente parecido

Se você conhece um provider em vercel/ai com formato de API semelhante, diga isso. Por exemplo:

Use add-provider-package and model this after the provider package that has the closest SSE text streaming and embeddings support.

Isso melhora a consistência e reduz abstrações inventadas.

Peça saída arquivo por arquivo, não um rascunho gigante

A skill fica mais fácil de validar quando você pede:

• árvore do pacote
• exports de src/index.ts
• factory do provider
• arquivos de implementação dos modelos
• testes
• metadados do pacote

Isso torna a revisão mais confiável do que gerar um pacote inteiro de uma vez só.

Modos de falha mais comuns para observar

Ao usar add-provider-package, revise as saídas em busca de:

• capabilities não suportadas sendo expostas como se fossem estáveis
• mapeamento de streaming otimista demais
• opções específicas do provider vazando para interfaces genéricas
• ausência de normalização de erros
• estrutura de pacote que não bate com as convenções existentes do repositório
• código que ignora diferenças de processo entre first-party e third-party

Melhore os prompts com exemplos concretos da API

Se a primeira saída estiver abstrata demais, adicione exemplos reais de request e response da documentação do provider. Esse é um dos ajustes de maior impacto, porque pacotes de provider dependem diretamente da correção das transformações.

Bom prompt de continuação:

Here are the exact JSON request and SSE response shapes for text generation. Revise the add-provider-package plan so the model implementation and streaming parser match these payloads.

Itere explicitando as decisões ainda em aberto

Depois da primeira rodada, peça à skill para separar:

• etapas de implementação com alto grau de confiança
• suposições
• perguntas em aberto que exigem a documentação do provider
• testes prováveis

Essa estrutura torna a skill mais acionável e reduz suposições escondidas.

Melhor forma de validar a saída da add-provider-package

Trate a saída como um plano de implementação sensível ao repositório e depois valide contra:

• SKILL.md
• o PR de referência linkado
• um ou dois pacotes de provider existentes
• interfaces de @ai-sdk/provider
• a documentação oficial da API do provider-alvo

Esse ciclo de validação é a melhor forma de elevar o add-provider-package usage de “rascunho útil” para um pacote que você realmente consegue fazer merge ou publicar.