Usa le funzionalità di Claude Code nell'SDK
Carica le istruzioni del progetto, le skills, gli hooks e altre funzionalità di Claude Code nei tuoi agenti SDK.
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}")
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me refactor the auth module",
options: {
// "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.
settingSources: ["user", "project"],
allowedTools: ["Read", "Edit", "Bash"]
}
})) {
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "text") console.log(block.text);
}
}
if (message.type === "result" && message.subtype === "success") {
console.log(`\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).
| Fonte | Cosa carica | Posizione |
|---|---|---|
"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:
| Input | Comportamento | Per disabilitare |
|---|---|---|
| Impostazioni dei criteri gestiti | Sempre caricate quando presenti sull'host | Rimuovi il file delle impostazioni gestite |
Configurazione globale ~/.claude.json |
Sempre letta | Riposiziona con CLAUDE_CONFIG_DIR in env |
Memoria automatica in ~/.claude/projects/<project>/memory/ |
Caricata per impostazione predefinita nel prompt di sistema | Imposta autoMemoryEnabled: false nelle impostazioni, o CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env |
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
| Livello | Posizione | Quando caricato |
|---|---|---|
| Progetto (root) | <cwd>/CLAUDE.md o <cwd>/.claude/CLAUDE.md |
settingSources include "project" |
| Regole del progetto | <cwd>/.claude/rules/*.md e .claude/rules/*.md in ogni directory padre |
settingSources include "project" |
| Progetto (directory padre) | File CLAUDE.md nelle directory sopra cwd |
settingSources include "project", caricato all'inizio della sessione |
| Progetto (directory figlie) | File CLAUDE.md nelle sottodirectory di cwd |
settingSources 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 padre |
settingSources include "local" |
| Utente | ~/.claude/CLAUDE.md |
settingSources include "user" |
| Regole dell'utente | ~/.claude/rules/*.md |
settingSources 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").
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. L'SDK abilita automaticamente lo strumento Skill quando skills è impostato, quindi non è necessario aggiungerlo a allowedTools.
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)
import { query } from "@anthropic-ai/claude-agent-sdk";
// Skills in .claude/skills/ are discovered automatically
// when settingSources includes "project"
for await (const message of query({
prompt: "Review this PR using our code review checklist",
options: {
settingSources: ["user", "project"],
skills: "all",
allowedTools: ["Read", "Grep", "Glob"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
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 quandosettingSourcesinclude 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 {} (un dict vuoto) significa consentire allo strumento di procedere. Restituire {"decision": "block", "reason": "..."} impedisce l'esecuzione e il motivo viene inviato a Claude come risultato dello strumento. 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 {"decision": "block", "reason": "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)
import { query, type HookInput, type HookJSONOutput } from "@anthropic-ai/claude-agent-sdk";
// PreToolUse hook callback. HookInput is a discriminated union on
// hook_event_name, so narrowing on it gives TypeScript the right
// tool_input shape for this event.
const auditBash = async (input: HookInput): Promise<HookJSONOutput> => {
if (input.hook_event_name !== "PreToolUse") return {};
const toolInput = input.tool_input as { command?: string };
if (toolInput.command?.includes("rm -rf")) {
return { decision: "block", reason: "Destructive command blocked" };
}
return {}; // Empty object: allow the tool to proceed
};
// Filesystem hooks from .claude/settings.json run automatically
// when settingSources loads them. You can also add programmatic hooks:
for await (const message of query({
prompt: "Refactor the auth module",
options: {
settingSources: ["project"], // Loads hooks from .claude/settings.json
hooks: {
PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }]
}
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
Quando usare quale tipo di hook
| Tipo di hook | Migliore 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; restituzione di decisioni strutturate; integrazione in-process. Limitato alla sessione principale solo. |
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... | Usa | Superficie SDK |
|---|---|---|
| Impostare le convenzioni del progetto che il tuo agente segue sempre | CLAUDE.md | settingSources: ["project"] lo carica automaticamente |
| Dare all'agente materiale di riferimento che carica quando rilevante | Skills | opzione settingSources + skills |
| Eseguire un flusso di lavoro riutilizzabile (deploy, review, release) | Skills invocabili dall'utente | opzione settingSources + skills |
| Delegare un sottocompito isolato a un contesto fresco (ricerca, review) | Subagenti | parametro agents + allowedTools: ["Agent"] |
| Coordinare più istanze di Claude Code con elenchi di attività condivisi e messaggistica diretta tra agenti | Team di agenti | Non 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) | Hooks | parametro hooks con callback, o script shell caricati tramite settingSources |
| Dare a Claude accesso strutturato agli strumenti di un servizio esterno | MCP | parametro mcpServers |
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