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