Claude Code Agent SDK: La Guida Completa per Creare Agenti IA (2026)

Vuoi creare il tuo primo agente IA ma non sai da dove iniziare?

Il Claude Code Agent SDK di Anthropic lo rende possibile – anche senza conoscenze approfondite di programmazione. In questa guida completa, ti mostreremo passo dopo passo come creare agenti IA autonomi in grado di gestire autonomamente compiti complessi.

---

Cosa Imparerai in Questa Guida

• Cosa sono gli agenti IA e come differiscono dai chatbot
• Come funziona il Claude Code Agent SDK
• Esempi di codice pratici per il tuo primo agente
• Strumenti, sotto-agenti e integrazione MCP
• Best practice per agenti pronti per la produzione

---

Cos'è un Agente IA? (E Perché è Diverso da ChatGPT?)

Prima di immergerci nel codice, chiariamo un concetto fondamentale: Cosa distingue un agente IA da un chatbot ordinario?

Chatbot vs Agente

Un chatbot risponde alle tue domande. Un agente IA lavora autonomamente verso un obiettivo, utilizzando vari strumenti e prendendo le proprie decisioni lungo il percorso.

Il Pattern Agent Loop

Ogni agente IA segue un pattern fondamentale – il cosiddetto Agent Loop:

┌─────────────────────────────────────────────────────────────┐
│                    PATTERN AGENT LOOP                       │
├─────────────────────────────────────────────────────────────┤
│  1. RACCOGLIERE CONTESTO                                    │
│     └─▶ Comprendere il compito, leggere dati rilevanti      │
│                                                             │
│  2. ESEGUIRE AZIONE                                         │
│     └─▶ Usare strumenti, eseguire operazioni                │
│                                                             │
│  3. VERIFICARE RISULTATI                                    │
│     └─▶ L'azione ha avuto successo?                         │
│                                                             │
│  4. RIPETERE                                                │
│     └─▶ Fino al raggiungimento dell'obiettivo               │
└─────────────────────────────────────────────────────────────┘

Esempio pratico: Chiedi a un agente di pianificare un viaggio. L'agente:

1. Raccoglie contesto: Chiede data, budget, preferenze
2. Esegue azioni: Cerca voli, hotel, attività
3. Verifica: Tutto rientra nel budget? Gli orari sono compatibili?
4. Ripete: Finché un piano di viaggio completo è pronto

---

Cos'è il Claude Code Agent SDK?

Il Claude Code Agent SDK è lo stesso framework che Anthropic utilizza internamente per Claude Code – il loro potente assistente di codifica.

Fornisce tutto ciò di cui hai bisogno per creare agenti IA pronti per la produzione.

Funzionalità Principali dell'SDK

Perché Scegliere il Claude Code Agent SDK?

1. Testato in produzione: Lo stesso sistema che alimenta Claude Code
2. Boilerplate minimo: Meno codice, più funzionalità
3. Strumenti integrati: Operazioni su file, Bash, Web pronti all'uso
4. Nativo MCP: Integrazione fluida con Model Context Protocol

---

Avvio Rapido: Installazione e Configurazione

Prerequisiti

• Python 3.10 o superiore
• Chiave API Anthropic (da console.anthropic.com)

Passo 1: Installare l'SDK

# Installare con pip
pip install claude-agent-sdk

# Oppure con uv (raccomandato per installazione più veloce)
uv pip install claude-agent-sdk

Passo 2: Configurare la Chiave API

# Impostare come variabile d'ambiente
export ANTHROPIC_API_KEY="sk-ant-..."

# Oppure in un file .env
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Passo 3: Testare la Prima Connessione

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def test_connection():
    options = ClaudeAgentOptions(
        model="sonnet",  # Claude Sonnet 4
        system_prompt="Sei un assistente utile."
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Saluta!")
        async for message in client.receive_response():
            print(message)

# Eseguire
import asyncio
asyncio.run(test_connection())

---

Esempio Pratico 1: Agente Q&A Semplice

Iniziamo con l'agente più semplice – uno che risponde alle domande:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock
import asyncio

SYSTEM_PROMPT = """Sei un assistente amichevole che risponde alle domande. 
Sii preciso e utile."""

async def simple_qa_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits"  # Permette operazioni di lettura
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🤖 Agente Q&A pronto! (Digita 'exit' per uscire)\n")
        
        while True:
            user_input = input("Tu: ").strip()
            
            if user_input.lower() in ['exit', 'esci']:
                print("Arrivederci!")
                break
            
            await client.query(user_input)
            
            print("Agente: ", end="")
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print("\n")

if __name__ == "__main__":
    asyncio.run(simple_qa_agent())

Cosa fa questo codice:

1. Crea un client con un prompt di sistema
2. Avvia un ciclo interattivo
3. Invia l'input dell'utente a Claude
4. Restituisce la risposta in streaming

---

Esempio Pratico 2: Agente con Memoria

Un agente con memoria di conversazione può ricordare i messaggi precedenti:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock
import asyncio

SYSTEM_PROMPT = """Sei un assistente con memoria. 
Ricordi tutto ciò che è stato detto in questa conversazione.
Fai riferimento alle affermazioni precedenti quando pertinente."""

async def memory_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        # L'SDK gestisce automaticamente la cronologia della conversazione!
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🧠 Agente Memoria pronto!\n")
        print("Suggerimento: Fai domande relative alle risposte precedenti.\n")
        
        while True:
            user_input = input("Tu: ").strip()
            
            if not user_input:
                continue
                
            if user_input.lower() == 'exit':
                break
            
            await client.query(user_input)
            
            print("Agente: ", end="")
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="", flush=True)
            print("\n")

if __name__ == "__main__":
    asyncio.run(memory_agent())

Testa la memoria:

Tu: Mi chiamo Max.
Agente: Ciao Max! Piacere di conoscerti.

Tu: Qual è il mio nome?
Agente: Il tuo nome è Max – ti sei appena presentato!

---

Esempio Pratico 3: Agente con Strumenti

È qui che diventa interessante! Gli agenti con strumenti possono eseguire azioni reali:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock, ToolUseBlock
import asyncio

SYSTEM_PROMPT = """Sei un assistente di ricerca con accesso agli strumenti.
Usa gli strumenti disponibili per completare i compiti:

- WebFetch: Recupera contenuti di pagine web
- Read: Legge file locali
- Grep: Cerca pattern nei file
- Glob: Trova file per pattern

Spiega sempre quale strumento stai usando e perché."""

async def tool_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=[
            "WebFetch",  # Recuperare contenuti web
            "Read",      # Leggere file
            "Grep",      # Cercare testo
            "Glob",      # Trovare file
        ]
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🔧 Agente Strumenti pronto!")
        print("Comandi: 'ricerca [URL]', 'trova [file]', ecc.\n")
        
        while True:
            user_input = input("Tu: ").strip()
            
            if user_input.lower() == 'exit':
                break
            
            await client.query(user_input)
            
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(f"Agente: {block.text}")
                        elif isinstance(block, ToolUseBlock):
                            print(f"🛠️ Uso strumento: {block.name}")
                            print(f"   Parametri: {block.input}")
            print()

if __name__ == "__main__":
    asyncio.run(tool_agent())

Strumenti Integrati Disponibili

---

Esempio Pratico 4: Agente Pianificatore di Viaggi Autonomo

Costruiamo ora un agente completamente autonomo:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock, ToolUseBlock, ToolResultBlock
import asyncio
import json

TRAVEL_SYSTEM_PROMPT = """Sei un agente di pianificazione viaggi autonomo.

IL TUO OBIETTIVO: Creare un piano di viaggio completo basato sui requisiti dell'utente.

IL TUO WORKFLOW:
1. Raccogliere tutte le informazioni necessarie (data, budget, preferenze)
2. Ricercare opzioni con WebFetch
3. Creare un piano di viaggio strutturato
4. Presentare il piano e chiedere feedback

IMPORTANTE:
- PRIMA chiedere le informazioni mancanti
- Usare WebFetch per informazioni attuali
- Creare un piano chiaro e strutturato
- Offrire alternative

INIZIA SEMPRE con un saluto amichevole e chiedi la destinazione."""

async def travel_planner_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=TRAVEL_SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=["WebFetch", "Read", "Write"],
        max_turns=20  # Permette cicli di agente più lunghi
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("✈️ Agente Pianificatore Viaggi avviato!")
        print("=" * 50)
        
        # Saluto iniziale dall'agente
        await client.query("Inizia la pianificazione viaggio per un nuovo cliente.")
        
        async for message in client.receive_response():
            if hasattr(message, 'content'):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Agente: {block.text}")
        print()
        
        # Ciclo interattivo
        while True:
            user_input = input("Tu: ").strip()
            
            if user_input.lower() in ['exit', 'finito', 'grazie']:
                print("Agente: Prego! Buon viaggio! 🌍✨")
                break
            
            await client.query(user_input)
            
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(f"Agente: {block.text}")
                        elif isinstance(block, ToolUseBlock):
                            print(f"🔍 Ricerca: {block.name}...")
            print()

if __name__ == "__main__":
    asyncio.run(travel_planner_agent())

---

Funzionalità Avanzate: Integrazione MCP

Il Model Context Protocol (MCP) permette l'integrazione di servizi esterni:

Includere Server MCP

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# Configurazione server MCP
MCP_CONFIG = {
    "utils": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://your-mcp-server.com/api"]
    }
}

async def mcp_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt="Hai accesso agli strumenti MCP per funzionalità estese.",
        permission_mode="acceptEdits",
        allowed_tools=[
            "WebFetch",
            "mcp__utils__save_note",   # Gli strumenti MCP sono prefissati
            "mcp__utils__find_note",
        ],
        mcp_servers=MCP_CONFIG
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Crea una nota con titolo 'Importante'")
        # ...

Creare il Proprio Server MCP

# mcp_server.py - Server MCP semplice
from mcp import Server

server = Server("my-tools")

@server.tool(name="save_note")
async def save_note(title: str, content: str) -> dict:
    """Salva una nota."""
    # La tua logica qui
    return {"status": "success", "id": "note_123"}

@server.tool(name="find_note")
async def find_note(pattern: str) -> dict:
    """Trova note per pattern."""
    # La tua logica qui
    return {"notes": [...]}

if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

---

Sotto-agenti: Agenti Specializzati

Per compiti complessi, puoi usare sotto-agenti – agenti specializzati che gestiscono sotto-compiti:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

ORCHESTRATOR_PROMPT = """Sei un coordinatore che delega compiti a 
sotto-agenti specializzati:

- Agente Ricerca: Per raccolta informazioni
- Agente Scrittura: Per creazione contenuti
- Agente Analisi: Per analisi dati

Delega i compiti secondo il loro tipo."""

async def orchestrator_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=ORCHESTRATOR_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=["SubAgent", "Read", "Write"],
        subagents_enabled=True  # Abilita i sotto-agenti
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query(
            "Ricerca le ultime tendenze IA e crea un report."
        )
        # L'agente delega automaticamente ai sotto-agenti

Quando Usare i Sotto-agenti?

---

Hooks: Workflow Basati su Eventi

Gli Hooks permettono azioni automatizzate su eventi specifici:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher

# Definire la funzione hook
async def log_tool_usage(event):
    """Registra ogni utilizzo di strumento."""
    print(f"📝 Log: Strumento '{event.tool_name}' è stato chiamato")
    return True  # Permette l'esecuzione

async def block_dangerous_commands(event):
    """Blocca comandi Bash pericolosi."""
    dangerous = ['rm -rf', 'sudo', 'chmod 777']
    if any(cmd in str(event.arguments) for cmd in dangerous):
        print("⚠️ Comando pericoloso bloccato!")
        return False  # Blocca l'esecuzione
    return True

async def hook_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt="Sei un assistente con hook di sicurezza.",
        permission_mode="acceptAll",
        allowed_tools=["Bash", "Write", "Read"],
        hooks={
            "PreToolUse": [
                HookMatcher(hooks=[log_tool_usage]),
                HookMatcher(
                    tool_name="Bash",
                    hooks=[block_dangerous_commands]
                )
            ]
        }
    )
    
    async with ClaudeSDKClient(options=options) as client:
        # ...

Tipi di Hook

---

Best Practice per Agenti Pronti per la Produzione

1. Prompt di Sistema Chiari

# ❌ Male: Istruzioni vaghe
SYSTEM_PROMPT = "Sii utile."

# ✅ Bene: Ruolo, limiti e comportamento chiari
SYSTEM_PROMPT = """Sei un agente di servizio clienti per TechCorp.

IL TUO RUOLO:
- Rispondere a domande sui nostri prodotti
- Inoltrare richieste complesse agli umani
- Documentare tutte le interazioni

LIMITI:
- Nessuna negoziazione prezzi
- Nessun cambiamento tecnico senza approvazione
- In caso di dubbio: Chiedi

COMPORTAMENTO:
- Amichevole e professionale
- Rispondi nella lingua del cliente
- Riassumi argomenti complessi"""

2. Impostare i Permessi in Modo Granulare

# ❌ Male: Permettere tutto
permission_mode = "acceptAll"

# ✅ Bene: Permettere solo gli strumenti necessari
permission_mode = "acceptEdits"
allowed_tools = ["Read", "WebFetch"]  # Solo ciò che è veramente necessario

3. Implementare la Gestione degli Errori

async def resilient_agent():
    max_retries = 3
    
    for attempt in range(max_retries):
        try:
            async with ClaudeSDKClient(options=options) as client:
                await client.query(prompt)
                async for message in client.receive_response():
                    # Elaborazione
                    pass
                break  # Successo, esci dal ciclo
                
        except RateLimitError:
            wait_time = 2 ** attempt  # Backoff esponenziale
            print(f"Limite di rate raggiunto. Attendo {wait_time}s...")
            await asyncio.sleep(wait_time)
            
        except Exception as e:
            print(f"Errore: {e}")
            if attempt == max_retries - 1:
                raise

4. Gestione del Contesto

# Per conversazioni lunghe: Comprimere il contesto
options = ClaudeAgentOptions(
    model="sonnet",
    system_prompt=SYSTEM_PROMPT,
    # L'SDK comprime automaticamente quando necessario
    max_context_tokens=100000,  # Dimensione massima del contesto
)

---

Costi e Selezione del Modello

Modelli Disponibili

Raccomandazione Modello per Caso d'Uso

---

Riepilogo: Il Tuo Percorso verso il Primo Agente

Checklist per Iniziare

• Python 3.10+ installato
• Chiave API Anthropic creata
• claude-agent-sdk installato
• Agente Q&A semplice testato
• Agente con memoria provato
• Strumenti aggiunti
• Agente autonome costruito

Prossimi Passi

1. Sperimenta: Inizia con l'agente Q&A semplice
2. Estendi: Aggiungi strumenti secondo necessità
3. Specializza: Crea agenti specifici per dominio
4. Scala: Usa sotto-agenti per workflow complessi
5. Proteggi: Implementa hook per ambienti di produzione

---

Domande Frequenti (FAQ)

Qual è la differenza tra Claude Code e il Claude Agent SDK?

Claude Code è l'assistente di codifica completo di Anthropic – un prodotto finito che puoi usare nel tuo terminale.

Il Claude Agent SDK è il framework sottostante che ti permette di costruire i tuoi agenti per qualsiasi caso d'uso. L'SDK ti dà i blocchi di costruzione che alimentano anche Claude Code.

Ho bisogno di conoscenze di programmazione per l'SDK?

Conoscenze base di Python sono utili ma non strettamente necessarie. Puoi seguire gli esempi semplici di questa guida anche senza esperienza approfondita di programmazione.

Tuttavia, per agenti pronti per la produzione, raccomandiamo solide basi di Python.

Quanto costa usare il Claude Agent SDK?

Usare l'SDK stesso è gratuito. Paghi solo per le chiamate API a Claude.

Sonnet costa circa 3$ per milione di token in ingresso e 15$ per milione di token in uscita (gennaio 2026). Per sviluppo e test, raccomandiamo di iniziare con contesti piccoli.

Posso usare l'SDK con altri modelli IA?

Il Claude Agent SDK è specificamente ottimizzato per i modelli Claude.

Per altri modelli come GPT-4 o Gemini, esistono SDK alternativi come OpenAI Agents SDK o Google ADK. Tuttavia, i concetti (Agent Loop, Strumenti, Memoria) sono trasferibili.

Come proteggo il mio agente per l'uso in produzione?

Tre passi importanti:

1. Imposta permission_mode su "manual" o "acceptEdits" invece di "acceptAll"
2. Definisci esplicitamente allowed_tools con solo gli strumenti necessari
3. Implementa hook per controlli di sicurezza e logging

Per applicazioni critiche, aggiungi approvazioni umane nel ciclo.

---

Risorse Aggiuntive

• Documentazione Ufficiale: docs.claude.com/en/api/agent-sdk
• Blog Ingegneria Anthropic: anthropic.com/engineering
• Specifica MCP: modelcontextprotocol.io
• Claude Code: anthropic.com/claude-code

---

Questa guida è stata creata per sviluppatori e appassionati di IA che muovono i primi passi con gli agenti IA. Il Claude Code Agent SDK è in continua evoluzione – visita la documentazione ufficiale per gli ultimi aggiornamenti.