- 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. Se non ne hai uno, 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. npm stampa added N packages quando l’installazione ha successo.Sia l’SDK TypeScript che quello Python includono un binario Claude Code nativo, quindi la maggior parte delle installazioni non necessita di un’installazione separata di Claude Code. Alcune installazioni non hanno un binario incluso:
- Se pip installa la distribuzione del codice sorgente dell’SDK Python invece di una wheel della piattaforma, ad esempio su ARM64 Windows, nessun binario è incluso. Installa Claude Code nativamente. L’SDK Python lo trova nel tuo
PATH. - L’SDK TypeScript installa il suo binario tramite dipendenze opzionali npm, quindi un’installazione che le salta, ad esempio
npm ci --omit=optional, non ottiene alcun binario anche su una piattaforma supportata. Reinstalla senza saltare le dipendenze opzionali, o installa Claude Code nativamente e impostapathToClaudeCodeExecutableal suo percorso.
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 Foundry: 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 rate limit 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, l’esecuzione dello strumento, la gestione del contesto e i 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 un errore di autenticazione come
Not logged in o Invalid API key, 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.Per le cause e le correzioni dietro questi e altri errori di autenticazione, vedi Errori di autenticazione nel riferimento degli errori.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"
Ognuno di questi frammenti imposta campi sullo stesso oggetto opzioni. Per ulteriori informazioni, vedi Configura il tuo agente.
Concetti chiave
Tools controllano cosa può fare il tuo agente:
Permission modes controllano quanto controllo umano desideri. L’SDK valuta la modalità attiva insieme alle tue regole di allow e deny in un ordine fisso, descritto in How permissions are evaluated. Per l’elenco completo delle modalità, il loro comportamento e quando utilizzare ciascuna, vedi Permission mode in How the agent loop works.
Passaggi successivi
Ora che hai creato il tuo primo agente, scopri come estendere le sue capacità e adattarlo al tuo caso d’uso:- Configura il tuo agente: componi l’oggetto options e trova la pagina che copre ogni impostazione
- 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
- Troubleshooting: risolvi gli errori quando la CLI non riesce ad avviarsi o esce, oppure un risultato arriva senza output strutturato