Agenti AI — Manuale per Operations Manager

capitolo 01

Cos'è un agente AI?

Partiamo dall'analogia più semplice che esiste.

Concetto chiave

Un agente AI è un programma che, invece di aspettare ogni singola istruzione da te, riceve un obiettivo e poi decide autonomamente quali azioni compiere per raggiungerlo — leggendo file, chiamando API, scrivendo codice, navigando il web — iterando finché il compito non è fatto.

La differenza con una chat normale

💬

Chat normale

Domanda → Risposta
Ti risponde, si ferma.

⇒

🤖

Agente

Obiettivo → Loop azioni
Agisce, verifica, continua.

L'analogia del dipendente

Modo 1 — Chat tradizionale

Ogni mattina gli dici "Ora fai questo, poi aspetta" — poi quando finisce lo richiami. Sei tu a tenere in testa tutta la sequenza.

Modo 2 — Agente

Gli dici "Entro venerdì voglio il report sulle prenotazioni Airbnb di giugno." Lui sa cosa fare: apre Smoobu, estrae i dati, formatta il documento, ti avvisa solo a fine lavoro.

I 3 ingredienti

Un modello AI (il cervello)

Claude, GPT-4, Gemini — il modello che ragiona e decide cosa fare.

Degli strumenti (i tool)

Funzioni Python: leggere file, API calls, database, email, ricerche web.

Un loop (il motore)

AI decide → esegui → risultato torna all'AI → AI decide ancora → … finché finisce.

Cosa NON è un agente

Una skill in Claude Code non è un agente — è un prompt che esegui manualmente. Un agente ha autonomia: decide lui i passi.

Caratteristica	Script tradizionale	Agente AI
Passi fissi	Sì, sempre gli stessi	No, decide lui in base al contesto
Gestisce errori inaspettati	No, crasha	Sì, ragiona e cambia strategia
Comprende linguaggio naturale	No, solo parametri formali	Sì, capisce istruzioni ambigue
Prevedibile e auditabile	Sempre	Con log, sì

capitolo 03

Come si scrive un agente

Tre blocchi fissi in qualsiasi agente: (1) definisci i tool come JSON, (2) scrivi le funzioni Python reali, (3) fai girare il while loop.

Livello 1 — L'agente minimo

Complessità:

Principiante

import anthropic
client = anthropic.Anthropic()

# 1. Definisci gli STRUMENTI che l'agente può usare
tools = [{"name": "leggi_file", "description": "Legge un file di testo",
    "input_schema": {"type": "object",
        "properties": {"percorso": {"type": "string"}},
        "required": ["percorso"]}}]

# 2. Funzione reale che esegue l'azione
def leggi_file(percorso):
    with open(percorso, "r") as f:
        return f.read()

# 3. Il loop agente — cuore del sistema
messages = [{"role": "user", "content": "Leggi 'note.txt' e dimmi di cosa parla"}]

while True:
    response = client.messages.create(
        model="claude-opus-4-6", max_tokens=1024,
        tools=tools, messages=messages)

    # Se l'AI ha finito, esci
    if response.stop_reason == "end_turn":
        print(response.content[0].text); break

    # Se l'AI vuole usare un tool, eseguilo
    if response.stop_reason == "tool_use":
        tc = response.content[0]
        risultato = leggi_file(**tc.input)
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": [{"type": "tool_result",
                "tool_use_id": tc.id, "content": risultato}]}]

La struttura da ricordare

Il loop è sempre lo stesso. Cambia solo il numero di tool. Più tool aggiungi, più l'agente diventa capace.

Livello 3 — Slash command in Claude Code

Complessità:

Avanzato

---
description: Genera report mensile prenotazioni Allori
---

Sei un agente che genera il report mensile dell'appartamento Allori.

## Obiettivo
Produci un report per il mese: $ARGUMENTS

## Passi
1. Trova il CSV del mese richiesto in ~/allori/prenotazioni/
2. Calcola: n. prenotazioni, revenue, soggiorno medio, % occupazione
3. Confronta con il mese precedente
4. Scrivi report markdown e salvalo come report_MESE_ANNO.md
5. Dimmi il path del file salvato

Come si usa

In Claude Code digiti: /report-allori maggio 2025 — Claude esegue i passi autonomamente.

Pensiero tradizionale	Pensiero ad agenti
"Cosa devo fare passo per passo?"	"Qual è l'obiettivo? Quali dati? Quali azioni?"
"Scrivo uno script per questo caso"	"Scrivo tool generici che l'agente combinerà"
"Se cambia qualcosa riscrivo tutto"	"Cambio il prompt, i tool restano"

Gli Agenti AI
spiegati da zero

Cos'è un agente AI?

La differenza con una chat normale

L'analogia del dipendente

I 3 ingredienti

Come funziona internamente

Come si scrive un agente

Livello 1 — L'agente minimo

Livello 3 — Slash command in Claude Code

Casi pratici per il tuo lavoro

La scala di complessità

Gli Agenti AIspiegati da zero

Cos'è un agente AI?

La differenza con una chat normale

L'analogia del dipendente

I 3 ingredienti

Come funziona internamente

Come si scrive un agente

Livello 1 — L'agente minimo

Livello 3 — Slash command in Claude Code

Casi pratici per il tuo lavoro

La scala di complessità

Gli Agenti AI
spiegati da zero