Come funziona il ciclo dell'agente

​

Il ciclo a colpo d’occhio

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.

​

Turni e messaggi

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.

​

Tipi di messaggi

• 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.

​

Gestire i messaggi

• 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.

• 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

​

Strumenti integrati

• 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

• 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, tranne per le letture da percorsi di rete. Gli strumenti non elencati sono ancora disponibili, e le chiamate a essi che necessitano di approvazione ricadono nella modalità di permesso 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.

​

Esecuzione parallela degli strumenti

​

Controllare come viene eseguito il ciclo

​

Turni e budget

​

Margine del budget

​

Livello di sforzo

​

Modalità di autorizzazione

​

Modello

​

La finestra di contesto

​

Cosa consuma il contesto

​

Compattazione automatica

• 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

• Usa i subagent per le sottoattività. Ogni subagent inizia con una conversazione nuova (nessuna cronologia di messaggi precedenti, anche se carica il proprio 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. Il contesto dell’agente principale cresce per quel riassunto, non per la trascrizione completa della sottoattività. Consulta Cosa ereditano i subagent 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.

​

Sessioni e continuità

​

Gestire il risultato

• 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.

​

Hooks

​

Mettere tutto insieme

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}`);
}

​

Passaggi successivi

• 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 dell’Agent SDK per indicazioni su container e serverless, e Archiviazione della sessione per persistere le sessioni al vostro backend.