Sviluppare un agente AI con Claude Agent SDK: permessi, revisione umana ed errori

Per sviluppare un agente AI con Claude Agent SDK servono uno sviluppatore, una chiave API di Anthropic e Python 3.10 o Node.js 18. Serve anche un elenco ristretto di strumenti autorizzati. Le azioni che toccano clienti o denaro restano fuori da quell'elenco. In questo modo una persona le approva prima che vengano eseguite.

Questa guida è la seconda parte di una serie di tre sugli agenti AI in pratica. La prima parte spiega come creare un agente AI con Claude senza codice. La terza tratterà la gestione degli agenti in produzione. Questo post si rivolge a un'azienda che ha uno sviluppatore interno o un fornitore tecnico.

Il Claude Agent SDK è una libreria di Anthropic, programmabile in Python e TypeScript. Offre gli stessi strumenti, lo stesso ciclo dell'agente e la stessa gestione del contesto che fanno funzionare Claude Code. Anthropic lo chiamava Claude Code SDK e lo ha poi rinominato. Un agente, nella definizione della documentazione, è un'applicazione che completa un compito pianificando da sola i passi e chiamando strumenti.

La differenza rispetto a una semplice chiamata al modello è che con l'SDK Claude esegue direttamente gli strumenti. Lo sviluppatore non deve implementarli uno per uno. Per questo la domanda centrale riguarda che cosa gli si permette di fare dentro sistemi reali come Zoho CRM.

Il Claude Agent SDK richiede Node.js 18 o successivo, oppure Python 3.10 o successivo, e un account Anthropic. Il pacchetto Python si chiama claude-agent-sdk su PyPI. Quello TypeScript si chiama @anthropic-ai/claude-agent-sdk su npm. Entrambi includono un binario nativo di Claude Code, quindi di norma non serve un'installazione separata.

I due comandi seguenti installano l'SDK Python e impostano la chiave API. Vanno eseguiti nel terminale della macchina, o del server, su cui girerà l'agente.

pip install claude-agent-sdk
export ANTHROPIC_API_KEY=your-api-key

Al posto di your-api-key va inserita la chiave della console Anthropic. L'SDK legge la chiave dall'ambiente del processo che esegue l'agente e non carica da solo i file .env. Chi conserva la chiave in un file .env deve quindi caricarlo esplicitamente. L'autenticazione funziona anche tramite Amazon Bedrock, Claude Platform on AWS, Google Cloud e Microsoft Foundry. Per Bedrock si imposta la variabile CLAUDE_CODE_USE_BEDROCK=1 con le credenziali AWS.

L'uso dell'SDK è regolato dai Commercial Terms of Service di Anthropic, anche quando alimenta prodotti offerti ai propri clienti. Salvo approvazione preventiva, non è consentito offrire il login di claude.ai o i suoi limiti d'uso in un prodotto costruito sull'SDK. Il nome del prodotto può essere, per esempio, "NomeAgente Powered by Claude". Non può chiamarsi "Claude Code" né "Claude Code Agent".

Il ciclo dell'agente descritto da Anthropic ha quattro fasi: raccogliere il contesto, compiere un'azione, verificare il lavoro e ripetere. Il principio di progetto dell'SDK è dare all'agente un computer, così che lavori come farebbe una persona. L'agente legge file, esegue comandi e controlla il risultato prima di passare al passo successivo.

L'SDK gestisce orchestrazione, esecuzione degli strumenti, gestione del contesto e nuovi tentativi. Lo sviluppatore consuma il flusso di messaggi che l'agente produce. Le funzioni principali sono queste:

• Strumenti integrati: Read, Edit, Glob, Grep e Bash per leggere, modificare e cercare file o eseguire comandi.
• Hook: codice personalizzato eseguito in punti precisi del ciclo di vita dell'agente.
• Subagenti: agenti secondari con una propria finestra di contesto isolata, che restituiscono all'orchestratore solo le informazioni rilevanti.
• Server MCP: collegamenti a strumenti e dati esterni.
• Permessi e sessioni: regole su che cosa l'agente può fare e memoria del lavoro svolto.

La funzione di compattazione riassume automaticamente i messaggi precedenti quando il limite di contesto si avvicina. Per la ricerca nei documenti, Anthropic suggerisce di partire dalla ricerca agentica e di aggiungere la ricerca semantica solo se servono risultati più rapidi. Sulla fase di verifica, lo stesso articolo definisce poco robusto, in generale, affidare il giudizio a un altro modello linguistico. Per un processo aziendale conviene quindi prevedere controlli a regole e, dove conta, una persona.

L'agente minimo del quickstart ufficiale chiede a Claude di cercare errori in un file e correggerli. La funzione query è il punto di ingresso che crea il ciclo dell'agente e restituisce un iteratore asincrono. Il codice seguente va salvato in un file, per esempio agent.py, nella cartella su cui l'agente deve lavorare, e avviato con Python.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Ciclo agentico: trasmette i messaggi mentre Claude lavora
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Approva in automatico questi strumenti
            permission_mode="acceptEdits",  # Approva in automatico le modifiche ai file
        ),
    ):
        # Stampa un output leggibile
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Il ragionamento di Claude
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Strumento in uso
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Risultato finale


asyncio.run(main())

Le righe da cambiare sono tre. Il testo di prompt descrive il compito, e Claude decide da solo quali strumenti usare. L'elenco allowed_tools dice quali strumenti partono senza chiedere: Read, Glob e Grep bastano per un'analisi in sola lettura. permission_mode="acceptEdits" approva le modifiche ai file nella cartella di lavoro.

Per impostazione predefinita l'agente accede ai file della cartella da cui viene avviato e alle sue sottocartelle. Per questo un prototipo va eseguito in una cartella dedicata, mai nella radice di un server condiviso.

Il Model Context Protocol (MCP) è uno standard aperto per collegare gli agenti AI a strumenti e fonti di dati esterni. Un server MCP può girare come processo locale, rispondere via HTTP o essere definito direttamente nel codice dell'applicazione. Gli strumenti MCP prendono il nome secondo lo schema mcp__<nome-server>__<nome-strumento>.

L'esempio seguente, tratto dalla documentazione MCP dell'SDK, collega un server HTTP e autorizza tutti i suoi strumenti. Va salvato come file Python separato e avviato come il precedente.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "claude-code-docs": {
                "type": "http",
                "url": "https://code.claude.com/docs/mcp",
            }
        },
        allowed_tools=["mcp__claude-code-docs__*"],
    )

    async for message in query(
        prompt="Use the docs MCP server to explain what hooks are in Claude Code",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

In un progetto reale si sostituiscono il nome claude-code-docs e l'indirizzo url con quelli del server MCP del CRM o della posta dell'azienda. Si cambia di conseguenza anche la voce in allowed_tools. Il carattere jolly autorizza ogni strumento del server. In produzione conviene elencare solo gli strumenti di lettura, uno per uno.

Gli strumenti MCP richiedono un permesso esplicito: senza permesso Claude li vede ma non può chiamarli. La modalità acceptEdits non li approva. L'SDK non apre un browser e non gestisce un flusso OAuth interattivo, quindi le credenziali vanno preparate prima. La connessione a un server scade dopo 30 secondi per impostazione predefinita. Per capire dove un assistente legge e scrive nei sistemi, è utile anche la guida all'assistente AI negli strumenti aziendali.

Le modalità di permesso sono le impostazioni che stabiliscono quanta supervisione umana riceve l'agente. Quando Claude chiede uno strumento, l'SDK controlla in un ordine fisso di sei passi: hook, regole deny, regole ask, modalità attiva, regole allow e infine la callback canUseTool. Una regola deny blocca lo strumento in qualsiasi modalità.

La tabella confronta le modalità documentate e il loro uso sensato in un processo che tocca dati aziendali.

La modalità bypassPermissions merita un avvertimento esplicito. L'elenco allowed_tools non la limita: con allowed_tools=["Read"] approva comunque ogni strumento, compresi Bash, Write ed Edit. Su un agente collegato a clienti, fatture o pagamenti non va usata. La modalità si può cambiare a sessione in corso con set_permission_mode() in Python o setPermissionMode() in TypeScript.

La callback canUseTool è una funzione, passata nelle opzioni di query, che scatta quando Claude ha bisogno di una decisione. Riceve il nome dello strumento e i dati dell'azione proposta. L'esecuzione resta in pausa finché la callback non risponde con allow o deny.

Il frammento TypeScript seguente è la parte decisionale dell'esempio ufficiale. Va inserito dentro l'oggetto delle opzioni passato a query, accanto a allowedTools.

canUseTool: async (toolName, input) => {
  // ... mostrare l'azione proposta a una persona e leggere la risposta ...
  if (response.toLowerCase() === "y") {
    return { behavior: "allow", updatedInput: input };
  } else {
    return { behavior: "deny", message: "User denied this action" };
  }
}

La riga da adattare è il commento: lì il codice mostra l'azione a una persona, per esempio in un'interfaccia interna, e ne legge la risposta. Anche il testo di message va adattato, perché Claude legge il motivo del rifiuto e può cambiare approccio.

Tre dettagli contano in produzione. Primo, la callback non scatta mai per gli strumenti approvati in automatico, quindi un'azione nell'elenco allow non arriva mai a una persona. Secondo, la callback può restare in attesa senza limite di tempo. Se l'approvazione arriva ore dopo, un hook PreToolUse può restituire la decisione defer e riprendere più tardi dalla sessione salvata. Terzo, l'hook PermissionRequest può inviare una notifica via Slack, email o push quando Claude attende un'approvazione.

L'agente per le email dei fornitori della prima parte, costruito con il Claude Agent SDK, legge i messaggi in arrivo, cerca il fornitore nel CRM e prepara una risposta. La differenza rispetto alla versione senza codice è che ogni permesso è scritto nel codice e si può rileggere riga per riga.

La configurazione segue lo schema bloccato raccomandato dalla documentazione. Nelle opzioni si collegano due server MCP, uno per Zoho Mail e uno per il CRM. L'elenco allowed_tools contiene solo gli strumenti di lettura: leggere un messaggio, cercare un contatto, leggere un ordine. Lo strumento che invia l'email resta fuori dall'elenco.

A questo punto ci sono due scelte, entrambe legittime:

• Invio con approvazione: lo strumento di invio non è nell'elenco allow, quindi ogni tentativo arriva a canUseTool e una persona decide.
• Solo bozza: lo strumento di invio va in disallowed_tools; Claude non lo vede, non può tentarlo e si limita a preparare il testo.

La seconda scelta è la più prudente per le prime settimane. Una regola deny con il solo nome dello strumento lo rimuove dalla richiesta, e nessun hook con esito allow la scavalca. Quando le bozze risultano affidabili, si passa alla prima scelta senza riscrivere il resto dell'agente.

Gli errori più frequenti nel passaggio alla produzione nascono da impostazioni comode nel prototipo e pericolose con dati reali. Da Svennis, prima di ogni messa in produzione, rileggiamo con il cliente l'elenco allowed_tools strumento per strumento e togliamo tutto ciò che scrive verso clienti o sistemi contabili. Così quelle azioni passano sempre da una persona.

Gli errori da controllare, uno per uno, sono questi:

• bypassPermissions lasciata attiva: in demo fa risparmiare clic, in produzione approva ogni strumento.
• Carattere jolly non ancorato: allowed_tools=["*"] o ["mcp__*"] viene ignorato con un avviso e non approva nulla, quindi l'agente sembra rotto.
• Fiducia in acceptEdits per il CRM: la modalità non approva gli strumenti MCP.
• Chiave letta da .env: l'SDK non carica il file da solo e l'agente non si autentica.
• Cartella di lavoro troppo ampia: l'agente vede tutti i file sotto la cartella di avvio.
• Server MCP non raggiungibile: dopo cinque tentativi di riconnessione falliti il server risulta failed, oppure needs-auth se va autorizzato di nuovo.

L'ultimo punto richiede attenzione particolare. Quando un server MCP non risponde, Claude può ripiegare sugli strumenti integrati. Il registro delle esecuzioni deve quindi mostrare quale strumento è stato davvero usato.

Il costo di un agente costruito con l'SDK dipende dal modello e dai token consumati. Un token è un frammento di testo: in inglese vale circa 4 caratteri. I prezzi seguenti sono in dollari USA per milione di token, IVA esclusa, dalla pagina prezzi di Anthropic.

Due leve riducono la spesa. La Batch API sconta del 50% input e output per richieste elaborate in modo asincrono. Una lettura dalla cache del prompt costa il 10% del prezzo di input standard, salvo i modelli che la pagina indica a parte.

Claude Managed Agents è l'alternativa ospitata, oggi in beta. Anthropic esegue il ciclo dell'agente e la sandbox, cioè l'ambiente isolato in cui girano i comandi. La sandbox può essere nel cloud di Anthropic o sull'infrastruttura del cliente. La fatturazione somma i token a prezzo standard e 0,08 dollari per ora di sessione.

Ogni richiesta a Managed Agents richiede l'header beta managed-agents-2026-04-01, attivo per impostazione predefinita su tutti gli account API. Managed Agents non è oggi idoneo alla Zero Data Retention, perché conserva lo stato per progetto.

Per un'azienda italiana, sviluppare un agente con il Claude Agent SDK significa decidere tre cose prima di scrivere codice: il contratto, il luogo dei dati e la responsabilità delle azioni. Il contratto è quello commerciale di Anthropic, anche se l'agente serve clienti finali. I prezzi sono in dollari USA e vanno letti al netto dell'IVA.

Sul luogo dei dati, la documentazione offre strade diverse. I modelli Claude sono disponibili anche su Amazon Bedrock e Google Cloud, e l'SDK si autentica tramite questi servizi. Un'azienda che ha già un contratto cloud può quindi valutare se passare da lì. Con Managed Agents la cronologia degli eventi resta salvata sui server di Anthropic. Chi tratta dati di clienti deve tenerne conto, insieme all'assenza di Zero Data Retention per quel servizio.

Sulla responsabilità, l'SDK fornisce gli strumenti ma non decide chi approva. Conviene scrivere per ogni azione chi la autorizza e con quale strumento: un'offerta in Zoho CRM, un ticket in Zoho Desk, un'email a un fornitore. Prima di automatizzare decisioni che riguardano persone conviene verificare con il proprio consulente legale l'art. 22 del GDPR, l'AI Act e la legge italiana sull'intelligenza artificiale (L. 132/2025). Per l'AI Act è disponibile anche il testo annotato in italiano.

Il primo passo concreto è scegliere un solo processo, con un inizio e una fine chiari, e scrivere l'elenco degli strumenti che l'agente potrà usare. Accanto a ogni strumento va indicato se legge, scrive o invia. Tutto ciò che invia o registra importi resta fuori da allowed_tools.

Poi, in ordine:

1. Installare l'SDK in un ambiente di prova e far girare l'agente minimo su una cartella dedicata.
2. Collegare il server MCP del CRM in sola lettura e verificare i nomi degli strumenti.
3. Aggiungere canUseTool con un'interfaccia che mostri a una persona l'azione proposta.
4. Far lavorare l'agente in modalità bozza per alcune settimane e confrontare le bozze con le risposte reali.
5. Scegliere il modello in base ai costi misurati, non a quelli stimati.

Se il processo da automatizzare non è ancora chiaro, la valutazione di prontezza all'AI aiuta a capire da dove partire. Per vedere quali processi si prestano meglio a un agente, è utile la pagina sull'automazione dei processi con l'AI per le PMI. La terza parte di questa serie tratterà la gestione degli agenti in produzione.