Code Mode deixa modelos escreverem código chamando ferramentas

O que é Code Mode

O Code Mode é um recurso experimental do AI SDK da Vercel que permite a um modelo de linguagem escrever código JavaScript ou TypeScript que chama ferramentas definidas pelo desenvolvedor, em vez de invocar cada ferramenta individualmente. O código gerado é executado em um sandbox isolado baseado em QuickJS e retorna um resultado serializável em JSON.

Vantagens sobre a chamada direta de ferramentas

Ao gerar código, o modelo pode executar ferramentas independentes de forma concorrente, transformar e combinar resultados de múltiplas ferramentas, filtrar respostas grandes antes de devolvê-las ao contexto e usar fluxo de controle JavaScript para operações em múltiplas etapas.

Integração com generateText

O pacote @ai-sdk/code-mode expõe a função codeModeTool, que é adicionada ao conjunto de ferramentas de uma chamada generateText. O desenvolvedor usa experimental_toolCallers para declarar quais ferramentas ficam disponíveis exclusivamente via code mode, exclusivamente via chamada direta ou por ambos os caminhos. Ferramentas sem entrada nessa configuração mantêm o comportamento padrão de chamada direta.

A descrição da ferramenta de code mode inclui assinaturas TypeScript geradas a partir dos schemas de entrada e saída das ferramentas permitidas, o que ajuda o modelo a produzir código correto.

Capacidades e restrições do código gerado

Os programas gerados suportam JavaScript e TypeScript com remoção de tipos, await no nível superior, return, fluxo de controle padrão, Promise.all para concorrência, JSON.parse, JSON.stringify e métodos de console. Cada chamada de ferramenta é assíncrona e precisa ser aguardada. Retornar enquanto chamadas ainda estão pendentes falha a invocação e aborta o trabalho restante.

O suporte a TypeScript limita-se à remoção de sintaxe de tipos; não há verificação de tipos nem compilador completo.

Execução direta

A função experimental_runCodeMode permite executar um programa diretamente, sem expor o code mode a um modelo. O sandbox e os limites de execução são os mesmos.

Aprovação de ferramentas

O Code Mode não se integra atualmente aos fluxos de aprovação de ferramentas do AI SDK. Como as chamadas ficam aninhadas dentro da invocação do code mode, não é possível pausar a geração para solicitar aprovação ao usuário. A recomendação é não expor ao code mode ferramentas que dependam de aprovação; essas devem permanecer como chamadas diretas.

Limites de execução

Cada invocação possui limites configuráveis para tempo de execução, memória QuickJS, tamanho da pilha, tamanho do código-fonte gerado, tamanho do resultado, saída de console, tamanho de entrada e saída de cada ferramenta, número total de chamadas e número de chamadas concorrentes. Também é possível definir um teto global de workers simultâneos com experimental_setMaxWorkers (padrão: até 32, conforme memória disponível).

Isolamento e segurança

Cada invocação recebe um contexto QuickJS novo. O código no sandbox não acessa globais do Node.js, sistema de arquivos, fetch, WebCrypto, eval nem construção dinâmica de Function. Acesso a rede ou sistema deve ser implementado como ferramenta fornecida explicitamente.

A documentação ressalta que o sandbox deve ser tratado como defesa em profundidade: ferramentas executam fora do QuickJS, no processo hospedeiro, e toda capacidade exposta por uma ferramenta fica disponível ao código gerado. O desenvolvedor deve validar entradas e aplicar autorização dentro de cada ferramenta.

Disponibilidade

O recurso é experimental, requer Node.js 22 ou superior e não está disponível em runtimes de navegador ou edge.