Ferramenta code_interpreter: Executar Python
Nesta página
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_interpreterexecuta 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