Vai al contenuto principale
L’Agent SDK è costruito sulla stessa base di Claude Code, il che significa che i tuoi agenti SDK hanno accesso alle stesse funzionalità basate sul filesystem: istruzioni del progetto (CLAUDE.md e regole), skills, hooks e altro ancora. Quando ometti settingSources, query() legge le stesse impostazioni del filesystem di Claude Code CLI: impostazioni utente, progetto e locali, file CLAUDE.md e skills, agenti e comandi in .claude/. Per eseguire senza questi, passa settingSources: [], che limita l’agente a ciò che configuri programmaticamente. Le impostazioni dei criteri gestiti e la configurazione globale ~/.claude.json vengono lette indipendentemente da questa opzione. Vedi Cosa settingSources non controlla. Per una panoramica concettuale di ciò che ogni funzionalità fa e quando usarla, vedi Estendi Claude Code.

Controlla le impostazioni del filesystem con settingSources

L’opzione delle fonti di impostazione (setting_sources in Python, settingSources in TypeScript) controlla quali impostazioni basate sul filesystem carica l’SDK. Passa un elenco esplicito per acconsentire a fonti specifiche, oppure passa un array vuoto per disabilitare le impostazioni utente, progetto e locali. Questo esempio carica sia le impostazioni a livello di utente che a livello di progetto impostando settingSources su ["user", "project"]:
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async for message in query(
    prompt="Help me refactor the auth module",
    options=ClaudeAgentOptions(
        # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
        # Together they give the agent access to CLAUDE.md, skills, hooks, and
        # permissions from both locations.
        setting_sources=["user", "project"],
        allowed_tools=["Read", "Edit", "Bash"],
    ),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if hasattr(block, "text"):
                print(block.text)
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(f"\nResult: {message.result}")
Ogni fonte carica le impostazioni da una posizione specifica, dove <cwd> è la directory di lavoro che passi tramite l’opzione cwd, o la directory corrente del processo se non impostata. Per la definizione del tipo completo, vedi SettingSource (TypeScript) o SettingSource (Python).
FonteCosa caricaPosizione
"project"CLAUDE.md del progetto, .claude/rules/*.md, skills del progetto, hooks del progetto, settings.json del progetto<cwd>/.claude/ per settings.json e hooks; <cwd> e ogni directory padre per CLAUDE.md e rules; <cwd> e ogni directory padre fino alla radice del repository per skills
"user"CLAUDE.md dell’utente, ~/.claude/rules/*.md, skills dell’utente, impostazioni dell’utente~/.claude/
"local"CLAUDE.local.md, .claude/settings.local.json<cwd>/.claude/ per settings.local.json; <cwd> e ogni directory padre per CLAUDE.local.md
Omettere settingSources equivale a ["user", "project", "local"]. L’opzione cwd determina dove l’SDK cerca gli input a livello di progetto. CLAUDE.md e rules vengono caricati da <cwd> e da ogni directory padre. Skills vengono caricate da <cwd> e da ogni directory padre fino alla radice del repository. settings.json e hooks del progetto vengono caricati solo da <cwd>/.claude/ senza fallback di directory padre.

Cosa settingSources non controlla

settingSources copre le impostazioni utente, progetto e locali. Alcuni input vengono letti indipendentemente dal suo valore:
InputComportamentoPer disabilitare
Impostazioni dei criteri gestitiSempre caricate quando presenti sull’hostRimuovi il file delle impostazioni gestite
Configurazione globale ~/.claude.jsonSempre lettaRiposiziona con CLAUDE_CONFIG_DIR in env
Memoria automatica in ~/.claude/projects/<project>/memory/Caricata per impostazione predefinita nel prompt di sistemaImposta autoMemoryEnabled: false nelle impostazioni, o CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env
Connettori MCP da claude.aiCaricati quando il metodo di autenticazione attivo è un abbonamento a claude.ai. Passare mcpServers: {} non li sopprimeImposta strictMcpConfig: true, o ENABLE_CLAUDEAI_MCP_SERVERS=false in env
Non fare affidamento sulle opzioni predefinite di query() per l’isolamento multi-tenant. Poiché gli input di cui sopra vengono letti indipendentemente da settingSources, un processo SDK può raccogliere la configurazione a livello di host e la memoria per directory. Per le distribuzioni multi-tenant, esegui ogni tenant nel suo proprio filesystem e imposta settingSources: [] più CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env. Vedi Distribuzione sicura.

Istruzioni del progetto (CLAUDE.md e regole)

I file CLAUDE.md e i file .claude/rules/*.md forniscono al tuo agente un contesto persistente sul tuo progetto: convenzioni di codifica, comandi di compilazione, decisioni architettoniche e istruzioni. Quando settingSources include "project" (come nell’esempio sopra), l’SDK carica questi file nel contesto all’inizio della sessione. L’agente quindi segue le tue convenzioni di progetto senza che tu le ripeta in ogni prompt.

Posizioni di caricamento di CLAUDE.md

LivelloPosizioneQuando caricato
Progetto (root)<cwd>/CLAUDE.md o <cwd>/.claude/CLAUDE.mdsettingSources include "project"
Regole del progetto<cwd>/.claude/rules/*.md e .claude/rules/*.md in ogni directory padresettingSources include "project"
Progetto (directory padre)File CLAUDE.md nelle directory sopra cwdsettingSources include "project", caricato all’inizio della sessione
Progetto (directory figlie)File CLAUDE.md nelle sottodirectory di cwdsettingSources include "project", caricato su richiesta quando l’agente legge un file in quel sottoalbero
Locale<cwd>/CLAUDE.local.md e CLAUDE.local.md in ogni directory padresettingSources include "local"
Utente~/.claude/CLAUDE.mdsettingSources include "user"
Regole dell’utente~/.claude/rules/*.mdsettingSources include "user"
Tutti i livelli sono additivi: se esistono sia file CLAUDE.md di progetto che di utente, l’agente vede entrambi. Non esiste una regola di precedenza rigida tra i livelli; se le istruzioni entrano in conflitto, il risultato dipende da come Claude le interpreta. Scrivi regole non conflittuali, o dichiara esplicitamente la precedenza nel file più specifico (“Queste istruzioni di progetto sostituiscono qualsiasi impostazione predefinita conflittuale a livello di utente”).
Puoi anche iniettare il contesto direttamente tramite systemPrompt senza usare file CLAUDE.md. Vedi Modifica i prompt di sistema. Usa CLAUDE.md quando vuoi che lo stesso contesto sia condiviso tra le sessioni interattive di Claude Code e i tuoi agenti SDK.
Per come strutturare e organizzare il contenuto di CLAUDE.md, vedi Gestisci la memoria di Claude.

Skills

Le skills sono file markdown che danno al tuo agente conoscenze specializzate e flussi di lavoro invocabili. A differenza di CLAUDE.md (che si carica ogni sessione), le skills si caricano su richiesta. L’agente riceve le descrizioni delle skills all’avvio e carica il contenuto completo quando rilevante. Le skills vengono scoperte dal filesystem tramite settingSources. Quando l’opzione skills su query() viene omessa, le skills di utente e progetto scoperte vengono abilitate e lo strumento Skill è disponibile, corrispondendo al comportamento della CLI. Per controllare quali skills sono abilitate, passa skills come "all", un elenco di nomi di skills, o [] per disabilitare tutte. Quando skills è impostato, l’SDK aggiunge automaticamente lo strumento Skill a allowedTools. Se passi anche un elenco esplicito di tools, includi "Skill" in quell’elenco in modo che Claude possa invocare le skills.
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
    prompt="Review this PR using our code review checklist",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],
        skills="all",
        allowed_tools=["Read", "Grep", "Glob"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)
Le skills devono essere create come artefatti del filesystem (.claude/skills/<name>/SKILL.md). L’SDK non ha un’API programmatica per registrare le skills. Vedi Agent Skills nell’SDK per i dettagli completi.
Per ulteriori informazioni sulla creazione e l’utilizzo delle skills, vedi Agent Skills nell’SDK.

Hooks

L’SDK supporta due modi per definire gli hooks, e vengono eseguiti fianco a fianco:
  • Filesystem hooks: comandi shell definiti in settings.json, caricati quando settingSources include la fonte rilevante. Questi sono gli stessi hooks che configureresti per sessioni interattive di Claude Code.
  • Programmatic hooks: funzioni di callback passate direttamente a query(). Questi vengono eseguiti nel tuo processo di applicazione e possono restituire decisioni strutturate. Vedi Controlla l’esecuzione con gli hooks.
Entrambi i tipi vengono eseguiti durante lo stesso ciclo di vita degli hooks. Se hai già degli hooks nel file .claude/settings.json del tuo progetto e imposti settingSources: ["project"], quegli hooks vengono eseguiti automaticamente nell’SDK senza configurazione aggiuntiva. I callback degli hooks ricevono l’input dello strumento e restituiscono un dict di decisione. Restituire {} significa consentire allo strumento di procedere. Per bloccare l’esecuzione, restituisci un oggetto hookSpecificOutput con permissionDecision: "deny" e un permissionDecisionReason. Il motivo viene inviato a Claude come risultato dello strumento. I campi di primo livello decision e reason sono deprecati per PreToolUse. Vedi la guida degli hooks per la firma completa del callback e i tipi di ritorno.
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Destructive command blocked",
            }
        }
    return {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
    prompt="Refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads hooks from .claude/settings.json
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[audit_bash]),
            ]
        },
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

Quando usare quale tipo di hook

Tipo di hookMigliore per
Filesystem (settings.json)Condividere gli hooks tra le sessioni CLI e SDK. Supporta "command" (script shell), "http" (POST a un endpoint), "mcp_tool" (chiama lo strumento di un server MCP connesso), "prompt" (LLM valuta un prompt), e "agent" (genera un agente verificatore). Questi si attivano nell’agente principale e in qualsiasi subagente che genera.
Programmatic (callback in query())Logica specifica dell’applicazione, decisioni strutturate e integrazione in-process. Questi si attivano anche all’interno dei subagenti. Il callback riceve agent_id e agent_type per distinguere.
L’SDK TypeScript supporta eventi hook aggiuntivi rispetto a Python, inclusi SessionStart, SessionEnd, TeammateIdle e TaskCompleted. Vedi la guida degli hooks per la tabella di compatibilità degli eventi completa.
Per i dettagli completi sugli hooks programmatici, vedi Controlla l’esecuzione con gli hooks. Per la sintassi degli hooks del filesystem, vedi Hooks.

Scegli la funzionalità giusta

L’Agent SDK ti dà accesso a diversi modi per estendere il comportamento del tuo agente. Se non sei sicuro di quale usare, questa tabella mappa gli obiettivi comuni all’approccio giusto.
Vuoi…UsaSuperficie SDK
Impostare le convenzioni del progetto che il tuo agente segue sempreCLAUDE.mdsettingSources: ["project"] lo carica automaticamente
Dare all’agente materiale di riferimento che carica quando rilevanteSkillsopzione settingSources + skills
Eseguire un flusso di lavoro riutilizzabile (deploy, review, release)Skills invocabili dall’utenteopzione settingSources + skills
Delegare un sottocompito isolato a un contesto fresco (ricerca, review)Subagentiparametro agents + allowedTools: ["Agent"]
Coordinare più istanze di Claude Code con elenchi di attività condivisi e messaggistica diretta tra agentiTeam di agentiNon configurato direttamente tramite le opzioni SDK. I team di agenti sono una funzionalità CLI in cui una sessione agisce come il capo del team, coordinando il lavoro tra i compagni di squadra indipendenti
Eseguire logica deterministica sulle chiamate di strumenti (audit, block, transform)Hooksparametro hooks con callback, o script shell caricati tramite settingSources
Dare a Claude accesso strutturato agli strumenti di un servizio esternoMCPparametro mcpServers
Subagenti versus team di agenti: I subagenti sono effimeri e isolati: conversazione fresca, un compito, riepilogo restituito al genitore. I team di agenti coordinano più istanze indipendenti di Claude Code che condividono un elenco di attività e si messaggiano direttamente. I team di agenti sono una funzionalità CLI. Vedi Cosa ereditano i subagenti e il confronto dei team di agenti per i dettagli.
Ogni funzionalità che abiliti aggiunge alla finestra di contesto del tuo agente. Per i costi per funzionalità e come queste funzionalità si stratificano insieme, vedi Estendi Claude Code.

Risorse correlate

  • Estendi Claude Code: Panoramica concettuale di tutte le funzionalità di estensione, con tabelle di confronto e analisi dei costi di contesto
  • Skills nell’SDK: Guida completa all’utilizzo delle skills a livello programmatico
  • Subagenti: Definisci e invoca subagenti per sottocompiti isolati
  • Hooks: Intercetta e controlla il comportamento dell’agente nei punti di esecuzione chiave
  • Permessi: Controlla l’accesso agli strumenti con modalità, regole e callback
  • Prompt di sistema: Inietta il contesto senza file CLAUDE.md