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"]:
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). 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:
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. Le impostazioni gestite dal server vengono recuperate quando il processo si autentica con una credenziale dell’organizzazione; l’isolamento del filesystem non le rimuove. 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

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

Quando usare quale tipo di hook

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