Guida rapida

Inizia con l'Agent SDK per Python o TypeScript per creare agenti AI che funzionano autonomamente

Utilizza l'Agent SDK per creare un agente AI che legge il tuo codice, trova i bug e li corregge, il tutto senza intervento manuale.

Quello che farai:

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

Crea una cartella di progetto

Crea una nuova directory per questa guida rapida:

mkdir my-agent
cd my-agent

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.

Installa l'SDK

Installa il pacchetto Agent SDK per il tuo linguaggio:

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

Impostare "type": "module" in package.json consente al tuo script agente di utilizzare await di livello superiore, e tsx esegue i file TypeScript direttamente.

npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

tsx esegue i file TypeScript direttamente. Se il tuo progetto utilizza CommonJS, nomina il tuo script agente agent.mts invece di agent.ts. L'estensione .mts fa sì che tsx tratti il file come un modulo ES, quindi await di livello superiore funziona senza convertire l'intero progetto a moduli ES. Utilizza agent.mts al posto di agent.ts nei passaggi di creazione ed esecuzione successivi in questa guida rapida.

uv è un gestore di pacchetti Python veloce che gestisce automaticamente gli ambienti virtuali:

uv init
uv add claude-agent-sdk

Crea e attiva un ambiente virtuale, quindi installa il pacchetto.

Su macOS o Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Su Windows:

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

Se PowerShell blocca Activate.ps1 con un errore di criterio di esecuzione, esegui prima Set-ExecutionPolicy -Scope Process RemoteSigned.

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:

export ANTHROPIC_API_KEY=your-api-key

$env:ANTHROPIC_API_KEY = "your-api-key"

L'SDK legge la chiave dall'ambiente del processo che esegue il tuo agente; non carica automaticamente i file .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=1 e configura le credenziali AWS
Claude Platform on AWS: imposta CLAUDE_CODE_USE_ANTHROPIC_AWS=1 e ANTHROPIC_AWS_WORKSPACE_ID, quindi configura le credenziali AWS
Google Vertex AI: imposta la variabile di ambiente CLAUDE_CODE_USE_VERTEX=1 e configura le credenziali Google Cloud
Microsoft Azure: imposta la variabile di ambiente CLAUDE_CODE_USE_FOUNDRY=1 e configura le credenziali Azure

Consulta le guide di configurazione per Bedrock, Claude Platform on AWS, Vertex AI, o Azure AI Foundry per i dettagli.

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. Crea utils.py nella directory my-agent e incolla il seguente codice:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

Questo codice ha due bug:

calculate_average([]) si arresta in modo anomalo con una divisione per zero
get_user_name(None) si arresta in modo anomalo con un TypeError

Costruisci un agente che trova e corregge i bug

Crea agent.py se stai utilizzando l'SDK Python, o agent.ts per TypeScript. Utilizza agent.mts invece se il tuo progetto esistente utilizza CommonJS:

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


async def main():
# Agentic loop: streams messages as Claude works
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"],  # Auto-approve these tools
permission_mode="acceptEdits",  # Auto-approve file edits
),
):
# Print human-readable output
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)  # Claude's reasoning
elif hasattr(block, "name"):
print(f"Tool: {block.name}")  # Tool being called
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}

Questo codice ha tre parti principali:

query: il punto di ingresso principale che crea il loop agentico. Restituisce un iteratore asincrono, quindi usi async for per 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 utilizza allowedTools per pre-approvare Read, Edit e Glob, e permissionMode: "acceptEdits" per auto-approvare i cambiamenti ai file. Altre opzioni includono systemPrompt, mcpServers e altro. Vedi tutte le opzioni per Python o TypeScript.

Il loop 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.

Esegui il tuo agente

Il tuo agente è pronto. Eseguilo con il seguente comando:

npx tsx agent.ts

Se hai nominato il tuo script agent.mts, esegui npx tsx agent.mts invece.

uv run agent.py

Con il tuo ambiente virtuale ancora attivato:

python agent.py

Mentre lavora, l'agente stampa il suo ragionamento e ogni strumento che chiama, terminando con 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.py per 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

Questo è ciò che rende diverso l'Agent SDK: Claude esegue gli strumenti direttamente invece di chiederti di implementarli.

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:

options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "acceptEdits"
}
};

Dai a Claude un prompt di sistema personalizzato:

options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
}
};

Esegui comandi nel terminale:

options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};

Con 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:

Tools	Cosa può fare l'agente
`Read`, `Glob`, `Grep`	Analisi di sola lettura
`Read`, `Edit`, `Glob`	Analizzare e modificare il codice
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Automazione completa

Permission modes controllano quanto controllo umano desideri:

Mode	Comportamento	Caso d'uso
`acceptEdits`	Auto-approva le modifiche ai file e i comandi comuni del file system, chiede per altre azioni	Flussi di lavoro di sviluppo affidabili
`plan`	Esegue strumenti di sola lettura; le modifiche ai file non vengono mai auto-approvate e raggiungono il tuo callback `canUseTool`	Definizione dell'ambito di un compito prima di approvare l'esecuzione
`dontAsk`	Nega tutto ciò che non è in `allowedTools`	Agenti headless bloccati
`auto` (solo TypeScript)	Un classificatore di modelli approva o nega ogni chiamata di strumento	Agenti autonomi con protezioni di sicurezza
`bypassPermissions`	Esegue ogni strumento senza prompt, a meno che una regola `ask` esplicita non corrisponda	CI sandbox, ambienti completamente affidabili
`default`	Richiede un callback `canUseTool` per gestire l'approvazione	Flussi di approvazione personalizzati

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

agent-sdk/quickstart.md +36 −23

41 Installa il pacchetto Agent SDK per il tuo linguaggio:41 Installa il pacchetto Agent SDK per il tuo linguaggio:

42 42

43 <Tabs>43 <Tabs>

~~44 <Tab title="TypeScript">~~44 <Tab title="TypeScript (nuovo progetto)">

45 ```bash theme={null}45 ```bash theme={null}

46 npm init -y

47 npm pkg set type=module

46 npm install @anthropic-ai/claude-agent-sdk48 npm install @anthropic-ai/claude-agent-sdk

49 npm install --save-dev tsx

47 ```50 ```

52 Impostare `"type": "module"` in `package.json` consente al tuo script agente di utilizzare `await` di livello superiore, e [tsx](https://tsx.is) esegue i file TypeScript direttamente.

53 </Tab>

55 <Tab title="TypeScript (progetto esistente)">

56 ```bash theme={null}

57 npm install @anthropic-ai/claude-agent-sdk

58 npm install --save-dev tsx

59 ```

61 [tsx](https://tsx.is) esegue i file TypeScript direttamente. Se il tuo progetto utilizza CommonJS, nomina il tuo script agente `agent.mts` invece di `agent.ts`. L'estensione `.mts` fa sì che tsx tratti il file come un modulo ES, quindi `await` di livello superiore funziona senza convertire l'intero progetto a moduli ES. Utilizza `agent.mts` al posto di `agent.ts` nei passaggi di creazione ed esecuzione successivi in questa guida rapida.

48 </Tab>62 </Tab>

49 63

50 <Tab title="Python (uv)">64 <Tab title="Python (uv)">

85 </Step>99 </Step>

86 100

87 <Step title="Imposta la tua chiave API">101 <Step title="Imposta la tua chiave API">

~~88 Ottieni una chiave API dalla [Claude Console](https://platform.claude.com/), quindi crea un file `.env` nella directory del tuo progetto:~~102 Ottieni una chiave API dalla [Claude Console](https://platform.claude.com/), quindi impostala come variabile di ambiente nella shell in cui eseguirai il tuo agente:

89 103

104 <Tabs>

105 <Tab title="macOS / Linux">

90 ```bash theme={null}106 ```bash theme={null}

~~91 ANTHROPIC_API_KEY=your-api-key~~107 export ANTHROPIC_API_KEY=your-api-key

92 ```108 ```

109 </Tab>

110

111 <Tab title="Windows (PowerShell)">

112 ```powershell theme={null}

113 $env:ANTHROPIC_API_KEY = "your-api-key"

114 ```

115 </Tab>

116 </Tabs>

117

118 L'SDK legge la chiave dall'ambiente del processo che esegue il tuo agente; non carica automaticamente i file `.env`. Se mantieni la chiave in un file `.env`, caricala tu stesso, ad esempio con il pacchetto `dotenv`, prima di chiamare l'SDK.

93 119

94 L'SDK supporta anche l'autenticazione tramite provider API di terze parti:120 L'SDK supporta anche l'autenticazione tramite provider API di terze parti:

95 121

133 Costruisci un agente che trova e corregge i bug159 Costruisci un agente che trova e corregge i bug

134</h2>160</h2>

135 161

136Crea `agent.py` se stai utilizzando l'SDK Python, o `agent.ts` per TypeScript:162Crea `agent.py` se stai utilizzando l'SDK Python, o `agent.ts` per TypeScript. Utilizza `agent.mts` invece se il tuo progetto esistente utilizza CommonJS:

137 163

138<CodeGroup>164<CodeGroup>

139 ```python Python theme={null}165 ```python Python theme={null}

218 ```bash theme={null}244 ```bash theme={null}

219 npx tsx agent.ts245 npx tsx agent.ts

220 ```246 ```

247

248 Se hai nominato il tuo script `agent.mts`, esegui `npx tsx agent.mts` invece.

221 </Tab>249 </Tab>

222 250

223 <Tab title="Python (uv)">251 <Tab title="Python (uv)">

235 </Tab>263 </Tab>

236</Tabs>264</Tabs>

237 265

238Dopo l'esecuzione, controlla `utils.py`. Vedrai codice difensivo che gestisce elenchi vuoti e utenti nulli. Il tuo agente autonomamente:266Mentre lavora, l'agente stampa il suo ragionamento e ogni strumento che chiama, terminando con `Done: success`. Dopo l'esecuzione, controlla `utils.py`. Vedrai codice difensivo che gestisce elenchi vuoti e utenti nulli. Il tuo agente autonomamente:

239 267

2401. **Ha letto** `utils.py` per comprendere il codice2681. **Ha letto** `utils.py` per comprendere il codice

2412. **Ha analizzato** la logica e identificato i casi limite che causerebbero arresti anomali2692. **Ha analizzato** la logica e identificato i casi limite che causerebbero arresti anomali

244Questo è ciò che rende diverso l'Agent SDK: Claude esegue gli strumenti direttamente invece di chiederti di implementarli.272Questo è ciò che rende diverso l'Agent SDK: Claude esegue gli strumenti direttamente invece di chiederti di implementarli.

245 273

246<Note>274<Note>

247 Se vedi "API key not found", assicurati di aver impostato la variabile di ambiente `ANTHROPIC_API_KEY` nel tuo file `.env` o nell'ambiente della shell. Vedi la [guida completa alla risoluzione dei problemi](/it/troubleshooting) per ulteriore aiuto.275 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](/it/troubleshooting) per ulteriore aiuto.

248</Note>276</Note>

249 277

250<h3 id="try-other-prompts">278<h3 id="try-other-prompts">

340**Permission modes** controllano quanto controllo umano desideri:368**Permission modes** controllano quanto controllo umano desideri:

341 369

343| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |371| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |

373| `plan` | Esegue strumenti di sola lettura; le modifiche ai file non vengono mai auto-approvate e raggiungono il tuo callback `canUseTool` | Definizione dell'ambito di un compito prima di approvare l'esecuzione |

347| `bypassPermissions` | Esegue ogni strumento senza prompt, a meno che una regola [`ask`](/it/agent-sdk/permissions#how-permissions-are-evaluated) esplicita non corrisponda | CI sandbox, ambienti completamente affidabili |376| `bypassPermissions` | Esegue ogni strumento senza prompt, a meno che una regola [`ask`](/it/agent-sdk/permissions#how-permissions-are-evaluated) esplicita non corrisponda | CI sandbox, ambienti completamente affidabili |

349 378

350L'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`](/it/agent-sdk/user-input) che raccoglie l'input dell'utente. Per un maggiore controllo, vedi [Permissions](/it/agent-sdk/permissions).379L'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`](/it/agent-sdk/user-input) che raccoglie l'input dell'utente. Per un maggiore controllo, vedi [Permissions](/it/agent-sdk/permissions).

351 380

352<h2 id="troubleshooting">

353 Risoluzione dei problemi

354</h2>

~~355~~

356<h3 id="api-error-thinking-type-enabled-is-not-supported-for-this-model">

357 Errore API `thinking.type.enabled` non è supportato per questo modello

358</h3>

~~359~~

360Claude Opus 4.7 sostituisce `thinking.type.enabled` con `thinking.type.adaptive`. Le versioni precedenti di Agent SDK falliscono con il seguente errore API quando selezioni `claude-opus-4-7`:

~~361~~

362```text theme={null}

363API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

364```

~~365~~

366Aggiorna a Agent SDK v0.2.111 o successivo per utilizzare Opus 4.7.

~~367~~

368<h2 id="next-steps">381<h2 id="next-steps">

369 Passaggi successivi382 Passaggi successivi

370</h2>383</h2>

agent-sdk/quickstart.md 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC

Guida rapida

Prerequisiti

Configurazione

Crea una cartella di progetto

Installa l'SDK

Imposta la tua chiave API

Crea un file buggy

Costruisci un agente che trova e corregge i bug

Esegui il tuo agente

Prova altri prompt

Personalizza il tuo agente

Concetti chiave

Passaggi successivi