- O que um interpretador de código adiciona a um app de IA
- Arquitetura de referência
- Fluxo de implementação
- Lidar com arquivos, saídas e artefatos gerados
- Definir política de pacotes e rede
- Aplicar limites, logs, limpeza e revisão
- Onde o Novita Agent Sandbox se encaixa
- Lista de verificação de avaliação
- Conclusão
- FAQ
- Artigos recomendados
Adicione um interpretador de código a um app de IA roteando a execução de código solicitada pelo modelo para um sandbox isolado com arquivos com escopo definido, uma política de pacotes clara, limites de recursos e tempo, saídas capturadas e revisão no lado do aplicativo antes que os resultados sejam exibidos ou persistidos. O modelo pode decidir quando o código é útil, mas seu aplicativo deve controlar o limite de execução: faça upload apenas dos arquivos necessários para a tarefa, crie ou reutilize uma sessão de sandbox de curta duração, execute Python com limites rigorosos, capture stdout, stderr, arquivos gerados e logs, retorne um resultado estruturado para o modelo e limpe a sessão quando o fluxo de trabalho for concluído.
O que um interpretador de código adiciona a um app de IA
Um interpretador de código transforma um modelo de linguagem de um assistente apenas de texto em um aplicativo que utiliza ferramentas, capaz de calcular, transformar arquivos, inspecionar dados, gerar gráficos e produzir artefatos revisáveis. Em vez de pedir ao modelo para raciocinar sobre uma planilha a partir de um prompt, o aplicativo pode permitir que o modelo escreva Python, execute-o no arquivo carregado, inspecione a saída e explique o resultado.
O padrão útil não é “deixe o modelo executar qualquer coisa”. O padrão útil é a execução controlada. Seu aplicativo aceita uma tarefa do usuário, permite que o modelo solicite uma chamada de ferramenta, como run_python, e então executa essa solicitação dentro de um sandbox, em vez de no processo principal do aplicativo. O sandbox se torna a bancada para arquivos temporários, instalações de pacotes, scripts, gráficos e logs.
Os recursos do interpretador de código são especialmente úteis para:
- Análise de CSV, Excel, JSON e logs
- Geração de gráficos a partir de dados carregados
- Conversão de formato e limpeza de dados
- Tarefas de matemática e simulação que precisam de computação exata
- Trechos de código que precisam ser testados antes que o modelo os explique
- Fluxos de trabalho de agente em várias etapas, onde as saídas de uma etapa se tornam entradas para a próxima
Eles são uma escolha inadequada para tarefas que exigem credenciais de produção irrestritas, acesso de longa duração a sistemas privados ou execução silenciosa sem uma trilha de auditoria visível ao usuário. Se o resultado pode afetar dinheiro, infraestrutura, segurança ou controle de acesso, adicione portões de revisão antes que qualquer efeito colateral saia do sandbox.
Arquitetura de referência
Uma arquitetura prática de interpretador de código tem cinco partes:
| Camada | Responsabilidade | Escolha de design comum |
|---|---|---|
| Interface do usuário | Carregar arquivos, mostrar progresso, exibir artefatos, solicitar aprovação | Manter os arquivos carregados com escopo na conversa ou projeto atual |
| Servidor de aplicação | Autenticar usuários, aplicar políticas, criar sessões de sandbox, armazenar logs | Nunca expor credenciais brutas do sandbox ao navegador |
| Orquestração do modelo | Decidir quando chamar ferramentas de código e resumir resultados | Usar chamadas de ferramenta estruturadas em vez de interpretar texto de forma livre |
| Runtime do sandbox | Executar Python, armazenar arquivos temporários, instalar pacotes permitidos | Executar com controles de recurso, tempo limite e limpeza |
| Armazenamento de artefatos | Preservar saídas aprovadas, como gráficos, CSVs, relatórios e logs | Armazenar apenas saídas que o aplicativo ou usuário aceitou |
O modelo não deve controlar diretamente a infraestrutura. Ele deve solicitar uma chamada de ferramenta. Seu aplicativo decide se essa chamada de ferramenta é permitida, quais arquivos estão anexados, por quanto tempo pode ser executada, quais pacotes estão disponíveis e quais saídas são retornadas.
Essa separação mantém o modelo útil sem torná-lo o limite de segurança.
Fluxo de implementação
Um fluxo de implementação robusto começa antes de qualquer código ser executado.
1. Aceitar a tarefa do usuário e os arquivos
Quando o usuário faz upload de um arquivo, armazene-o sob um registro de arquivo em nível de aplicativo com proprietário, espaço de trabalho, tipo de conteúdo, tamanho e política de retenção. Não exponha imediatamente todos os arquivos da conta do usuário ao interpretador. O sandbox deve receber apenas os arquivos necessários para a tarefa atual.
Por exemplo, um usuário pode perguntar:
“Analise este CSV, encontre os principais impulsionadores de receita e retorne um gráfico e uma breve explicação.”
Seu aplicativo pode anexar o CSV carregado à próxima iteração do modelo como um arquivo disponível, mas os bytes reais do arquivo devem ser movidos para o sandbox somente quando a execução do código for aprovada.
2. Permitir que o modelo solicite uma chamada de ferramenta
Defina uma superfície de ferramenta restrita. Uma primeira versão típica precisa apenas de algumas ferramentas:
{
"name": "run_python",
"arguments": {
"code": "import pandas as pd\n...",
"input_files": ["sales.csv"],
"expected_outputs": ["summary.json", "revenue_chart.png"],
"timeout_seconds": 30
}
}
Mantenha o esquema explícito. O modelo deve declarar o código, os arquivos de entrada, as saídas esperadas e uma solicitação de tempo limite. O aplicativo pode encurtar o tempo limite, rejeitar arquivos desconhecidos ou bloquear comandos que entrem em conflito com a política.
3. Criar ou reutilizar uma sessão de sandbox
Para uma resposta de assistente única, crie uma nova sessão de sandbox, carregue os arquivos de entrada, execute o código, colete o resultado e encerre a sessão. Para uma experiência de usuário do tipo notebook, mantenha uma sessão ativa durante a conversa atual para que células posteriores possam reutilizar variáveis e arquivos anteriores.
Sessões de curta duração são mais fáceis de raciocinar. Sessões com estado são mais ergonômicas para tarefas de análise. Escolha deliberadamente e mostre ao usuário quando o estado existe.
4. Executar Python e capturar resultados
Execute o código por meio da API de execução do sandbox ou de seu próprio worker dentro do sandbox. Capture a saída de execução estruturada:
{
"status": "success",
"stdout": "Loaded 12,448 rows\n",
"stderr": "",
"artifacts": [
{
"path": "revenue_chart.png",
"type": "image/png",
"size_bytes": 84231
},
{
"path": "summary.json",
"type": "application/json",
"size_bytes": 1260
}
],
"duration_ms": 1840
}
Retorne este resultado estruturado ao modelo. O modelo pode então explicar o que aconteceu, citar os arquivos gerados e perguntar se o usuário deseja uma nova tentativa.
5. Retornar resultados ao usuário
Não force o usuário a ler logs brutos, a menos que algo tenha falhado. Uma boa interface mostra a resposta, o gráfico ou arquivo gerado e uma pequena divulgação de que o código foi executado. Forneça um log de execução expansível para revisão.
Para execuções com falha, mostre um erro conciso e deixe o modelo revisar o código. Evite despejar longos tracebacks no chat principal, a menos que o usuário esteja depurando.
Lidar com arquivos, saídas e artefatos gerados
O tratamento de arquivos é onde muitos projetos de interpretador de código se tornam confusos. Trate entradas e saídas como objetos separados.
Os arquivos de entrada devem ser copiados para o sandbox em caminhos estáveis e sanitizados. Evite preservar nomes de caminho fornecidos pelo usuário que contenham espaços, caracteres de shell ou diretórios aninhados. Mantenha um mapeamento do nome de exibição para o caminho do sandbox no estado do aplicativo.
Os arquivos gerados devem ser escaneados e classificados antes de se tornarem artefatos para download. Uma imagem de gráfico, CSV limpo, resumo JSON ou relatório PDF pode ser seguro para apresentar diretamente. Um script gerado, arquivo executável ou archive deve exigir tratamento mais rigoroso.
Para geração de gráficos, peça ao modelo para salvar arquivos de imagem explicitamente, em vez de depender apenas da exibição inline. Para análise de dados, peça um arquivo de resumo legível por máquina, bem como uma explicação em linguagem natural. Isso dá ao seu aplicativo algo estável para validar e armazenar.
Uma política de artefatos útil se parece com isto:
| Tipo de artefato | Tratamento padrão |
|---|---|
Gráficos .png, .jpg, .webp, .svg |
Visualizar na UI após verificações de tamanho e tipo |
Saídas de dados .csv, .json, .xlsx |
Oferecer como downloads e resumir alterações |
Relatórios .txt, .md, .pdf |
Visualizar ou baixar dependendo do tamanho |
.py, .sh, binários, archives |
Não executar ou abrir automaticamente; exigir revisão explícita |
Se seu aplicativo suportar projetos persistentes, armazene artefatos aceitos fora do sandbox. O sandbox deve permanecer descartável.
Definir política de pacotes e rede
A maioria dos fluxos de trabalho de interpretador de código precisa de pacotes como pandas, NumPy, matplotlib, seaborn, scikit-learn ou openpyxl. A questão é se os pacotes são pré-instalados, instalados sob demanda ou incorporados em modelos de sandbox personalizados.
Pacotes pré-instalados mantêm a execução previsível. Instalações sob demanda são flexíveis, mas podem atrasar tarefas e introduzir desvios de dependência. Modelos personalizados geralmente são o melhor caminho de produção quando você conhece suas cargas de trabalho comuns.
Defina uma política de pacotes antes do lançamento:
- quais pacotes estão sempre disponíveis
- se o modelo pode solicitar instalações de pacotes
- se as instalações podem acessar índices de pacotes públicos
- se as versões fixas são necessárias
- quanto tempo as instalações podem ser executadas
- se pacotes compilados ou nativos são permitidos
A política de rede é igualmente importante. Muitas tarefas de dados não precisam de acesso à internet após o upload dos arquivos. Se um fluxo de trabalho precisar de APIs externas, roteie as credenciais por meio de ferramentas aprovadas pelo aplicativo, em vez de colocar segredos amplos no sandbox. O modelo não deve receber variáveis de ambiente irrestritas por padrão.
Aplicar limites, logs, limpeza e revisão
Um interpretador de código é um recurso de produção, não um executor de célula de demonstração. Coloque limites desde o início.
Os controles mínimos devem incluir:
- tempo máximo de execução por célula ou chamada de ferramenta
- tamanho máximo de saída para stdout e stderr
- tamanho máximo de artefato e número de arquivos
- limites de CPU e memória apropriados para a tarefa
- extensões de arquivo permitidas para visualização e download
- limites de concorrência por usuário e por espaço de trabalho
- regras de limpeza para sessões e arquivos temporários
Os logs devem responder a três perguntas: quem solicitou a execução, qual código foi executado e quais saídas foram produzidas. Armazene o suficiente para depurar e auditar o fluxo de trabalho, mas evite reter dados privados carregados por mais tempo do que sua política de produto exige.
A revisão humana ou do usuário é o controle final. Para análises de baixo risco, a revisão pode significar que o usuário vê o gráfico antes de baixá-lo. Para fluxos de trabalho de agente que podem atualizar tickets, escrever em bancos de dados ou chamar APIs externas, a revisão deve acontecer antes do efeito colateral, não depois.
Onde o Novita Agent Sandbox se encaixa
O Novita Agent Sandbox é projetado para agentes de IA que precisam de ambientes de runtime isolados para execução de código, fluxos de trabalho de navegador, tarefas do tipo computer-use, avaliações, ambientes de aprendizado por reforço e fluxos de trabalho de longa duração. Para um recurso de interpretador de código, isso significa que o sandbox pode atuar como a camada de execução, enquanto seu aplicativo permanece responsável pela autenticação do usuário, orquestração do modelo, política de arquivos, revisão e retenção específica do produto.
A documentação do sandbox da Novita inclui fluxos de trabalho de sistema de arquivos para ler, escrever, fazer upload, baixar e monitorar arquivos em um sandbox. Essas capacidades se mapeiam diretamente para as necessidades do interpretador de código: mover arquivos do usuário para o ambiente de execução, deixar o código gerar gráficos ou dados transformados e, em seguida, trazer as saídas selecionadas de volta para o aplicativo. Consulte a documentação do sistema de arquivos do sandbox Novita para obter a visão geral atual das operações de arquivo.
Se seu interpretador crescer além de um simples executor Python, modelos de sandbox personalizados podem ajudar a padronizar dependências e configuração de runtime. Isso é útil quando cada sessão precisa da mesma pilha de análise, ferramentas de linha de comando internas ou bibliotecas específicas do projeto. Comece com um conjunto de pacotes permitidos pequeno e, em seguida, mova a configuração repetida para modelos assim que a carga de trabalho se estabilizar.
Mantenha as decisões de integração específicas da Novita separadas da arquitetura geral. Seu interpretador de código ainda precisa de políticas em nível de aplicativo para visibilidade de arquivos, instalação de pacotes, acesso à rede, retenção de logs e revisão. O sandbox fornece o runtime controlado; seu produto define como esse runtime é usado.
Lista de verificação de avaliação
Antes de enviar, teste o recurso com fluxos de trabalho reais e prompts adversariais.
| Pergunta | O que verificar |
|---|---|
| Os usuários podem carregar os arquivos corretos? | Tamanho do arquivo, verificações de tipo, verificações de proprietário e mensagens de erro claras |
| O modelo pode solicitar execução de forma limpa? | Chamadas de ferramenta estruturadas com código, entradas, saídas esperadas e tempo limite |
| O sandbox tem o escopo correto? | Apenas arquivos e variáveis de ambiente aprovados estão disponíveis |
| Os pacotes são previsíveis? | Pacotes comuns funcionam, pacotes negados falham claramente, instalações têm limites |
| As saídas são utilizáveis? | Gráficos renderizam, arquivos baixam, resumos correspondem aos artefatos gerados |
| As falhas são recuperáveis? | Tracebacks são capturados, o modelo pode revisar o código, os usuários veem erros concisos |
| Os limites são aplicados? | Loops infinitos, saídas enormes, tarefas pesadas de memória e instalações longas são encerradas |
| A revisão está incorporada? | Os usuários podem inspecionar código, logs e artefatos antes de efeitos colaterais importantes |
| A limpeza é confiável? | Arquivos e sessões temporários são removidos ou expirados conforme programado |
A melhor primeira versão geralmente é restrita: execução Python, um conjunto de pacotes pequeno, upload de arquivos, gráficos e arquivos para download, limites claros e um log de execução. Adicione instalações de pacotes mais amplas, sessões persistentes, acesso a API externa e efeitos colaterais de agente somente depois que o loop básico estiver observável e confiável.
Conclusão
Um interpretador de código funciona melhor quando o modelo pode solicitar execução, mas seu aplicativo controla o sandbox, arquivos, limites e a etapa de revisão. Comece com uma ferramenta Python restrita, mantenha entradas e saídas explícitas e expanda somente após o fluxo estar estável.
FAQ
Qual é a maneira mais segura de adicionar um interpretador de código?
Use um sandbox isolado, defina o escopo dos arquivos de entrada, limite o tempo de execução e a memória e retorne saídas estruturadas em vez de acesso bruto ao shell.
O modelo deve controlar as instalações de pacotes?
Apenas dentro de uma política que você definir. Muitos aplicativos começam com um conjunto de pacotes fixo e adicionam instalações posteriormente, se a carga de trabalho precisar.
Todas as tarefas do interpretador de código precisam de acesso à rede?
Não. Muitos fluxos de trabalho de análise funcionam totalmente offline depois que os arquivos do usuário são carregados, o que mantém o modelo de execução mais simples.
O que o usuário deve ver após a execução?
O resultado, artefatos gerados e um resumo conciso do log ou erro, com a opção de inspecionar o código ou executar a tarefa novamente.
