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. Per ulteriori informazioni, vedi Cosa settingSources non controlla.
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
import asyncio
async def main():
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}")
asyncio.run(main())
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}`);
}
}
Quando viene eseguito, la risposta dell'assistente viene stampata su stdout, seguita da una riga di risultato finale una volta completata l'esecuzione.
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" |
settings.json del progetto e hooks; CLAUDE.md del progetto e .claude/rules/*.md; skills, comandi e subagenti 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, comandi e subagenti, più le cartelle .claude/skills/, .claude/commands/ e .claude/agents/ di ogni directory che passi tramite l'opzione additionalDirectories o add_dirs, che l'SDK passa a Claude Code come --add-dir |
"user" |
settings.json dell'utente; CLAUDE.md dell'utente e ~/.claude/rules/*.md; skills, comandi e subagenti dell'utente |
~/.claude/ per settings.json, CLAUDE.md e rules; ~/.claude/skills/, ~/.claude/commands/ e ~/.claude/agents/ per skills, comandi e subagenti |
"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. 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 | Criterio gestito dall'endpoint, come un plist MDM, criterio del registro o file di impostazioni gestite, carica dall'host. Le impostazioni gestite dal server vengono recuperate su una configurazione idonea quando la sessione si autentica con una credenziale idonea, come un accesso OAuth dell'organizzazione, una chiave API configurata direttamente, o un profilo user_oauth Anthropic |
Criterio dell'endpoint: rimuovi il file delle impostazioni gestite, plist o criterio del registro dall'host. Impostazioni gestite dal server: un Proprietario nella tua organizzazione Claude le controlla; non puoi disabilitarle dall'SDK |
Configurazione globale ~/.claude.json |
Sempre letta | Riposiziona con CLAUDE_CONFIG_DIR in env |
Memoria automatica in ~/.claude/projects/<project>/memory/ |
Caricata nel prompt di sistema all'avvio della sessione. L'agente scrive nuovi ricordi lì con gli strumenti standard Write e Edit piuttosto che con uno strumento di memoria dedicato, quindi questi strumenti devono essere abilitati affinché l'agente possa salvare i ricordi |
Imposta autoMemoryEnabled: false nelle impostazioni, o CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env |
| Connettori MCP da claude.ai | Caricati quando la sessione si autentica con il tuo accesso a claude.ai. Non caricati quando CLAUDE_CODE_OAUTH_TOKEN contiene un token da claude setup-token, che può solo fare richieste di modello. Passare mcpServers: {} non sopprime i connettori |
Imposta strictMcpConfig: true, disableClaudeAiConnectors: true nelle impostazioni, o ENABLE_CLAUDEAI_MCP_SERVERS=false in env |
sandbox.credentials voci deny e voci mask di file in ~/.claude/settings.json |
Quando viene eseguita la sandbox dei comandi, Claude Code applica le voci deny e mantiene le voci mask di credentials.files come restrizioni anche quando settingSources esclude le impostazioni utente. Claude Code utilizza queste voci solo per limitare ciò a cui i comandi in sandbox possono accedere |
Rimuovi le voci da ~/.claude/settings.json |
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 settingSources, 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. 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
import asyncio
# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async def main():
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)
asyncio.run(main())
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);
}
}
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.
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. 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
import asyncio
# 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, reserved for future abort-signal support
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 def main():
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)
asyncio.run(main())
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 {
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "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, decisioni strutturate e integrazione in-process. Questi si attivano anche all'interno dei subagenti. L'input dell'hook, il primo argomento del callback, contiene i campi agent_id e agent_type che identificano quale agente ha attivato l'hook. |
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