Vercel AI SDK 6: Agent abstraction, ToolLoopAgent e human-in-the-loop

Resposta atômica: AI SDK 6 introduz a abstração Agent (define modelo, instructions, tools uma vez e reutiliza no app inteiro), a classe ToolLoopAgent (default stopWhen: stepCountIs(20) em vez do antigo 1), needsApproval para human-in-the-loop em tool execution, structured outputs estáveis com tool calling, e DevTools para debugging. Migração via npx @ai-sdk/codemod v6.

O que muda em uma linha

A SDK deixou de tratar agente como helper ad-hoc. Agora é abstração de primeira classe, com lifecycle, configuração reutilizável e telemetria.

Para quem construía agentes encadeando chamadas generateText na mão, isso significa menos código de cola. Para quem já usava Experimental_Agent, a migração é mecânica.

A abstração Agent

import { Agent } from "ai";

const supportAgent = new Agent({
  model: "anthropic/claude-opus-4-7",
  instructions: `
    Você é assistente técnico da COLMEIA. Responde dúvidas sobre
    arquitetura SaaS e produtos digitais. Sempre cita fontes primárias.
  `,
  tools: {
    searchDocs: { /* ... */ },
    bookMeeting: { /* ... */ },
  },
});

const result = await supportAgent.generate({ prompt });
const stream = supportAgent.stream({ prompt });

Define uma vez. Usa em qualquer rota, componente, server action. O agent integra com type-safe UI streaming, structured outputs e os frameworks que a SDK suporta.

A consequência prática: a configuração de agente para de viver espalhada em 8 lugares do código. Vira módulo único com responsabilidade clara.

ToolLoopAgent — a substituição

Quem usava Experimental_Agent precisa migrar para ToolLoopAgent. Três coisas mudaram:

1. Nome da classe: Experimental_Agent → ToolLoopAgent
2. Param renomeado: system → instructions
3. Default mudou: stopWhen: stepCountIs(1) → stopWhen: stepCountIs(20)

A última é a mais importante. Antes, o agente parava após 1 step (tool call) por padrão. Você precisava lembrar de aumentar. Agora 20 é default — apps que dependiam do velho default precisam explicitamente setar stopWhen: stepCountIs(1) para preservar comportamento.

Human-in-the-loop com needsApproval

A feature que mais muda arquitetura de produto: o usuário pode aprovar tool calls antes da execução.

const tools = {
  sendEmail: tool({
    description: "Envia e-mail para o cliente",
    parameters: emailSchema,
    needsApproval: true,
    execute: async (input) => { /* ... */ },
  }),

  searchInternal: tool({
    description: "Busca em documentos internos",
    parameters: searchSchema,
    needsApproval: false,
    execute: async (input) => { /* ... */ },
  }),

  deleteRecord: tool({
    description: "Apaga registro do sistema",
    parameters: deleteSchema,
    needsApproval: (input) => input.scope === "production",
    execute: async (input) => { /* ... */ },
  }),
};

needsApproval aceita boolean ou função que recebe o input. Permite gradação fina: ler é livre, escrever em staging é livre, escrever em produção precisa OK explícito.

A SDK ainda oferece padrão para lembrar aprovações — usuário pode marcar "sempre aprovar X com estes parâmetros" e a próxima ocorrência idêntica passa sem perguntar.

Para produtos que dão poder de execução a agentes (ações em CRM, financeiro, comunicação externa), isso reduz drasticamente o risco de "agente fez X que ninguém queria". Sem ser fricção desnecessária para ações triviais.

Structured outputs estáveis com tool calling

Antes da 6, misturar generateObject (output em schema fixo) com tool calling tinha casos de borda — o modelo às vezes quebrava o schema durante uma sequência de tool calls.

Na 6, o comportamento ficou estável. Agente pode chamar 5 tools, sintetizar o resultado, e devolver objeto que respeita o schema declarado. Em pipelines de extração de dados estruturados, isso simplifica o código que antes precisava de retry + validação manual.

DevTools

A 6 traz DevTools dedicado para inspeção de agente em dev:

• Timeline de steps com latência por chamada
• Tool calls com input/output capturados
• Token usage por step
• Errors agrupados por categoria

Para times que estão construindo agente complexo e debugando comportamento de loop, é a peça que faltava — antes era preciso enxertar logs manualmente.

Migration playbook

Para quem tem app SDK 5 em produção:

1. Rode o codemod:

   npx @ai-sdk/codemod v6
   

2. Audite os defaults: identifique onde dependia implícito stepCountIs(1). Force explicitamente onde precisa.
3. Configure needsApproval nos tools com efeito colateral material. Não deixe para depois — é a maior fonte de risco em produção.
4. Centralize agents em módulos: extraia configurações que estavam espalhadas para arquivos sob lib/agents/. A abstração Agent paga aqui.
5. Ative DevTools em dev e mensure latência por step antes de comprometer arquitetura de produção.

Em projetos médios, a migração leva uma sprint.

A leitura estratégica

A 6 é a release que confirma a SDK como camada de aplicação para agente, não só wrapper de provider. Quem trata como wrapper continua bem, mas perde os ganhos de:

• pricing model previsível
• governance interna (human-in-the-loop padronizado)
• observabilidade (DevTools + telemetria)
• migração de provider (modelos como string)

Em SaaS com IA real em produção, esses quatro itens são o que separa "demo no LinkedIn" de "produto com SLA".

Próximo passo

Para times migrando de SDK 5, construindo agente novo, ou avaliando se vale formalizar a camada de agente: discovery técnico cobre o escopo — auditoria do estado atual, ADR sobre needsApproval policy, plano de migração faseado.

Fontes citadas

1. AI SDK 6 — Vercel Blog · acessado em 2026-05-19
2. AI SDK 5.x to 6.0 Migration Guide · acessado em 2026-05-19
3. AI SDK Documentation · acessado em 2026-05-19