- Configurare un progetto con l’Agent SDK
- Creare un file con del codice buggy
- Eseguire un agente che trova e corregge automaticamente i bug
Prerequisiti
- Node.js 18+ o Python 3.10+
- Un account Anthropic (iscriviti qui)
Configurazione
1
Crea una cartella di progetto
Crea una nuova directory per questa guida rapida:Per i tuoi progetti, puoi eseguire l’SDK da qualsiasi cartella; avrà accesso ai file in quella directory e nelle sue sottodirectory per impostazione predefinita.
2
Installa l'SDK
Installa il pacchetto Agent SDK per il tuo linguaggio:Impostare
- TypeScript (nuovo progetto)
- TypeScript (progetto esistente)
- Python (uv)
- Python (pip)
"type": "module" in package.json consente al tuo script agente di utilizzare await di livello superiore, e tsx esegue i file TypeScript direttamente.L’SDK TypeScript raggruppa un binario Claude Code nativo per la tua piattaforma come dipendenza opzionale, quindi non è necessario installare Claude Code separatamente.
3
Imposta la tua chiave API
Ottieni una chiave API dalla Claude Console, quindi impostala come variabile di ambiente nella shell in cui eseguirai il tuo agente:L’SDK legge la chiave dall’ambiente del processo che esegue il tuo agente; non carica automaticamente i file
- macOS / Linux
- Windows (PowerShell)
.env. Se mantieni la chiave in un file .env, caricala tu stesso, ad esempio con il pacchetto dotenv, prima di chiamare l’SDK.L’SDK supporta anche l’autenticazione tramite provider API di terze parti:- Amazon Bedrock: imposta la variabile di ambiente
CLAUDE_CODE_USE_BEDROCK=1e configura le credenziali AWS - Claude Platform on AWS: imposta
CLAUDE_CODE_USE_ANTHROPIC_AWS=1eANTHROPIC_AWS_WORKSPACE_ID, quindi configura le credenziali AWS - Google Cloud’s Agent Platform: imposta la variabile di ambiente
CLAUDE_CODE_USE_VERTEX=1e configura le credenziali Google Cloud - Microsoft Azure: imposta la variabile di ambiente
CLAUDE_CODE_USE_FOUNDRY=1e configura le credenziali Azure
Se non precedentemente approvato, Anthropic non consente agli sviluppatori di terze parti di offrire il login claude.ai o limiti di velocità per i loro prodotti, inclusi gli agenti costruiti su Agent SDK di Claude. Utilizza invece i metodi di autenticazione con chiave API descritti in questo documento.
Crea un file buggy
Questa guida rapida ti guida attraverso la creazione di un agente che può trovare e correggere i bug nel codice. Per prima cosa, hai bisogno di un file con alcuni bug intenzionali che l’agente possa correggere. Creautils.py nella directory my-agent e incolla il seguente codice:
calculate_average([])si arresta in modo anomalo con una divisione per zeroget_user_name(None)si arresta in modo anomalo con un TypeError
Costruisci un agente che trova e corregge i bug
Creaagent.py se stai utilizzando l’SDK Python, o agent.ts per TypeScript. Utilizza agent.mts invece se il tuo progetto esistente utilizza CommonJS:
-
query: il punto di ingresso principale che crea il loop agentico. Restituisce un iteratore asincrono, quindi usiasync forper trasmettere i messaggi mentre Claude lavora. Vedi l’API completa nel riferimento SDK Python o TypeScript. -
prompt: quello che vuoi che Claude faccia. Claude capisce quali strumenti usare in base al compito. -
options: configurazione per l’agente. Questo esempio utilizzaallowedToolsper pre-approvareRead,EditeGlob, epermissionMode: "acceptEdits"per auto-approvare i cambiamenti ai file. Altre opzioni includonosystemPrompt,mcpServerse altro. Vedi tutte le opzioni per Python o TypeScript.
async for continua a funzionare mentre Claude pensa, chiama strumenti, osserva i risultati e decide cosa fare dopo. Ogni iterazione produce un messaggio: il ragionamento di Claude, una chiamata a uno strumento, un risultato dello strumento, o il risultato finale. L’SDK gestisce l’orchestrazione (esecuzione dello strumento, gestione del contesto, tentativi) quindi consumi semplicemente il flusso. Il loop termina quando Claude completa il compito o incontra un errore.
La gestione dei messaggi all’interno del loop filtra l’output leggibile dall’uomo. Senza filtraggio, vedresti oggetti messaggio grezzi inclusa l’inizializzazione del sistema e lo stato interno, il che è utile per il debug ma rumoroso altrimenti.
Questo esempio utilizza lo streaming per mostrare i progressi in tempo reale. Se non hai bisogno di output dal vivo (ad esempio per lavori in background o pipeline CI), puoi raccogliere tutti i messaggi contemporaneamente. Vedi Streaming vs. modalità single-turn per i dettagli.
Esegui il tuo agente
Il tuo agente è pronto. Eseguilo con il seguente comando:- TypeScript
- Python (uv)
- Python (pip)
agent.mts, esegui npx tsx agent.mts invece.Done: success. Dopo l’esecuzione, controlla utils.py. Vedrai codice difensivo che gestisce elenchi vuoti e utenti nulli. Il tuo agente autonomamente:
- Ha letto
utils.pyper comprendere il codice - Ha analizzato la logica e identificato i casi limite che causerebbero arresti anomali
- Ha modificato il file per aggiungere la gestione corretta degli errori
Se vedi “API key not found”, assicurati di aver impostato la variabile di ambiente
ANTHROPIC_API_KEY nella shell in cui esegui il tuo agente. L’SDK non carica automaticamente i file .env. Vedi la guida completa alla risoluzione dei problemi per ulteriore aiuto.Prova altri prompt
Ora che il tuo agente è configurato, prova alcuni prompt diversi:"Add docstrings to all functions in utils.py""Add type hints to all functions in utils.py""Create a README.md documenting the functions in utils.py"
Personalizza il tuo agente
Puoi modificare il comportamento del tuo agente cambiando le opzioni. Ecco alcuni esempi: Aggiungi capacità di ricerca web:Bash abilitato, prova: "Write unit tests for utils.py, run them, and fix any failures"
Concetti chiave
Tools controllano cosa può fare il tuo agente:
Permission modes controllano quanto controllo umano desideri:
L’esempio sopra utilizza la modalità
acceptEdits, che auto-approva le operazioni sui file in modo che l’agente possa funzionare senza prompt interattivi. Se desideri richiedere agli utenti l’approvazione, utilizza la modalità default e fornisci un callback canUseTool che raccoglie l’input dell’utente. Per un maggiore controllo, vedi Permissions.
Passaggi successivi
Ora che hai creato il tuo primo agente, scopri come estendere le sue capacità e adattarlo al tuo caso d’uso:- Permissions: controlla cosa può fare il tuo agente e quando ha bisogno di approvazione
- Hooks: esegui codice personalizzato prima o dopo le chiamate agli strumenti
- Sessions: costruisci agenti multi-turn che mantengono il contesto
- MCP servers: connettiti a database, browser, API e altri sistemi esterni
- Hosting: distribuisci agenti a Docker, cloud e CI/CD
- Example agents: vedi esempi completi: assistente email, agente di ricerca e altro