AI SDK 7: o codemod atualiza a API, mas não prepara seu agente para produção

Tem um momento perigoso em toda migração: o build volta a ficar verde.

Você roda o codemod, corrige meia dúzia de tipos, sobe a versão do Node.js e vê o TypeScript compilar outra vez. A sensação é de trabalho concluído. Só que o seu agente ainda pode passar vinte minutos preso em uma ferramenta, repetir uma ação depois do deploy ou receber uma credencial muito maior do que a tarefa exige.

Nenhuma troca automática de import decide se deleteFile pede aprovação. Também não escolhe o que deve acontecer quando o processo reinicia no meio de uma tarefa, quais dados podem aparecer na telemetria ou quanto tempo uma chamada externa tem para responder.

Esse é o pedaço menos confortável da migração para o AI SDK 7. A parte mecânica cabe em um codemod. A parte operacional continua sendo responsabilidade do time.

O codemod resolve o que tem forma

Codemod é ótimo quando existe uma transformação previsível: um import mudou, uma função ganhou outro nome, uma assinatura precisa ser ajustada. Eu prefiro automatizar esse trabalho a passar uma tarde fazendo substituição manual e torcendo para não esquecer um arquivo.

No AI SDK 7, o piso da migração também inclui Node.js 22 e ESM. Isso precisa funcionar no ambiente inteiro, não apenas no notebook de quem atualizou a dependência. Vale conferir build, testes, imagem de contêiner, funções serverless e deploy antes de seguir.

Ainda assim, compilar prova apenas que o código conversa com a nova API. Não prova que o agente se comporta bem quando algo sai do caminho feliz.

Pensa em duas migrações sobrepostas:

a migração de código, que troca a forma de chamar a biblioteca;
a migração de operação, que define como o agente usa ferramentas, falha, retoma e deixa rastros.

A primeira aceita bastante automação. A segunda exige escolhas, porque cada controle cobra alguma coisa em troca.

Aprovação precisa ter motivo

O AI SDK 7 trouxe políticas de aprovação e revalidação para ferramentas. A tentação é ligar aprovação em tudo e chamar isso de segurança.

Não dura.

Se toda leitura de arquivo, consulta ou chamada reversível abrir uma caixa de confirmação, o humano aprende a clicar sem ler. A aprovação continua presente na interface, mas já perdeu a função.

Eu começaria pelo efeito da ferramenta:

ela altera ou apaga dados?
envia uma mensagem, publica conteúdo ou movimenta dinheiro?
acessa informação sensível?
executa código fora de um ambiente controlado?
consegue ampliar o próprio acesso?

Ferramentas com efeito externo ou difícil de desfazer merecem uma pausa explícita. Operações de leitura e baixo risco podem seguir uma política diferente. O importante é registrar a razão da escolha, não espalhar requiresApproval: true até o lint parar de reclamar.

Também vale testar a recusa. Um agente que só funciona quando todas as aprovações são aceitas não tem política de aprovação; tem um botão decorativo no caminho feliz.

Execução durável muda a arquitetura

Fazer uma tarefa sobreviver a reinício ou deploy parece uma melhoria óbvia. Às vezes é. Mas execução durável não significa apenas "continuar de onde parou".

O estado precisa ser recuperável. As etapas precisam saber se já terminaram. E toda ação externa pede uma resposta para uma pergunta chata: o que acontece se o processo cair depois de enviar a requisição, mas antes de registrar o sucesso?

Sem idempotência, a retomada pode criar duas issues, disparar duas mensagens ou repetir uma cobrança. Sem um identificador estável por ação, você nem consegue distinguir uma repetição segura de uma duplicação acidental.

Nem todo agente precisa desse peso. Uma sugestão curta e descartável pode falhar e recomeçar do zero. Já uma tarefa que passa por várias ferramentas, espera aprovação humana ou atravessa um deploy provavelmente precisa de estado persistido e uma estratégia clara de retomada.

A decisão não é "durável é melhor". É: qual trabalho custa mais caro repetir do que recuperar?

Timeout não é um número mágico

Outro erro comum é escolher um timeout global, colocar 30s em algum lugar e considerar o problema resolvido.

Um limite único mistura coisas diferentes. O agente pode ter um orçamento total de dez minutos, uma etapa de raciocínio de dois minutos e uma chamada HTTP que deveria falhar em cinco segundos. Se tudo herda o mesmo valor, uma ferramenta lenta consome o orçamento inteiro ou uma tarefa legítima morre cedo demais.

Na prática, eu separaria pelo menos três limites:

tempo total da execução;
tempo de uma etapa;
tempo de uma ferramenta externa.

Depois testaria o que o usuário recebe em cada interrupção. "Timeout" sozinho ajuda pouco. O rastro precisa mostrar qual etapa parou, se houve efeito externo antes da parada e se a execução pode ser retomada com segurança.

O limite contém custo e evita tarefa zumbi. Curto demais, vira uma fábrica de falhas artificiais. Longo demais, só adia o incidente.

Telemetria útil sabe o que não guardar

Quando um agente falha, o log que diz apenas tool call failed quase não serve. Você quer saber qual ferramenta rodou, quanto demorou, qual política foi aplicada, se houve nova tentativa e onde a execução terminou.

Só que contexto de agente costuma carregar justamente o que não deveria cair em qualquer painel: prompt completo, conteúdo de arquivo, resposta de cliente, token, URL assinada ou argumento sensível de ferramenta.

Antes de ativar telemetria, eu definiria um envelope pequeno para cada evento:

identificador da execução e da etapa;
nome da ferramenta e duração;
resultado normalizado, como sucesso, recusa, timeout ou erro externo;
quantidade de tentativas;
referência segura ao artefato, quando for necessário investigar mais.

O AI SDK 7 também oferece formas de limitar o contexto e os segredos entregues a cada ferramenta, como runtimeContext e toolsContext. Isso ajuda, mas não substitui revisão. Se uma ferramenta não precisa do token do GitHub nem do histórico inteiro da conversa, esses dados não deveriam chegar até ela.

Observabilidade boa não é copiar tudo para outro lugar. É deixar o suficiente para explicar o incidente sem criar um segundo vazamento.

A credencial faz parte do desenho da ferramenta

Muitos agentes começam do jeito mais rápido: um Personal Access Token amplo em variável de ambiente. Funciona no protótipo e vai ficando. Meses depois, uma ferramenta de revisão ainda consegue escrever em repositórios que nunca deveria enxergar.

O suporte do GitHub Tools ao Vercel Connect mostra outro padrão possível. Em vez de guardar um PAT de longa duração, o agente recebe em runtime um token curto e limitado. Presets como code-review, issue-triage e maintainer agrupam permissões, enquanto repositório, instalação e escopos podem ser estreitados por chamada.

Não precisa usar essa integração específica para aplicar a ideia. A pergunta é a mesma em qualquer stack: qual é a menor credencial que permite esta ferramenta concluir esta tarefa, por quanto tempo ela precisa existir e onde o uso fica registrado?

Token curto reduz o estrago de um vazamento, mas adiciona dependência do fluxo de identidade. Se o emissor ficar indisponível, o agente precisa falhar de forma compreensível. Se o preset estiver amplo demais, a vida curta do token não corrige o excesso de permissão.

Credencial temporária não elimina o trabalho. Ela muda o trabalho de "guardar um segredo para sempre" para "emitir acesso certo na hora certa". Para agente com poder de ação, é uma troca que costuma valer a pena.

Teste a migração quebrando o agente

Depois do build e dos testes normais, eu faria uma rodada curta de falhas provocadas. Nada sofisticado:

inicie uma tarefa com mais de uma etapa e reinicie o processo no meio;
negue a aprovação de uma ferramenta com efeito externo;
force uma chamada a ultrapassar o timeout;
devolva um erro temporário em um serviço externo;
tente usar a credencial em um repositório fora do escopo;
leia os eventos gerados e procure dados que não deveriam estar ali.

O objetivo não é provar que o agente nunca falha. Isso seria fantasia. O objetivo é verificar se ele para no lugar esperado, evita repetir efeitos e deixa informação suficiente para alguém entender o ocorrido.

Se a retomada duplica uma ação, falta idempotência. Se negar uma ferramenta derruba a tarefa inteira sem explicação, falta um caminho de recusa. Se o log resolve o incidente, mas expõe o token usado, a telemetria virou parte do incidente.

É nessa rodada que a migração deixa de ser atualização de dependência e vira preparação para produção.

O build verde é o começo da conversa

Eu gosto de codemods porque eles devolvem tempo ao time. Só não dá para pedir que eles tomem decisões que dependem do risco e da arquitetura do seu produto.

Ao atualizar para o AI SDK 7, feche a parte mecânica, claro. Confirme Node.js 22, ESM, tipos, testes e deploy. Depois trate aprovação, retomada, timeout, telemetria e credenciais como itens verificáveis da migração.

Se a única prova de conclusão é pnpm build, você validou a biblioteca.

O comportamento do agente em produção ainda está esperando review.