A Vercel lançou a versão 7 de seu AI SDK com um recurso de contexto de ferramenta com escopo (scoped tool context) que força cada ferramenta em um agente de IA a receber apenas os segredos que ela declara explicitamente. Ao limitar a exposição, os desenvolvedores podem impedir que ferramentas de terceiros vejam acidentalmente todas as credenciais armazenadas em seu ambiente.

Por que a mudança é importante

Agentes de IA frequentemente combinam múltiplos serviços externos — consultas de pedidos, criação de tickets, processamento de pagamentos — cada um exigindo suas próprias chaves de API ou URLs. O atalho comum é entregar o objeto process.env inteiro para cada ferramenta:

execute(input, { context: process.env })

Esse padrão cria uma expansão implícita de privilégios: adicionar uma nova ferramenta concede instantaneamente a ela acesso a todos os segredos existentes, incluindo senhas de banco de dados ou tokens de pagamento, sem qualquer sinalização em uma revisão de código. O risco é que uma ferramenta comprometida ou com bugs possa subitamente vazar credenciais que nunca foram destinadas a ela.

Como funciona o contexto de ferramenta com escopo

No SDK 7, uma ferramenta declara um esquema de contexto (context schema) — uma definição baseada em Zod dos campos exatos de que ela precisa. Quando o agente invoca uma ferramenta, o chamador fornece um objeto toolsContext que contém apenas esses campos declarados. O SDK valida a estrutura antes da execução, e quaisquer chaves ausentes ou extras causam um erro.

Uma demonstração mínima mostra duas ferramentas com requisitos distintos:

  • lookupOrder – precisa de baseUrl para chamar um serviço de pedidos interno.
  • createTicket – precisa de supportToken para abrir um ticket de suporte.

Cada ferramenta exporta um contextSchema que lista sua única chave obrigatória. Quando o agente é executado, ele passa:

{
  lookupOrder: { baseUrl: "https://orders.internal" },
  createTicket: { supportToken: "s3cr3t-token" }
}

Apenas o lookupOrder vê o baseUrl; o createTicket nunca o acessa, e vice-versa. O SDK impõe esse limite em tempo de execução, transformando uma dependência oculta em uma lista de capacidades explícitas que os revisores podem auditar.

Vantagens de segurança

  • Limita a exposição de dados – as credenciais permanecem onde são necessárias.
  • Valida o contexto – campos incompatíveis ou ausentes abortam a execução.
  • Torna as capacidades explícitas – os revisores podem ver exatamente o que cada ferramenta pode acessar.
  • Reduz o raio de impacto – se uma ferramenta for comprometida, o invasor só obtém os segredos que aquela ferramenta tinha permissão para acessar.

O recurso não substitui o sandboxing tradicional. Os desenvolvedores ainda devem empregar redação de logs, controles de saída de rede e rotação regular de tokens. O contexto com escopo é um limite; ele não sela a sala.

O que os desenvolvedores precisam ajustar

  1. Defina um esquema para cada ferramenta – use a biblioteca Zod que vem com o SDK.
  2. Passe um toolsContext restrito – evite o uso genérico do process.env.
  3. Revise os agentes existentes – identifique quaisquer segredos que possam ser removidos das chamadas de ferramentas.
  4. Adicione testes automatizados – garanta que a validação de contexto falhe quando dados extras forem injetados.

Um início rápido se parece com isto:

mkdir scoped-tools && cd scoped-tools
npm init -y
npm install ai zod
npm install -D typescript tsx @types/node

Crie demo.ts, declare o contextSchema de cada ferramenta e execute com tsx demo.ts. O SDK lançará um erro se você tentar fornecer a uma ferramenta um segredo que ela não solicitou.

Contraponto

Algumas equipes podem argumentar que as definições extras de esquema adicionam boilerplate e tornam a prototipagem mais lenta. Embora seja verdade, o custo é modesto — apenas algumas linhas por ferramenta — e o retorno em segurança cresce com o número de serviços integrados. Em ambientes que lidam com dados de pagamento ou informações pessoais, a compensação é difícil de ignorar.

O que observar a seguir

  • Métricas de adoção – os primeiros usuários estão relatando menos incidentes de vazamento de segredos.
  • Ferramentas da comunidade – plug-ins que geram automaticamente esquemas de contexto a partir de arquivos de configuração.
  • Futuros lançamentos do SDK – indícios de que a Vercel pode estender os contextos com escopo para incluir permissões de rede e limites de taxa (rate-limit).

Se você já está construindo agentes de IA com o SDK da Vercel, o primeiro passo é auditar o uso atual do seu process.env. Identifique o valor único que pode ser removido de todas as chamadas de ferramentas e substitua o padrão genérico por um toolsContext com escopo. O resultado é uma postura de segurança mais robusta sem sacrificar a flexibilidade que torna os agentes de IA poderosos.