> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# interpretador de código

> Execução de código em sandbox no ClickHouse Agents

[Recurso beta](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

O interpretador de código permite que um agente execute código em um sandbox gerenciado. Use-o para cálculos, transformação de dados, conversão de formatos, geração de gráficos e qualquer outra tarefa que seja melhor fazer em código do que em linguagem natural.

## Habilite o interpretador de código

No Agent Builder, habilite **Run Code** na seção **Capabilities** e salve. O agente decide quando executar código com base na solicitação do usuário e nas instruções recebidas.

![Seção Run Code do painel Capabilities, com a caixa de seleção Run Code habilitada e um botão Upload to Code Environment](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/run-code/run-code.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=00125f4a580b82198fdd9dc20dc6d25f)

## Idiomas compatíveis

O sandbox é um ambiente Unix com dois ambientes de execução de uso geral e alguns utilitários de shell:

* **Python 3** - o padrão para tarefas com dados.
* **Node.js (JavaScript)** - quando um agente prefere JS para a tarefa.
* **Bash** e **sh** - scripts de shell para encadear comandos e fazer E/S rápidas.
* **AWK** e **sed** - processamento de texto baseado em linhas.
* **bc** - matemática de precisão arbitrária.

Os agentes recorrem primeiro ao Python para tudo o que envolva interpretação de dados, transformação ou computação.

> [!TIP]
>
> Reserve as ferramentas de shell para tarefas que realmente se beneficiem de um comando de uma linha.

## Arquivos

Os usuários podem enviar arquivos em uma conversa; o interpretador de código tem acesso a eles no diretório de trabalho do sandbox. O código também pode gerar arquivos de saída (CSVs, gráficos, arquivos compactados), que aparecem na conversa como anexos para download.

## Isolamento do sandbox

Cada execução ocorre em um sandbox efêmero, sem acesso à rede e sem armazenamento persistente. As sessões não compartilham estado — variáveis e arquivos de uma execução não passam para a seguinte, a menos que o agente os recarregue explicitamente.

Aplicam-se limites de recursos específicos do plano (memória, arquivos por execução e cotas mensais de solicitações). Erros e `stderr` são exibidos na conversa junto com `stdout`.

## Quando usar

Use o interpretador de código quando a resposta exigir um processamento determinístico que um modelo de linguagem não consegue produzir com confiabilidade apenas por raciocínio.
Casos típicos incluem:

* Analisar um arquivo CSV ou JSON enviado pelo usuário.
* Calcular estatísticas resumidas ou executar uma simulação rápida.
* Converter entre formatos (Parquet, JSON, CSV).
* Gerar um gráfico a partir dos resultados da consulta.

> [!TIP]
>
> Evite usá-lo em tarefas que o modelo já consegue responder com base no contexto.
> A execução de código aumenta a latência e consome cota.
