Come funziona il ciclo dell'agente

Comprendere il ciclo di vita dei messaggi, l'esecuzione degli strumenti, la finestra di contesto e l'architettura che alimentano gli agenti SDK.

L'Agent SDK consente di incorporare il ciclo dell'agente autonomo di Claude Code nelle proprie applicazioni. L'SDK è un pacchetto autonomo che fornisce il controllo programmatico su strumenti, autorizzazioni, limiti di costo e output.

Sia gli SDK TypeScript che Python includono un binario nativo di Claude Code, quindi la maggior parte delle installazioni non richiede un'installazione separata di Claude Code. Vedere la nota di installazione della guida rapida per le installazioni che la richiedono.

Quando avviate un agente, l'SDK esegue lo stesso ciclo di esecuzione che alimenta Claude Code: Claude valuta il vostro prompt, chiama gli strumenti per agire, riceve i risultati e ripete fino al completamento dell'attività. Questa pagina spiega cosa accade all'interno di quel ciclo in modo che possiate costruire, eseguire il debug e ottimizzare i vostri agenti in modo efficace.

Il ciclo a colpo d'occhio

Ogni sessione dell'agente segue lo stesso ciclo:

1. Ricevere il prompt. Claude riceve il vostro prompt, insieme al prompt di sistema, alle definizioni degli strumenti e alla cronologia della conversazione. L'SDK produce un SystemMessage con sottotipo "init" contenente i metadati della sessione.
2. Valutare e rispondere. Claude valuta lo stato attuale e determina come procedere. Può rispondere con testo, richiedere una o più chiamate di strumenti, o entrambi. L'SDK produce uno o più oggetti AssistantMessage, uno per ogni blocco di contenuto, come un blocco di testo o una richiesta di chiamata di strumento.
3. Eseguire gli strumenti. L'SDK esegue ogni strumento richiesto e raccoglie i risultati. Ogni set di risultati degli strumenti viene restituito a Claude per la decisione successiva. Potete utilizzare hooks per intercettare, modificare o bloccare le chiamate di strumenti prima che vengano eseguite.
4. Ripetere. I passaggi 2 e 3 si ripetono come un ciclo. Ogni ciclo completo è un turno. Claude continua a chiamare gli strumenti ed elaborare i risultati fino a quando non produce una risposta senza chiamate di strumenti.
5. Restituire il risultato. L'SDK produce un AssistantMessage finale con la risposta di testo (senza chiamate di strumenti), seguito da un ResultMessage con il testo finale, l'utilizzo dei token, il costo e l'ID della sessione.

Una domanda rapida ("quali file ci sono qui?") potrebbe richiedere uno o due turni di chiamata di Glob e risposta con i risultati. Un'attività complessa ("refactorizza il modulo di autenticazione e aggiorna i test") può concatenare dozzine di chiamate di strumenti su molti turni, leggendo file, modificando codice ed eseguendo test, con Claude che adatta il suo approccio in base a ogni risultato.

Turni e messaggi

Un turno è un viaggio di andata e ritorno all'interno del ciclo: Claude produce output che include chiamate di strumenti, l'SDK esegue quegli strumenti e i risultati vengono restituiti a Claude automaticamente. Questo accade senza cedere il controllo al vostro codice. I turni continuano fino a quando Claude non produce output senza chiamate di strumenti, a quel punto il ciclo termina e il risultato finale viene consegnato.

Considerate come potrebbe apparire una sessione completa per il prompt "Correggi i test falliti in auth.ts".

Per prima cosa, l'SDK invia il vostro prompt a Claude e produce un SystemMessage con i metadati della sessione. Poi il ciclo inizia:

1. Turno 1: Claude chiama Bash per eseguire npm test. L'SDK produce un AssistantMessage con la chiamata dello strumento, esegue il comando, poi produce un UserMessage con l'output (tre errori).
2. Turno 2: Claude chiama Read su auth.ts e auth.test.ts. L'SDK produce un AssistantMessage per ogni chiamata e restituisce il contenuto dei file.
3. Turno 3: Claude chiama Edit per correggere auth.ts, poi chiama Bash per rieseguire npm test. Tutti e tre i test passano. L'SDK produce un AssistantMessage per ogni chiamata.
4. Turno finale: Claude produce una risposta solo di testo senza chiamate di strumenti: "Corretto il bug di autenticazione, tutti e tre i test passano ora." L'SDK produce un AssistantMessage finale con questo testo, poi un ResultMessage con lo stesso testo più costo e utilizzo.

Erano quattro turni: tre con chiamate di strumenti, uno con risposta solo di testo finale.

Potete limitare il ciclo con max_turns / maxTurns, che conta solo i turni di utilizzo degli strumenti. Ad esempio, max_turns=2 nel ciclo precedente si sarebbe fermato prima del passaggio di modifica. Potete anche utilizzare max_budget_usd / maxBudgetUsd per limitare i turni in base a una soglia di spesa.

Senza limiti, il ciclo viene eseguito fino a quando Claude non termina da solo, il che va bene per attività ben definite ma può durare a lungo su prompt aperti ("migliora questo codebase"). Impostare un budget è una buona impostazione predefinita per gli agenti di produzione. Vedere Turni e budget di seguito per il riferimento alle opzioni.

Tipi di messaggi

Mentre il ciclo viene eseguito, l'SDK produce un flusso di messaggi. Ogni messaggio ha un tipo che vi dice da quale fase del ciclo proviene. I cinque tipi principali sono:

• SystemMessage: eventi del ciclo di vita della sessione. Il campo subtype li distingue:

  • "init": metadati della sessione per l'esecuzione. Quando un hook SessionStart o Setup viene eseguito durante l'avvio della sessione, i suoi messaggi del ciclo di vita dell'hook arrivano prima del messaggio init
  • "compact_boundary": si attiva dopo la compattazione
  • "informational": banner di stato in testo semplice dal ciclo
  • "worker_shutting_down": l'host sta uscendo o Remote Control si è disconnesso

  In TypeScript, ogni sottotipo diverso da "init" è il suo proprio tipo nell'unione SDKMessage piuttosto che un sottotipo di SDKSystemMessage.

• AssistantMessage: emesso per ogni blocco di contenuto nelle risposte di Claude, incluso quello finale solo di testo. Ogni messaggio contiene un singolo blocco di contenuto, come testo o una chiamata di strumento, e i messaggi da una risposta condividono un ID messaggio.

• UserMessage: emesso dopo ogni esecuzione di strumento con il risultato dello strumento inviato di nuovo a Claude. Emesso anche per qualsiasi input dell'utente che trasmettete a metà ciclo.

• StreamEvent: emesso solo quando i messaggi parziali sono abilitati. Contiene eventi di streaming API grezzi (delta di testo, chunk di input dello strumento). Vedere Stream responses.

• ResultMessage: segna la fine del ciclo dell'agente. Contiene il risultato di testo finale, l'utilizzo dei token, il costo e l'ID della sessione. Controllate il campo subtype per determinare se l'attività ha avuto successo o ha raggiunto un limite. Un piccolo numero di eventi di sistema finali, come prompt_suggestion, può arrivare dopo di esso, quindi iterate il flusso fino al completamento piuttosto che interrompere al risultato. Vedere Gestire il risultato.

Questi cinque tipi coprono l'intero ciclo di vita del ciclo dell'agente. Entrambi gli SDK producono anche eventi di osservabilità come lo stato dei limiti di velocità e le notifiche di attività che non sono necessari per guidare il ciclo. Vedere il riferimento ai tipi di messaggi Python e il riferimento ai tipi di messaggi TypeScript per gli elenchi completi.

Gestire i messaggi

Quali messaggi gestite dipende da ciò che state costruendo:

• Solo risultati finali: gestite ResultMessage per ottenere l'output, il costo e se l'attività ha avuto successo o ha raggiunto un limite.
• Aggiornamenti di progresso: gestite AssistantMessage per vedere cosa sta facendo Claude ad ogni turno, inclusi gli strumenti che ha chiamato.
• Streaming in tempo reale: abilitate i messaggi parziali (include_partial_messages in Python, includePartialMessages in TypeScript) per ottenere messaggi StreamEvent in tempo reale. Vedere Stream responses in real-time.

Come controllate i tipi di messaggi dipende dall'SDK:

• Python: controllate i tipi di messaggi con isinstance() rispetto alle classi importate da claude_agent_sdk (ad esempio, isinstance(message, ResultMessage)).
• TypeScript: controllate il campo stringa type (ad esempio, message.type === "result"). AssistantMessage e UserMessage avvolgono il messaggio API grezzo in un campo .message, quindi i blocchi di contenuto si trovano in message.message.content, non in message.content.

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock


async def main():
try:
async for message in query(prompt="Summarize this project"):
if isinstance(message, AssistantMessage):
# Each AssistantMessage carries one content block
for block in message.content:
if isinstance(block, TextBlock):
print(f"Claude: {block.text}")
elif isinstance(block, ToolUseBlock):
print(f"Tool call: {block.name}")
if isinstance(message, ResultMessage):
if message.subtype == "success":
print(message.result)
else:
print(f"Stopped: {message.subtype}")
except Exception as error:
# A single-shot query() raises after yielding an error result. If the
# failure was an error result, the error subtype branches above have
# already run; connection or process failures yield no result message.
print(f"Session ended with an error: {error}")


asyncio.run(main())

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

try {
for await (const message of query({ prompt: "Summarize this project" })) {
if (message.type === "assistant") {
// Each assistant message carries one content block
for (const block of message.message.content) {
if (block.type === "text") {
console.log(`Claude: ${block.text}`);
} else if (block.type === "tool_use") {
console.log(`Tool call: ${block.name}`);
}
}
}
if (message.type === "result") {
if (message.subtype === "success") {
console.log(message.result);
} else {
console.log(`Stopped: ${message.subtype}`);
}
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the error subtype branches above have
// already run; connection or process failures yield no result message.
console.log(`Session ended with an error: ${error}`);
}

Esecuzione degli strumenti

Gli strumenti danno al vostro agente la capacità di agire. Senza strumenti, Claude può solo rispondere con testo. Con gli strumenti, Claude può leggere file, eseguire comandi, cercare codice e interagire con servizi esterni.

Strumenti integrati

L'SDK include gli stessi strumenti che alimentano Claude Code:

Sui modelli che non ottengono gli strumenti di tracciamento delle attività, Claude Code fornisce TaskCreate e TaskUpdate solo quando vi iscrivete.

Oltre agli strumenti integrati, potete:

• Connettere servizi esterni con server MCP (database, browser, API)
• Definire strumenti personalizzati con gestori di strumenti personalizzati
• Caricare skills del progetto tramite setting sources per flussi di lavoro riutilizzabili

Autorizzazioni degli strumenti

Claude determina quali strumenti chiamare in base all'attività, ma voi controllate se quelle chiamate sono autorizzate a essere eseguite. Potete approvare automaticamente strumenti specifici, bloccare altri completamente, o richiedere l'approvazione per tutto. Tre opzioni lavorano insieme per determinare cosa viene eseguito:

• allowed_tools / allowedTools approva automaticamente gli strumenti elencati. Un agente di sola lettura con ["Read", "Glob", "Grep"] nel suo elenco di strumenti consentiti esegue quegli strumenti senza chiedere. Gli strumenti non elencati sono ancora disponibili, e le chiamate a essi che necessitano di approvazione ricadono nella modalità di autorizzazione e in canUseTool.
• disallowed_tools / disallowedTools blocca gli strumenti elencati, indipendentemente da altre impostazioni. Vedere Autorizzazioni per l'ordine in cui le regole vengono controllate prima che uno strumento venga eseguito.
• permission_mode / permissionMode controlla quanto controllo umano desiderate. L'SDK valuta la modalità attiva insieme alle vostre regole di consentimento e negazione in un ordine fisso, descritto in Come vengono valutate le autorizzazioni. Vedere Modalità di autorizzazione per le modalità disponibili.

Potete anche limitare gli strumenti individuali con regole come "Bash(npm *)" per consentire solo comandi specifici. Vedere Autorizzazioni per la sintassi completa delle regole.

Quando uno strumento viene negato, Claude riceve un messaggio di rifiuto come risultato dello strumento e in genere tenta un approccio diverso o segnala che non potrebbe procedere.

Esecuzione parallela degli strumenti

Quando Claude richiede più chiamate di strumenti in un singolo turno, entrambi gli SDK possono eseguirli contemporaneamente o sequenzialmente a seconda dello strumento. Gli strumenti di sola lettura (come Read, Glob, Grep e strumenti MCP contrassegnati come di sola lettura) possono essere eseguiti contemporaneamente. Gli strumenti che modificano lo stato (come Edit, Write e Bash) vengono eseguiti sequenzialmente per evitare conflitti.

Gli strumenti personalizzati predefiniti per l'esecuzione sequenziale. Per abilitare l'esecuzione parallela per uno strumento personalizzato, impostare readOnlyHint nelle sue annotazioni. Sia l'SDK TypeScript che Python utilizzano questo nome di campo dall'SDK MCP.

Controllare come viene eseguito il ciclo

Potete limitare quanti turni il ciclo prende, quanto costa, quanto profondamente Claude ragiona e se gli strumenti richiedono approvazione prima di essere eseguiti. Tutti questi sono campi su ClaudeAgentOptions (Python) / Options (TypeScript).

Turni e budget

Quando uno dei due limiti viene raggiunto, l'SDK restituisce un ResultMessage con un sottotipo di errore corrispondente (error_max_turns o error_max_budget_usd). Vedere Gestire il risultato per come controllare questi sottotipi e ClaudeAgentOptions / Options per la sintassi.

Il limite di budget copre i subagenti: la loro spesa conta verso il totale. Una volta che la spesa raggiunge il limite, generare un altro subagente fallisce con Budget limit reached, e Claude Code interrompe tutti i subagenti in background ancora in esecuzione. I comportamenti di applicazione del limite richiedono Claude Code v2.1.217 o successivo.

Con streaming input, un messaggio che è ancora in coda quando un turno termina al limite di max-turni rimane in coda. Claude Code non lo aggiunge alla chiamata del modello finale di quel turno. Inizia un nuovo turno per il messaggio e il conteggio di max-turni ricomincia da capo per quel turno.

Livello di sforzo

L'opzione effort controlla quanto ragionamento Claude applica. I livelli di sforzo inferiori utilizzano meno token per turno e riducono il costo. Non tutti i modelli supportano il parametro di sforzo. Vedere Effort per quali modelli lo supportano.

Se non impostate effort, Claude Code risolve il livello di sforzo da solo, nell'ordine che Regolare il livello di sforzo descrive.

Utilizzate uno sforzo inferiore per gli agenti che eseguono attività semplici e ben definite (come elencare file o eseguire un singolo grep) per ridurre il costo e la latenza. Impostare effort nelle opzioni di livello superiore query() per l'intera sessione, o per subagente con il campo effort su AgentDefinition per sovrascrivere il livello di sessione.

Modalità di autorizzazione

L'opzione della modalità di autorizzazione (permission_mode in Python, permissionMode in TypeScript) controlla se l'agente chiede l'approvazione prima di utilizzare gli strumenti:

Per le applicazioni interattive, utilizzate "default" con un callback di approvazione dello strumento per visualizzare i prompt di approvazione. Per gli agenti autonomi su una macchina di sviluppo, "acceptEdits" approva automaticamente le modifiche ai file e i comandi comuni del filesystem (mkdir, touch, mv, cp, ecc.) mentre ancora limita altri comandi Bash dietro le regole di consentimento. Riservate "bypassPermissions" per CI, container o altri ambienti isolati. Vedere Autorizzazioni per i dettagli completi.

Modello

Se non impostate model, l'SDK utilizza il predefinito di Claude Code, che dipende dal vostro metodo di autenticazione e dall'abbonamento. Impostatelo esplicitamente (ad esempio, model="claude-sonnet-5") per fissare un modello specifico o per utilizzare un modello più piccolo per agenti più veloci e economici. Vedere models per gli ID disponibili.

La finestra di contesto

La finestra di contesto è la quantità totale di informazioni disponibili a Claude durante una sessione. Non si ripristina tra i turni all'interno di una sessione. Tutto si accumula: il prompt di sistema, le definizioni degli strumenti, la cronologia della conversazione, gli input degli strumenti e gli output degli strumenti. Il contenuto che rimane lo stesso tra i turni (prompt di sistema, definizioni degli strumenti, CLAUDE.md) viene automaticamente prompt cached, il che riduce il costo e la latenza per i prefissi ripetuti. Per come un prompt di sistema personalizzato o il testo append influisce sul riutilizzo della cache tra le sessioni, vedere Modifying system prompts.

Cosa consuma il contesto

Ecco come ogni componente influisce sul contesto nell'SDK:

I grandi output degli strumenti consumano un contesto significativo. Leggere un file grande o eseguire un comando con output dettagliato può utilizzare migliaia di token in un singolo turno. Il contesto si accumula nel corso dei turni, quindi le sessioni più lunghe con molte chiamate di strumenti accumulano significativamente più contesto rispetto a quelle brevi.

Compattazione automatica

Quando la finestra di contesto si avvicina al suo limite, l'SDK compatta automaticamente la conversazione: riassume la cronologia più vecchia per liberare spazio, mantenendo intatti gli scambi più recenti e le decisioni chiave. L'SDK emette un messaggio con type: "system" e subtype: "compact_boundary" nel flusso quando questo accade (in Python questo è un SystemMessage; in TypeScript è un tipo separato SDKCompactBoundaryMessage).

La compattazione sostituisce i messaggi più vecchi con un riassunto, quindi le istruzioni specifiche dall'inizio della conversazione potrebbero non essere preservate. Le regole persistenti appartengono a CLAUDE.md (caricato tramite settingSources) piuttosto che al prompt iniziale, perché il contenuto di CLAUDE.md viene reiniettato ad ogni richiesta.

Potete personalizzare il comportamento della compattazione in diversi modi:

• Istruzioni di riassunto in CLAUDE.md: Il compattatore legge il vostro CLAUDE.md come qualsiasi altro contesto, quindi potete includere una sezione che gli dice cosa preservare quando riassume. Il compattatore corrisponde all'intento, quindi l'intestazione della sezione è libera.
• Hook PreCompact: Eseguire logica personalizzata prima che si verifichi la compattazione, ad esempio per archiviare la trascrizione completa. L'hook riceve un campo trigger (manual o auto). Vedere hooks.
• Compattazione manuale: Inviare /compact come stringa di prompt per attivare la compattazione su richiesta. I comandi inviati in questo modo sono input SDK ordinari. Vedere dispatch commands by name.

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

Mantenere il contesto efficiente

Alcune strategie per gli agenti a lunga durata:

• Utilizzare subagenti per sottoattività. Ogni subagente inizia con una conversazione fresca (nessuna cronologia di messaggi precedenti, anche se carica il suo prompt di sistema e il contesto a livello di progetto come CLAUDE.md). Non vede i turni del genitore e solo la sua risposta finale ritorna al genitore come risultato dello strumento. Il contesto dell'agente principale cresce per quel riassunto, non per la trascrizione completa della sottoattività. Vedere Cosa ereditano i subagenti per i dettagli.
• Essere selettivi con gli strumenti. Ogni definizione di strumento occupa spazio di contesto. Utilizzate il campo tools su AgentDefinition per limitare i subagenti al set minimo di cui hanno bisogno.
• Controllare i costi dei server MCP. MCP tool search differisce gli schemi degli strumenti MCP per impostazione predefinita e li carica su richiesta. Quando la ricerca degli strumenti è disattivata o ha ricaduto nel caricamento anticipato, ogni server MCP aggiunge tutti i suoi schemi di strumenti ad ogni richiesta, quindi pochi server con molti strumenti possono consumare un contesto significativo prima che l'agente faccia qualsiasi lavoro. Vedere Configure tool search per le configurazioni in cui si applica il fallback.
• Utilizzare uno sforzo inferiore per attività di routine. Impostare effort a "low" per gli agenti che hanno solo bisogno di leggere file o elencare directory. Questo riduce l'utilizzo dei token e il costo.

Per una ripartizione dettagliata dei costi di contesto per funzione, vedere Comprendere i costi di contesto.

Sessioni e continuità

Ogni interazione con l'SDK crea o continua una sessione. Catturate l'ID della sessione da ResultMessage.session_id (disponibile in entrambi gli SDK) per riprendere in seguito. L'SDK TypeScript lo espone anche come campo diretto sul SystemMessage init; in Python è annidato in SystemMessage.data.

Quando riprendete, il contesto completo dai turni precedenti viene ripristinato: file che sono stati letti, analisi che è stata eseguita e azioni che sono state intraprese. Potete anche fare un fork di una sessione per diramarvisi in un approccio diverso senza modificare l'originale.

Vedere Gestione della sessione per la guida completa sui pattern di ripresa, continuazione e fork. Per riprendere sessioni tra container stateless o host serverless, passate un adattatore session_store / sessionStore in modo che l'SDK rispecchi i transcript nel vostro backend e un altro host possa riprenderli. Il subprocess Claude Code scrive comunque prima su disco locale. Vedere Architettura dual-write per quale copia sopravvive a una sessione nuova rispetto a un'esecuzione ripresa dallo store, e come mantenere la copia locale effimera.

Gestire il risultato

Quando il ciclo termina, il ResultMessage vi dice cosa è successo e vi fornisce l'output. Il campo subtype (disponibile in entrambi gli SDK) è il modo principale per controllare lo stato di terminazione.

Il campo result contiene l'output di testo finale ed è presente solo sulla variante success, quindi controllate sempre il sottotipo prima di leggerlo.

Tutti i sottotipi di risultato portano total_cost_usd, usage, num_turns e session_id in modo che possiate tracciare il costo e riprendere anche dopo gli errori. Due cose da proteggere:

• Dopo un arresto anomalo della sessione, il risultato finale è un error_during_execution i cui campi di costo possono essere azzerati e il cui stop_reason è null, e il processo esce dopo averlo emesso. Vedere Recuperare i totali dopo un arresto anomalo della sessione.
• In Python, total_cost_usd, usage e model_usage sono tipizzati come opzionali, quindi controllate che non siano None prima di leggerli.

Il campo usage copre solo il ciclo principale dell'agente. Utilizzate modelUsage, o model_usage in Python, per la contabilità completa dei token e dei costi dell'albero. Vedere Tracciamento di costi e utilizzo per i dettagli sull'interpretazione dei campi usage.

Il risultato include anche un campo stop_reason (string | null in TypeScript, str | None in Python) che indica perché il modello ha smesso di generare al suo turno finale. I valori comuni sono end_turn (il modello ha terminato normalmente), max_tokens (ha raggiunto il limite di token di output) e refusal (il modello ha rifiutato la richiesta). Su risultati di errore che il ciclo ha prodotto, stop_reason porta il valore dall'ultima risposta dell'assistente prima che il ciclo terminasse; il risultato che Claude Code sintetizza dopo un arresto anomalo della sessione porta null.

Per rilevare i rifiuti, controllate stop_reason === "refusal" (TypeScript) o stop_reason == "refusal" (Python). Vedere SDKResultMessage (TypeScript) o ResultMessage (Python) per il tipo completo.

Hooks

Hooks sono callback che si attivano in punti specifici del ciclo: prima che uno strumento venga eseguito, dopo che ritorna, quando l'agente termina e così via. Alcuni hook comunemente utilizzati sono:

Gli hook vengono eseguiti nel vostro processo di applicazione, non all'interno della finestra di contesto dell'agente, quindi non consumano contesto. Gli hook possono anche cortocircuitare il ciclo: un hook PreToolUse che rifiuta una chiamata di strumento impedisce che venga eseguita e Claude riceve il messaggio di rifiuto invece.

Entrambi gli SDK supportano tutti gli eventi precedenti. L'SDK TypeScript include eventi aggiuntivi che Python non supporta ancora. Vedere Controllare l'esecuzione con gli hooks per l'elenco completo degli eventi, la disponibilità per SDK e l'API di callback completa.

Mettere tutto insieme

Questo esempio combina i concetti chiave di questa pagina in un singolo agente che corregge i test falliti. Configura l'agente con strumenti consentiti (pre-approvati in modo che l'agente funzioni autonomamente), impostazioni del progetto e limiti di sicurezza su turni e sforzo di ragionamento. Mentre il ciclo viene eseguito, cattura l'ID della sessione per una potenziale ripresa, gestisce il risultato finale e stampa il costo totale.

Poiché una singola chiamata query() genera un'eccezione dopo aver restituito un risultato di errore, il ciclo è avvolto in un blocco try in modo che lo script esca correttamente quando viene raggiunto un limite.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
session_id = None

try:
async for message in query(
prompt="Find and fix the bug causing test failures in the auth module",
options=ClaudeAgentOptions(
allowed_tools=[
"Read",
"Edit",
"Bash",
"Glob",
"Grep",
],  # Listing tools here auto-approves them (no prompting)
setting_sources=[
"project"
],  # Load CLAUDE.md, skills, hooks from current directory
max_turns=30,  # Prevent runaway sessions
effort="high",  # Thorough reasoning for complex debugging
),
):
# Handle the final result
if isinstance(message, ResultMessage):
session_id = message.session_id  # Save for potential resumption

if message.subtype == "success":
print(f"Done: {message.result}")
elif message.subtype == "error_max_turns":
# Agent ran out of turns. Resume with a higher limit.
print(f"Hit turn limit. Resume session {session_id} to continue.")
elif message.subtype == "error_max_budget_usd":
print("Hit budget limit.")
else:
print(f"Stopped: {message.subtype}")
if message.total_cost_usd is not None:
print(f"Cost: ${message.total_cost_usd:.4f}")
except Exception as error:
# A single-shot query() raises after yielding an error result. If the
# failure was an error result, the error subtype branches above have
# already run; connection or process failures yield no result message.
print(f"Session ended with an error: {error}")


asyncio.run(run_agent())

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

let sessionId: string | undefined;

try {
for await (const message of query({
prompt: "Find and fix the bug causing test failures in the auth module",
options: {
allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)
settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory
maxTurns: 30, // Prevent runaway sessions
effort: "high" // Thorough reasoning for complex debugging
}
})) {
// Save the session ID to resume later if needed
if (message.type === "system" && message.subtype === "init") {
sessionId = message.session_id;
}

// Handle the final result
if (message.type === "result") {
if (message.subtype === "success") {
console.log(`Done: ${message.result}`);
} else if (message.subtype === "error_max_turns") {
// Agent ran out of turns. Resume with a higher limit.
console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);
} else if (message.subtype === "error_max_budget_usd") {
console.log("Hit budget limit.");
} else {
console.log(`Stopped: ${message.subtype}`);
}
console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the error subtype branches above have
// already run; connection or process failures yield no result message.
console.log(`Session ended with an error: ${error}`);
}

Quando l'agente termina con successo, l'esempio stampa una riga Done: con il riepilogo della correzione dell'agente, quindi una riga come Cost: $0.0312.

Passaggi successivi

Ora che comprendete il ciclo, ecco dove andare a seconda di ciò che state costruendo:

• Non avete ancora eseguito un agente? Iniziate con la quickstart per ottenere l'SDK installato e vedere un esempio completo in esecuzione da capo a fondo.
• Pronti a collegarvi al vostro progetto? Caricate CLAUDE.md, skills e filesystem hooks in modo che l'agente segua automaticamente le convenzioni del vostro progetto.
• State costruendo un'interfaccia utente interattiva? Abilitate lo streaming per mostrare testo e chiamate di strumenti in tempo reale mentre il ciclo viene eseguito.
• Avete bisogno di un controllo più stretto su ciò che l'agente può fare? Bloccate l'accesso agli strumenti con autorizzazioni e utilizzate hooks per controllare, bloccare o trasformare le chiamate di strumenti prima che vengano eseguite.
• State eseguendo attività lunghe o costose? Delegate il lavoro isolato ai subagenti per mantenere il vostro contesto principale snello.
• Distribuendo come servizio? Consultate Hosting the Agent SDK per indicazioni su container e serverless, e Session storage per persistere le sessioni al vostro backend.

Per il quadro concettuale più ampio del ciclo agentic (non specifico dell'SDK), vedere Come funziona Claude Code. Per una guida pratica alla progettazione di cicli in Claude Code, dai cicli basati su turni ai cicli basati su obiettivi e cicli proattivi, vedere Loop engineering: getting started with loops sul blog.