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 un AssistantMessage contenente il testo e le richieste di chiamate di strumenti.
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 restituisce il contenuto dei file e produce un AssistantMessage.
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.
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": il ciclo terminerà dopo il turno corrente perché 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 dopo ogni risposta di Claude, inclusa quella finale solo di testo. Contiene blocchi di contenuto di testo e blocchi di chiamate di strumenti da quel turno.
• 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


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, AssistantMessage):
                print(f"Turn completed: {len(message.content)} content blocks")
            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") {
      console.log(`Turn completed: ${message.message.content.length} content blocks`);
    }
    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. Gli strumenti non elencati sono ancora disponibili ma richiedono autorizzazione.
• 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 cosa accade agli strumenti che non sono coperti da regole di consentimento o negazione. Vedere Modalità di autorizzazione per le modalità disponibili.

​

Esecuzione parallela degli strumenti

​

Controllare come viene eseguito il ciclo

​

Turni e 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. L’intestazione della sezione è libera (non una stringa magica); il compattatore corrisponde all’intento.
• 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, non scorciatoie solo CLI. Vedere slash commands.

# 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

• 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, su Google Cloud’s Agent Platform, o dietro un ANTHROPIC_BASE_URL non di prima parte, 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.
• 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

​

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.