Usar a API Prompt integrada com o SDK de IA da Vercel

Thomas Steiner

Publicado em 16 de julho de 2026

O SDK de IA da Vercel é um kit de ferramentas TypeScript independente de provedor projetado para ajudar você a criar aplicativos e agentes com tecnologia de IA usando frameworks de interface conhecidos, como Next.js, React, Svelte, Vue, Angular e runtimes como Node.js. Embora a maioria dos provedores seja baseada na nuvem, este primeiro guia de uma série de duas partes se concentra em um provedor da comunidade chamado Browser AI criado por Jakob Hoeg Mørk (que foi financiado pelo Google). O Browser AI permite usar a Prompt API com o SDK de IA da Vercel. A segunda parte da série explica como adicionar uma interface gráfica do usuário ao aplicativo de IA.

Instalar a biblioteca

O @browser-ai/core pacote é o provedor de SDK de IA para a API Prompt. É possível instalá-lo com o npm. O SDK de IA da Vercel subjacente é instalado automaticamente pelo pacote como uma dependência de mesmo nível.

npm install @browser-ai/core

Uso básico

Para usar o provedor:

1. Importe o construtor browserAI do pacote @browser-ai/core.
2. Importe as generateText() ou as streamText() funções do SDK de IA da Vercel. Ambas as funções geram texto e chamam ferramentas para um determinado comando usando um modelo de linguagem:

• A função generateText() não é de streaming e é ideal para saídas curtas ou para saídas em que só é possível continuar depois que toda a saída for recebida.
• A função streamText() transmite gerações de texto de um modelo de linguagem. É possível usar essa função para casos de uso interativos, como chatbots e outros aplicativos em tempo real.

Para criar uma instância de modelo:

1. Chame browserAI(). Observação: como prática recomendada, sempre verifique a availability() do modelo, que permite usar um substituto (consulte Uso híbrido) quando o modelo estiver 'unavailable', ou mostrar uma atualização de progresso quando o modelo for 'downloadable' ou 'downloading'.

2. Em seguida, chame generateText() ou streamText(). Consulte a documentação do SDK de IA da Vercel para conferir a lista completa de parâmetros. Por exemplo, em vez de transmitir um prompt diretamente, como no exemplo de código a seguir, também é possível transmitir um objeto messages mais complexo para comandos de várias etapas ou transmitir um comando system.

import { browserAI } from '@browser-ai/core';
import { generateText, streamText } from 'ai';

(async () => {
  const model = browserAI();
  const availability = await model.availability();

  if (availability === 'unavailable') {
    console.log('Your browser cannot run the built-in AI model.');
    return;
  }

  if (availability === 'downloadable' || availability === 'downloading') {
    await model.createSessionWithProgress((progress) => {
      console.log(`Download progress: ${Math.round(progress * 100)}%`);
    });
  }

  // Non-streaming text generation.
  const { text } = await generateText({
    model,
    prompt: 'Tell me a short joke',
  });
  console.log(text);

  // Streaming text generation.
  const result = streamText({
    model,
    prompt: 'Tell me a long joke',
  });

  for await (const chunk of result.textStream) {
    console.log(chunk);
  }
})();

Uso multimodal

O pacote @browser-ai/core oferece suporte à entrada multimodal usando um type: 'file' objeto nos objetos de conteúdo da matriz messages.

content Campos de objeto (type: 'file')

type

'file'

data

string | Uint8Array | Buffer | ArrayBuffer | URL

Quando data é uma string, ela precisa ser uma destas opções:

Confira o snippet de código a seguir como exemplo:

import { streamText } from 'ai';
import { browserAI } from '@browser-ai/core';

const base64ImageData = await getBase64ImageData();
const audioData = await getAudioBuffer();

const result = streamText({
  model: browserAI(),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: "What's in this image?" },
        { type: 'file', mediaType: 'image/png', data: base64ImageData },
      ],
    },
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Transcribe this audio file!' },
        { type: 'file', mediaType: 'audio/mp3', data: audioData },
      ],
    },
  ],
});

for await (const chunk of result.textStream) {
  console.log(chunk);
}

Resposta estruturada

O SDK de IA da Vercel oferece suporte a saídas estruturadas pelo zod, uma validação de esquema TypeScript com inferência de tipo estático. Consulte a documentação Como definir esquemas do zod para mais detalhes.

Para solicitar um objeto JSON que corresponda ao seu esquema, transmita output: Output.object({ schema }) para generateText() ou streamText():

• generateText() com Output.object() retorna o objeto JSON final no campo output após a conclusão da geração.
• streamText() com Output.object() fornece um iterável assíncrono partialOutputStream em que cada resultado intermediário tem a garantia de ser analisado corretamente como JSON. Por exemplo, se o esquema impuser uma matriz de dois números, você receberá [] como o primeiro resultado parcial, [123] como o segundo e [123, 456] como o resultado final.

import { browserAI } from '@browser-ai/core';
import { generateText, streamText, Output } from 'ai';
import z from 'zod';

const model = browserAI();

const schema = z.object({
  recipe: z.object({
    name: z.string(),
    ingredients: z.array(z.object({ name: z.string(), amount: z.string() })),
    steps: z.array(z.string()),
  }),
});

const prompt = 'Generate a lasagna recipe.';

// Non-streaming object generation.
const { output } = await generateText({
  model,
  output: Output.object({ schema }),
  prompt,
});

console.log(output);

// Streaming object generation.
const { partialOutputStream } = streamText({
  model,
  output: Output.object({ schema }),
  prompt,
});

for await (const partialObject of partialOutputStream) {
  console.log(partialObject);
}

Uso híbrido

O SDK de IA da Vercel se destaca no uso híbrido. Ele fornece uma camada de abstração de nível mais alto sobre as implementações de nível mais baixo dos provedores subjacentes. Ao usar a API Prompt como provedor, você cria um model chamando o construtor browserAI.

import { browserAI } from '@browser-ai/core';

const model = browserAI();

Para usar um provedor diferente, por exemplo, o provedor de IA generativa do Google, faça o seguinte:

1. Instale o provedor selecionado.

   npm install @ai-sdk/google
   

2. Instancie o model usando o construtor do provedor, que, para provedores de nuvem como a IA generativa do Google, normalmente envolve a transmissão de uma chave de API. No caso do provedor de IA generativa do Google, também é possível transmitir um identificador de modelo de nuvem, por exemplo, 'gemini-2.5-flash'. Todo o restante do código, como as chamadas para streamText(), permanece exatamente o mesmo.

   import { createGoogleGenerativeAI } from '@ai-sdk/google';
   
   const API_KEY = 'YOUR_GOOGLE_AI_API_KEY';
   
   const google = createGoogleGenerativeAI({ apiKey: API_KEY });
   const model = google('gemini-2.5-flash');
   

Substituição de nuvem

Um caso de uso híbrido clássico é usar a API Prompt quando ela estiver disponível e fazer o fallback para um provedor de nuvem em outras circunstâncias. Para verificar se a API Prompt está disponível, o pacote @browser-ai/core fornece a função doesBrowserSupportBuiltInAI(). É possível usar essa função para instanciar dinamicamente o model como um modelo baseado na nuvem ou um modelo integrado.

import { doesBrowserSupportBuiltInAI } from '@browser-ai/core';

const API_KEY = 'YOUR_GOOGLE_AI_API_KEY';

const model = await (async () => {
  if (doesBrowserSupportBuiltInAI()) {
    const { browserAI } = await import('@browser-ai/core');
    return browserAI();
  }
  const { createGoogleGenerativeAI } = await import('@ai-sdk/google');
  const google = createGoogleGenerativeAI({ apiKey: API_KEY });
  return google('gemini-2.5-flash');
})();

Fallback integrado

Outro caso de uso híbrido é usar preferencialmente um provedor de nuvem quando estiver on-line, mas fazer o fallback para o provedor integrado se a API Prompt for compatível.

import { doesBrowserSupportBuiltInAI } from '@browser-ai/core';

const API_KEY = 'YOUR_GOOGLE_AI_API_KEY';

let model;

const switchProvider = async (forceCloud = false) => {
  model = await (async () => {
    if (navigator.onLine || forceCloud) {
      const { createGoogleGenerativeAI } = await import('@ai-sdk/google');
      const google = createGoogleGenerativeAI({ apiKey: API_KEY });
      return google('gemini-2.5-flash');
    }
    const { browserAI } = await import('@browser-ai/core');
    return browserAI();
  })();
};

if (doesBrowserSupportBuiltInAI()) {
  window.addEventListener('online', switchProvider);
  window.addEventListener('offline', switchProvider);
}
await switchProvider(true);

Demonstração

A demonstração ao vivo permite testar os dois provedores lado a lado. Selecione API de nuvem (Gemini 2.5 Flash) ou IA integrada nos botões de opção, clique em Executar e observe a página preencher quatro seções em sequência: uma piada curta gerada de uma só vez com generateText(), uma piada longa transmitida token por token com streamText(), uma receita de lasanha retornada como um objeto JSON completo e, em seguida, a mesma receita transmitida como JSON incrementalmente válido usando partialOutputStream. Se você selecionar a IA integrada e o navegador ainda não tiver feito o download do modelo, um indicador de progresso vai aparecer antes do início das demonstrações.

Próxima etapa

Agora que você já sabe como usar a API Prompt com o SDK de IA da Vercel, a próxima etapa é usar a interface do SDK de IA e os elementos de IA para adicionar uma interface gráfica do usuário ao seu app.

A interface do SDK de IA foi projetada para ajudar você a criar aplicativos interativos de chat, conclusão e assistente com facilidade. É um kit de ferramentas independente de framework que simplifica a integração de funcionalidades avançadas de IA aos seus aplicativos.

Os elementos de IA são uma biblioteca de componentes e um registro personalizado para ajudar você a criar aplicativos nativos de IA mais rapidamente. Ele fornece componentes pré-criados, como conversas, mensagens e muito mais.

Leia Usar a interface do SDK de IA da Vercel e os elementos de IA com a API Prompt, para saber como adicionar uma GUI ao seu app.