Strumento code_interpreter: esegui Python
In questa pagina
Esegui codice nel cloud Mistral
Lo strumento code_interpreter permette al tuo agente di scrivere ed eseguire codice Python all’interno di un container isolato (sandbox). È la scelta ideale per calcoli, analisi dati, generazione di grafici e validazione del codice. Non si tratta solo di comodità: un LLM che «calcola» nella sua testa produce un risultato plausibile, non corretto. Delegando l’operazione a un interprete reale, sostituisci la previsione di token con un’esecuzione verificabile, ottenendo codice che puoi esaminare.
Creare un agente con Code Interpreter
Le istruzioni per questo agente richiedono di mostrare il codice prima di eseguirlo, offrendoti un punto di controllo su ciò che viene effettivamente eseguito.
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}
)
Attivare un’esecuzione
Una semplice richiesta di calcolo è sufficiente ad attivare lo strumento; non serve alcuna istruzione speciale da parte tua.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Calculate the first 20 Fibonacci numbers."
)
L’agente scrive quindi uno script Python per calcolare la sequenza, lo esegue nella sandbox e presenta i risultati accompagnati da spiegazioni. I venti valori che ricevi provengono da un’esecuzione reale: saranno esatti anche oltre il punto in cui un modello inizia solitamente a commettere errori.
Struttura della risposta
Puoi leggere direttamente questo meccanismo nelle voci restituite; il tuo codice deve distinguere tra testo e risultati dell’esecuzione.
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}")
L’agente inizia con un message.output che annuncia cosa sta per fare. Segue il tool.execution in cui viene eseguito il codice: info.code contiene lo script e info.code_output ne contiene l’output. Un secondo message.output chiude la sequenza, in cui l’agente interpreta e spiega i risultati. Questi due campi, info.code e info.code_output, costituiscono la tua traccia di audit: conservali nei log della tua applicazione, poiché ti permettono di riprodurre e contestare qualsiasi cifra prodotta dall’agente.
Cosa cambia lo strumento nella pratica
L’analisi dati è il caso d’uso più immediato. Fornisci una serie di valori e chiedi statistiche: media, mediana e deviazione standard vengono calcolate, non stimate.
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."""
)
La generazione di grafici estende naturalmente questa capacità, dato che l’ambiente include librerie di 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%"
)
L’agente utilizza matplotlib per generare il grafico. Il risultato è un file immagine accessibile nella risposta: assicurati quindi che il tuo codice di lettura gestisca questo caso, altrimenti finirai per visualizzare solo il commento testuale di accompagnamento.
La validazione del codice è un terzo caso d’uso, meno ovvio ma prezioso. Invia una funzione e i casi di test da coprire: l’agente non si limita a ragionare sul codice, lo esegue. Nell’esempio seguente, l’input "Madam" rivela un difetto che una semplice revisione del codice probabilmente mancherebbe.
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"
"""
)
La matematica applicata completa l’elenco: risoluzione di sistemi di equazioni, algebra lineare, ottimizzazione. Anche in questo caso, la risposta si basa su un risolutore, non sull’intuizione.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Solve the system of equations: 2x + 3y = 12, 4x - y = 5"
)
Combinare con altri strumenti
Un agente può avere più strumenti abilitati simultaneamente, ed è spesso qui che emerge il vero valore: la ricerca porta dati freschi che il codice trasforma in analisi.
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."
)
L’agente sceglie automaticamente quale strumento utilizzare a ogni passo. In questa richiesta, li concatena: non puoi calcolare una variazione senza prima ottenere i valori, e non puoi ottenere quei valori senza accesso al web.
Limitazioni della sandbox
Questo ambiente isolato impone vincoli che devi conoscere prima di progettare la tua applicazione. Le librerie sono limitate: i pacchetti Python standard sono disponibili (numpy, pandas, matplotlib, tra gli altri), ma non tutti i pacchetti di terze parti, il che esclude le tue dipendenze interne. Il codice non ha accesso alla rete, quindi i dati devono raggiungerlo tramite il contesto o un altro strumento, mai attraverso una chiamata HTTP scritta nello script. Il tempo di esecuzione è limitato, quindi i processi di lunga durata vengono interrotti: suddividi grandi volumi invece di sperare in un’unica passata. Infine, non c’è persistenza tra le chiamate; un file creato durante un’esecuzione non verrà trovato nella successiva.
Punti chiave
code_interpreteresegue Python in una sandbox sicura lato Mistral- La risposta contiene il codice eseguito (
info.code) e il suo output (info.code_output) - Ideale per calcoli, analisi dati e generazione di grafici
- Può essere combinato con altri strumenti (web_search, ecc.)
- La sandbox ha limitazioni: nessun accesso alla rete, librerie limitate, nessuna persistenza