Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Ferramenta code_interpreter: Executar Python

Aula 9 de 18 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Executar Código na Nuvem Mistral
  2. Criar um Agente com Interpretador de Código
  3. Acionar uma Execução
  4. Estrutura da Resposta
  5. O Que a Ferramenta Muda na Prática
  6. Combinar com Outras Ferramentas
  7. Limitações da Sandbox
  8. Pontos-chave

Executar Código na Nuvem Mistral

A ferramenta code_interpreter permite que o seu agente escreva e execute código Python num contentor isolado (sandbox). É a escolha ideal para cálculos, análise de dados, geração de gráficos e validação de código. Isto não é apenas uma questão de conveniência: um LLM que «calcula» mentalmente produz um resultado plausível, não um correto. Ao delegar a operação a um interpretador real, substitui a previsão de tokens por uma execução verificável, obtendo código que pode auditar.

Criar um Agente com Interpretador de Código

As instruções para este agente exigem que mostre o código antes de o executar, dando-lhe um ponto de controlo sobre o que realmente corre.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Code Agent",
    instructions="""You are a Python programming assistant.
- Use the code interpreter to run code when necessary
- Always show the code before executing it
- Explain results clearly""",
    tools=[{"type": "code_interpreter"}],
    completion_args={"temperature": 0.3, "top_p": 0.95}
)

Acionar uma Execução

Um pedido de cálculo simples é suficiente para acionar a ferramenta; não é necessária nenhuma instrução especial da sua parte.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Calculate the first 20 Fibonacci numbers."
)

O agente escreve então um script Python para calcular a sequência, executa-o na sandbox e apresenta os resultados juntamente com explicações. Os vinte valores que recebe provêm de uma execução real: serão exatos, mesmo além do ponto onde um modelo costuma começar a cometer erros.

Estrutura da Resposta

Pode ler este mecanismo diretamente nas entradas devolvidas, e o seu código deve distinguir entre texto e resultados de execução.

for entry in response.outputs:
    if entry.type == "message.output":
        # First response: "I will calculate..." or final result
        print(f"Message: {entry.content}")

    elif entry.type == "tool.execution":
        # Executed code and result
        print(f"Code: {entry.info.code}")
        print(f"Output: {entry.info.code_output}")

O agente começa com um message.output a anunciar o que vai fazer. Segue-se o tool.execution onde o código corre: info.code contém o script e info.code_output guarda o seu output. Um segundo message.output encerra a sequência, na qual o agente interpreta e explica os resultados. Estes dois campos, info.code e info.code_output, constituem o seu registo de auditoria — mantenha-os nos registos da sua aplicação, pois permitem-lhe reproduzir e contestar qualquer valor produzido pelo agente.

O Que a Ferramenta Muda na Prática

A análise de dados é o caso de uso mais imediato. Forneça uma série de valores e peça estatísticas: a média, a mediana e o desvio padrão são calculados, não estimados.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="""Here are the monthly sales (in K€): 
    Jan: 120, Feb: 135, Mar: 142, Apr: 128, May: 155, Jun: 168
    Calculate the mean, median, standard deviation, and trend."""
)

A geração de gráficos estende naturalmente esta capacidade, uma vez que o ambiente inclui bibliotecas de plotting.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Create a bar chart of cloud market shares in Europe: AWS 31%, Azure 25%, GCP 11%, OVH 8%, Others 25%"
)

O agente utiliza o matplotlib para gerar o gráfico. O resultado é um ficheiro de imagem acessível na resposta — certifique-se de que o seu código de leitura lida com este caso, caso contrário, acabará por apresentar apenas o comentário de texto que o acompanha.

A validação de código é um terceiro caso de uso, menos óbvio mas valioso. Submeta uma função e os casos de teste a cobrir: o agente não raciocina apenas sobre o código, ele executa-o. No exemplo abaixo, a entrada "Madam" revela uma falha que uma revisão de código simples provavelmente ignoraria.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="""Check if this function is correct:
    
def is_palindrome(s):
    return s == s[::-1]

Test it with: "radar", "hello", "kayak", "Madam"
"""
)

A matemática aplicada completa a lista: resolução de sistemas de equações, álgebra linear, otimização. Mais uma vez, a resposta baseia-se num resolvedor, não na intuição.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Solve the system of equations: 2x + 3y = 12, 4x - y = 5"
)

Combinar com Outras Ferramentas

Um agente pode ter várias ferramentas ativadas simultaneamente, e é frequentemente aqui que surge o verdadeiro valor: a pesquisa traz dados recentes que o código transforma em análise.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Complete Analyst",
    description="Search + Calculation",
    instructions="Search for recent data then analyze it with code.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"}
    ]
)

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Find the current price of Bitcoin and calculate its percentage change over the last 30 days."
)

O agente escolhe automaticamente qual a ferramenta a utilizar em cada passo. Neste pedido, encadeia as duas: não é possível calcular uma variação sem primeiro obter os valores, e não é possível obter esses valores sem acesso à web.

Limitações da Sandbox

Este ambiente isolado impõe restrições que deve conhecer antes de desenhar a sua aplicação. As bibliotecas são limitadas: os pacotes Python standard estão disponíveis — numpy, pandas, matplotlib, entre outros — mas nem todos os pacotes de terceiros, o que exclui as suas dependências internas. O código não tem acesso à rede, pelo que os dados devem chegar-lhe via contexto ou através de outra ferramenta, nunca através de uma chamada HTTP escrita no script. O tempo de execução é limitado, pelo que processos de longa duração são interrompidos: divida grandes volumes de dados em vez de esperar por uma única passagem. Finalmente, não há persistência entre chamadas; um ficheiro criado durante uma execução não será encontrado na seguinte.

Pontos-chave

  • code_interpreter executa Python numa sandbox segura no lado da Mistral
  • A resposta contém o código executado (info.code) e o seu output (info.code_output)
  • Ideal para cálculos, análise de dados e geração de gráficos
  • Pode ser combinado com outras ferramentas (web_search, etc.)
  • A sandbox tem limitações: sem acesso à rede, bibliotecas limitadas, sem persistência