Chi lavora con agenti AI su basi .NET sa bene che il vero collo di bottiglia non è spesso la qualità del modello, ma il numero di round trip tra il modello stesso e i tool. Un agente che deve recuperare dati, filtrarli, fare calcoli e assemblare un risultato finisce tipicamente per eseguire cinque o sei chiamate separate al modello, ognuna con la propria latenza e il proprio costo in token. Microsoft ha presentato una soluzione concreta a questo problema: CodeAct, ora disponibile nel pacchetto alpha agent-framework-hyperlight.
Il problema: troppi turni, troppa latenza
Nel flusso tradizionale, un agente ragiona come segue: chiede al modello quale tool usare, esegue quel tool, rimanda il risultato al modello, il quale decide il prossimo tool, e così via. Questo schema modello → tool → modello → tool moltiplica la latenza e il consumo di token con ogni step aggiuntivo. Su task composti da tre, quattro o cinque operazioni concatenate (tipico nelle pipeline di data wrangling, elaborazione report, lookup incrociati), il costo diventa significativo.
CodeAct risolve il problema in modo elegante: invece di chiedere al modello di scegliere un tool alla volta, gli viene offerto un singolo tool speciale chiamato execute_code. Il modello esprime l’intero piano come un breve programma Python, che viene eseguito una volta sola in un ambiente sandbox. Il risultato? Latenza ridotta del ~50% e consumo di token calato di oltre il 60% su workload rappresentativi, secondo i dati pubblicati da Microsoft.
Hyperlight: sandbox micro-VM per sicurezza senza compromessi
La parte che rende CodeAct praticabile in produzione è Hyperlight: una tecnologia Microsoft che avvia una micro-VM isolata per ogni esecuzione di codice generato dal modello. Il codice Python prodotto dall’LLM gira dentro questa sandbox, senza accesso al filesystem host, alla rete o a qualsiasi risorsa non esplicitamente autorizzata. I tool reali invece continuano a girare nel runtime dell’applicazione, con tutti i permessi necessari.
Il bridge tra sandbox e tool avviene tramite la funzione call_tool(...): quando il codice nella sandbox chiama call_tool("nome_tool", ...), Hyperlight instrada la chiamata verso il tool nel processo principale, ne ritorna il risultato nella sandbox, e il programma continua. Il codice generato dall’AI rimane isolato; solo i tool verificati e distribuiti dallo sviluppatore hanno accesso reale alle risorse.
Come si integra CodeAct nel proprio agente
Il setup è sorprendentemente compatto. Dopo aver installato i pacchetti agent-framework e agent-framework-hyperlight:
from agent_framework import Agent, tool
from agent_framework_hyperlight import HyperlightCodeActProvider
@tool
def get_weather(city: str) -> dict:
# Restituisce il meteo corrente per una citta
return {"city": city, "temperature_c": 21.5, "conditions": "partly cloudy"}
codeact = HyperlightCodeActProvider(
tools=[get_weather],
approval_mode="never_require",
)
agent = Agent(
client=client,
name="CodeActAgent",
instructions="Sei un assistente utile.",
context_providers=[codeact],
)
result = await agent.run(
"Ottieni il meteo di Seattle e Amsterdam e confrontali."
)
HyperlightCodeActProvider si occupa di due cose in automatico: registra il tool execute_code ad ogni run dell’agente, e inietta nel system prompt le istruzioni sulla sandbox e sui tool disponibili via call_tool(...).
Gestione delle approvazioni: chi controlla cosa
Agent Framework distingue due modalità di approvazione per i tool:
- never_require: il framework invoca il tool automaticamente.
- always_require: ogni chiamata viene sospesa in attesa di un’approvazione human-in-the-loop.
Con CodeAct, la logica cambia leggermente. I tool registrati su HyperlightCodeActProvider non vengono esposti direttamente al modello come tool di primo livello: il modello vede solo execute_code e raggiunge gli altri tool scrivendo call_tool("nome", ...) nel programma Python. L’approvazione, se richiesta, si applica all’intero blocco di codice, non alle singole chiamate interne.
La regola pratica è chiara: i tool puri e sicuri (lookup dati, calcoli, chiamate read-only) vanno passati al provider, così il modello li può comporre in un unico turno. I tool con side effect (invio email, scrittura su sistemi in produzione, transazioni economiche) vanno tenuti sull’agente direttamente con approval_mode="always_require", così il modello li deve invocare esplicitamente uno per uno.
Quando conviene usare CodeAct
CodeAct non è la soluzione giusta per ogni agente. I benefici massimi si ottengono con task che coinvolgono molte operazioni concatenate e chainabili: data wrangling, generazione report, lookup multipli, calcoli intermedi. Se il task dell’agente si risolve quasi sempre con una o due chiamate a tool, il guadagno è marginale.
È anche importante considerare che il codice Python generato dal modello deve essere revisionabile: uno dei vantaggi collaterali di CodeAct è che l’intero piano dell’agente è concentrato in un singolo blocco di codice leggibile e auditabile, invece di essere distribuito su una catena di messaggi di tool-call.
Conclusione
CodeAct con Hyperlight rappresenta un’evoluzione pragmatica nell’architettura degli agenti AI su .NET: meno turni, meno token, stessa qualità. Il pattern è disponibile oggi nel pacchetto alpha agent-framework-hyperlight, pronto per essere sperimentato su workload interni prima di adottarlo in produzione. Chi sta già usando Agent Framework e si trova a costruire pipeline di tool-calling complesse troverà probabilmente il guadagno di latenza immediato e concreto.
Fonte: CodeAct in Agent Framework: Faster Agents with Fewer Model Turns – Microsoft Dev Blogs, 23 aprile 2026