Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Coding agentico con chiamata di strumenti

Lezione 6 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Cos’è il coding agentico?
  2. Il ciclo agentico
  3. Esempio pratico: correzione di un bug
  4. Uso degli strumenti nella pratica
  5. Ciclo agentico multi-turno
  6. Punti chiave

Lezione aggiornata il 2 novembre 2026. Gli esempi originali utilizzavano Devstral, rimosso dalle API il 31 luglio 2026. Ora utilizzano Mistral Small 4 (mistral-small-2603) e il ciclo agentico segue il modello della documentazione Mistral (tutte le chiamate di strumenti in una risposta vengono elaborate fino alla risposta finale). Fonte: Function calling.

Cos’è il coding agentico?

Il coding agentico cambia la natura di ciò che chiedi al modello di fare. Invece di richiedere uno snippet, poi un altro, poi un terzo, e unirli tu stesso, assegni un compito completo. Il modello lo risolve concatenando i passaggi in autonomia: esplorazione, pianificazione, implementazione e verifica. Tu rimani il decisore su cosa deve essere fatto, ma smetti di microgestire ogni singola mossa.

I modelli Devstral sono stati costruiti per questo flusso di lavoro; i modelli generici attuali, guidati da Mistral Small 4, lo gestiscono tramite la chiamata di strumenti. Un agente non si limita a rispondere a una domanda; agisce sul repository.

Il ciclo agentico

Fase 1 — Comprendere

L’agente inizia sempre orientandosi. Legge la struttura delle cartelle e dei file, identifica i file rilevanti per il compito richiesto, traccia le dipendenze tra i moduli per vedere cosa potrebbe influenzare una modifica e prende nota delle convenzioni esistenti: denominazione, organizzazione dei test e pattern ricorrenti. Questa fase sembra improduttiva perché non scrive codice, eppure determina se il codice risultante sembrerà tuo o quello di un estraneo.

Fase 2 — Pianificare

Prima di scrivere una singola riga, l’agente formula un piano. Scompone il compito in sotto-compiti ordinati, distingue i file da modificare da quelli da creare, anticipa gli effetti collaterali e i rischi di regressione e stabilisce un approccio tecnico. È qui che il tuo intervento costa meno: correggere un piano richiede trenta secondi; correggere dieci file che hai già scritto richiede molto più tempo.

Fase 3 — Eseguire

L’implementazione svolge il piano passo dopo passo. L’agente modifica i file esistenti, ne crea di nuovi quando la struttura lo richiede, aggiorna import e dipendenze spostati dalle sue modifiche e adatta i file di configurazione lungo il percorso. La coerenza tra queste modifiche è esattamente ciò che un modello di completamento non può garantire.

Fase 4 — Verificare

Infine arriva la prova che il lavoro regge. L’agente esegue la suite di test esistente, scrive nuovi test per il codice appena aggiunto, si assicura che la build passi e rivede il proprio diff alla ricerca di errori o modifiche stray. Un agente che salta questa fase produce codice plausibile, non codice corretto.

Esempio pratico: correzione di un bug

Supponi di dire all’agente: «Gli utenti ricevono un errore 500 quando inviano un modulo con un’email contenente un ’+’». Il ciclo assume quindi questa forma:

1. COMPRENDERE
   -> Cercare i file relativi al modulo (cercare "email" nel codice)
   -> Leggere il controller che gestisce l'invio
   -> Leggere la funzione di validazione dell'email
   -> Identificare la regex che rifiuta '+'

2. PIANIFICARE
   -> Modificare la regex di validazione per accettare '+'
   -> Aggiungere un test unitario per le email con '+'
   -> Verificare che nessun'altra parte del codice filtri '+'

3. ESEGUIRE
   -> Modificare src/validators/email.py: correggere il pattern regex
   -> Creare tests/test_email_validation.py: aggiungere casi con '+'
   -> Modificare src/controllers/form.py: aggiungere un log per il debug

4. VERIFICARE
   -> Eseguire pytest -> tutti i test passano
   -> Controllare il diff -> le modifiche sono coerenti e minime

Nota la terza riga del piano: l’agente non si limita a correggere dove il bug si manifesta; controlla che nessun altro filtro rifiuti il carattere altrove. Questa ricerca della causa radice, piuttosto che del solo sintomo, è ciò che distingue una correzione agentica da una toppa locale.

Uso degli strumenti nella pratica

L’agente agisce sul suo ambiente tramite chiamate di funzione. Dichiarai gli strumenti disponibili nella richiesta, inclusi nome, descrizione e schema dei parametri; il modello sceglie quali chiamare e con quali argomenti.

# Esempio di conversazione agentica
messages = [
    {
        "role": "user",
        "content": "Aggiungi una validazione robusta della password al modulo auth."
    }
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Legge il contenuto di un file di progetto",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "Percorso del file"}
                },
                "required": ["path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "write_file",
            "description": "Scrive o modifica un file di progetto",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string"},
                    "content": {"type": "string"}
                },
                "required": ["path", "content"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "run_command",
            "description": "Esegue un comando di shell",
            "parameters": {
                "type": "object",
                "properties": {
                    "command": {"type": "string"}
                },
                "required": ["command"]
            }
        }
    }
]

response = client.chat.complete(
    model="mistral-small-2603",
    messages=messages,
    tools=tools,
    tool_choice="auto",   # valore predefinito: il modello decide se chiamare uno strumento
)

Per questa richiesta, la sequenza tipica inizia con read_file("src/auth/validators.py") per comprendere il codice esistente, continua con read_file("tests/test_auth.py") per vedere il formato dei test attuali, per poi passare alla scrittura: write_file("src/auth/validators.py", ...) con la regola di validazione aggiunta, write_file("tests/test_auth.py", ...) con i nuovi casi e infine run_command("pytest tests/test_auth.py") per verificare. L’ordine conta: aprendo entrambi i file prima di toccare un singolo carattere, l’agente recepisce le tue convenzioni e le riproduce, invece di importarne altre viste altrove.

Ciclo agentico multi-turno

Nulla di tutto ciò avviene in una singola chiamata. Il cuore del coding agentico è il ciclo multi-turno: il modello propone un’azione, il tuo codice la esegue e tu invii il risultato indietro affinché possa decidere il passo successivo. Mantieni il controllo dell’esecuzione effettiva, che funge anche da tua barriera di sicurezza.

import json

TOOLS = {"read_file": read_file, "write_file": write_file, "run_command": run_command}

response = client.chat.complete(model="mistral-small-2603", messages=messages, tools=tools)
messages.append(response.choices[0].message)

for _ in range(30):   # barriera di sicurezza: un agente non deve mai andare in loop all'infinito
    tool_calls = response.choices[0].message.tool_calls
    if not tool_calls:
        break         # nessuna altra chiamata di strumento: la risposta finale è arrivata
    for tool_call in tool_calls:   # una risposta può contenere più chiamate
        name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)
        result = TOOLS[name](**arguments)
        messages.append({
            "role": "tool",
            "name": name,
            "content": str(result),
            "tool_call_id": tool_call.id,
        })
    response = client.chat.complete(model="mistral-small-2603", messages=messages, tools=tools)
    messages.append(response.choices[0].message)

print(response.choices[0].message.content)

Tre dettagli contano. Il messaggio dell’agente e ogni risultato dello strumento vengono reiniettati nella cronologia, accoppiati tramite tool_call_id: omettine uno e l’agente perde il filo, richiamando gli stessi strumenti in un loop. Una singola risposta può contenere multiple chiamate di strumento, poiché le chiamate parallele sono consentite di default (parallel_tool_calls=False le vieta): elaborale tutte. Infine, limita il numero di turni e fai validare a un umano i comandi di shell e le scritture su file: un agente che esegue tutto ciò che propone è un rischio, non un risparmio di tempo.

Punti chiave

  • Il coding agentico segue un ciclo: comprendere, pianificare, eseguire, verificare
  • L’agente agisce sul repository tramite chiamata di strumenti (tools, tool_choice)
  • Il ciclo multi-turno permette all’agente di iterare fino alla risoluzione completa
  • L’agente modifica più file in modo coerente in un unico compito
  • La fase di verifica (test, build) è essenziale per l’affidabilità