AI SDK 7 Chegou O Framework de Agentes que Você Esperava para Produção

Por que o AI SDK 7 é um Marco

Se você já construiu agentes de IA com TypeScript, sabe o pesadelo: cada provedor tem sua própria API para raciocínio, upload de arquivos, contexto de ferramentas e streaming. O AI SDK da Vercel, com mais de 16 milhões de downloads semanais, resolve isso com uma camada unificada. A versão 7 é um salto gigante — não é só uma atualização de biblioteca, é um framework de agentes pronto para produção.

A ideia central: separar o que (sua lógica de agente) do como (a parte específica de cada provedor). Isso permite trocar de modelo, adicionar aprovação humana e observar cada passo sem reescrever seu código.

Vamos mergulhar nas cinco áreas principais: Desenvolver, Executar, Integrar, Observar e Ir Além do Texto.

Desenvolva Agentes com Precisão

Controle de Raciocínio

Modelos de fronteira (OpenAI, Anthropic, Google) suportam raciocínio configurável, mas cada um expõe de forma diferente. O AI SDK 7 padroniza com uma única opção reasoning:

import { generateText } from 'ai';

const result = await generateText({
  model,
  prompt: 'Resolva este problema matemático complexo passo a passo.',
  reasoning: 'high', // mapeia para as configurações nativas do provedor
});

Contexto de Ferramentas e Contexto de Runtime

Ferramentas muitas vezes precisam de chaves de API ou configurações que não devem vazar para o LLM. O AI SDK 7 introduz contextSchema tipado para escopar segredos a ferramentas individuais:

const agent = new ToolLoopAgent({
  model,
  tools: {
    clima: tool({
      description: 'Obter clima para uma cidade',
      inputSchema: z.object({ cidade: z.string() }),
      contextSchema: z.object({ apiKey: z.string() }),
      execute: async (input, { context: { apiKey } }) => {
        // apiKey está escopada apenas para esta ferramenta
      },
    }),
  },
  toolsContext: {
    clima: { apiKey: process.env.WEATHER_API_KEY! },
  },
});

Para loops de múltiplos passos, runtimeContext permite compartilhar estado mutável entre etapas:

const agent = new ToolLoopAgent({
  runtimeContext: { historicoConversa: [] },
  prepareStep: async ({ runtimeContext, steps }) => {
    runtimeContext.historicoConversa.push(steps[steps.length - 1].resultado);
    return runtimeContext;
  },
});

Upload de Arquivos e Skills do Provedor

Fazer upload de arquivos grandes (PDFs, imagens) em toda chamada de inferência é desperdício. As novas APIs uploadFile e uploadSkill permitem enviar uma vez e passar uma referência leve:

const { providerReference } = await uploadFile({
  api: openai.files(),
  data: readFileSync('./foto.png'),
  filename: 'foto.png',
});

const result = await streamText({
  model: openai.responses('gpt-5.5'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Descreva esta imagem.' },
        { type: 'file', mediaType: 'image', data: providerReference },
      ],
    },
  ],
});

MCP Apps e Terminal UI

Apps MCP (Model Context Protocol) agora são cidadãos de primeira classe. Você pode construir apps que expõem tanto ferramentas visíveis ao modelo quanto uma UI em sandbox. Para testes rápidos, o pacote TUI permite executar um agente do terminal sem código de UI:

import { runAgentTUI } from '@ai-sdk/tui';

await runAgentTUI({ agent });
// UI interativa no terminal com raciocínio, ferramentas e renderização de markdown

Execute Agentes com Confiabilidade

Aprovações de Ferramentas & Durabilidade

Para workflows de alto risco, você precisa de supervisão humana. O AI SDK 7 suporta modos de aprovação por ferramenta:

const agent = new ToolLoopAgent({
  model,
  tools: { deletarDatabase: deletarDatabaseTool },
  toolApproval: {
    deletarDatabase: 'user-approval', // requer confirmação manual
  },
});

Para agentes de longa duração, WorkflowAgent oferece durabilidade — seu agente sobrevive a reinicializações de processo, deploys e interrupções. Ele serializa o estado e pode retomar do último passo concluído.

Timeouts & Sandbox

Agentes podem travar. O AI SDK 7 adiciona timeouts granulares:

const result = await generateText({
  model,
  tools: { clima: climaTool, apiLenta: apiLentaTool },
  timeout: {
    totalMs: 60000,
    stepMs: 10000,
    chunkMs: 2000,
    toolMs: 5000,
    tools: { apiLentaMs: 10000 },
  },
  prompt: 'Qual é o clima em São Paulo?',
});

O suporte a sandbox via SandboxSession permite executar agentes em ambientes isolados (como Vercel Sandbox) para execução segura de código.

Integre Qualquer Harness de Agente

Quer usar Claude Code, Codex ou Pi dentro do seu app? O novo HarnessAgent fornece uma interface consistente:

const agent = new HarnessAgent({
  harness: claudeCode,
  sandbox: createVercelSandbox({ runtime: 'node24', ports: [4000] }),
  instructions: 'Você é um assistente de codificação cuidadoso.',
  tools: { lerIssueGitHub, lerPRGitHub },
});

Observe Tudo

Telemetria & Tracing

Registre telemetria uma vez na inicialização:

import { registerTelemetry, generateText } from 'ai';
import { OpenTelemetry } from '@ai-sdk/otel';

registerTelemetry(new OpenTelemetry());

const result = await generateText({
  model: 'google/gemini-3.5-flash',
  prompt: 'Escreva uma história curta sobre um gato.',
  telemetry: { functionId: 'story-agent' },
});

Estatísticas de Performance

Obtenha métricas por etapa como tempo até o primeiro token e tokens por segundo:

const result = streamText({ model: 'openai/gpt-5', prompt: '...' });
for await (const chunk of result.textStream) process.stdout.write(chunk);
const { performance } = await result.finalStep;
console.log({
  responseTimeMs: performance.responseTimeMs,
  outputTokensPerSecond: performance.outputTokensPerSecond,
});

Vá Além do Texto

O AI SDK 7 adiciona suporte a voz em tempo real agnóstico de provedor (WebSocket, funciona com OpenAI, Google, xAI) e geração de vídeo:

import { experimental_generateVideo as generateVideo } from 'ai';

const { videos } = await generateVideo({
  model: 'google/veo-3.1-generate-001',
  prompt: 'Um gato andando em uma esteira',
  aspectRatio: '16:9',
});

Limitações & Cuidados

• Maturidade: Alguns recursos são experimentais (voz em tempo real, geração de vídeo, harnesses). Espere mudanças na API.
• Risco de Lock-in: Embora o SDK abstraia provedores, recursos avançados como uploadSkill só funcionam com endpoints Anthropic/OpenAI que os suportam.
• Curva de Aprendizado: A quantidade de novas abstrações (ToolLoopAgent, WorkflowAgent, HarnessAgent, SandboxSession) pode ser assustadora para iniciantes.
• Overhead de Performance: A camada unificada adiciona leve latência comparada a APIs diretas do provedor para casos de uso simples.

Próximos Passos

1. Atualize: Execute npx @ai-sdk/codemod v7 para migrar da v6 automaticamente.
2. Explore a documentação: Confira a documentação oficial do AI SDK para mergulhos profundos em cada recurso.
3. Construa um agente durável: Comece com WorkflowAgent e adicione aprovações de ferramentas para um assistente do mundo real.
4. Veja inovações similares: Para uma abordagem diferente de assistentes de IA em plataforma, veja como o Agent Lee da Cloudflare redefine a interação em plataforma.

Fonte: Este artigo é baseado no post oficial do blog da Vercel sobre AI SDK 7.