Use Claude Code features in the SDK
Load project instructions, skills, hooks, and other Claude Code features into your SDK agents.
O Agent SDK é construído na mesma base que Claude Code, o que significa que seus agentes SDK têm acesso aos mesmos recursos baseados em sistema de arquivos: instruções de projeto (CLAUDE.md e regras), skills, hooks e muito mais.
Quando você omite settingSources, query() lê as mesmas configurações do sistema de arquivos que a CLI Claude Code: configurações de usuário, projeto e local, arquivos CLAUDE.md e skills, agentes e comandos em .claude/. Para executar sem estes, passe settingSources: [], o que limita o agente ao que você configura programaticamente. As configurações de política gerenciada e a configuração global ~/.claude.json são lidas independentemente desta opção. Veja O que settingSources não controla.
Para uma visão geral conceitual do que cada recurso faz e quando usá-lo, veja Extend Claude Code.
Controlar configurações do sistema de arquivos com settingSources
A opção de fontes de configuração (setting_sources em Python, settingSources em TypeScript) controla quais configurações baseadas em sistema de arquivos o SDK carrega. Passe uma lista explícita para optar por fontes específicas, ou passe um array vazio para desabilitar configurações de usuário, projeto e local.
Este exemplo carrega configurações de nível de usuário e nível de projeto definindo settingSources para ["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}`);
}
}
Cada fonte carrega configurações de um local específico, onde <cwd> é o diretório de trabalho que você passa via opção cwd, ou o diretório atual do processo se não definido. Para a definição de tipo completa, veja SettingSource (TypeScript) ou SettingSource (Python).
| Fonte | O que carrega | Local |
|---|---|---|
"project" |
CLAUDE.md do projeto, .claude/rules/*.md, skills do projeto, hooks do projeto, settings.json do projeto |
<cwd>/.claude/ e cada diretório pai até a raiz do sistema de arquivos (parando quando um .claude/ é encontrado ou não há mais pais) |
"user" |
CLAUDE.md do usuário, ~/.claude/rules/*.md, skills do usuário, configurações do usuário |
~/.claude/ |
"local" |
CLAUDE.local.md (gitignored), .claude/settings.local.json |
<cwd>/ |
Omitir settingSources é equivalente a ["user", "project", "local"].
A opção cwd determina onde o SDK procura por configurações de projeto. Se nem cwd nem nenhum de seus diretórios pai contiver uma pasta .claude/, os recursos de nível de projeto não serão carregados.
O que settingSources não controla
settingSources cobre configurações de usuário, projeto e local. Algumas entradas são lidas independentemente de seu valor:
| Entrada | Comportamento | Para desabilitar |
|---|---|---|
| Configurações de política gerenciada | Sempre carregadas quando presentes no host | Remova o arquivo de configurações gerenciadas |
Configuração global ~/.claude.json |
Sempre lida | Relocalize com CLAUDE_CONFIG_DIR em env |
Memória automática em ~/.claude/projects/<project>/memory/ |
Carregada por padrão no prompt do sistema | Defina autoMemoryEnabled: false nas configurações, ou CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 em env |
Project instructions (CLAUDE.md and rules)
Arquivos CLAUDE.md e arquivos .claude/rules/*.md dão ao seu agente contexto persistente sobre seu projeto: convenções de codificação, comandos de compilação, decisões de arquitetura e instruções. Quando settingSources inclui "project" (como no exemplo acima), o SDK carrega esses arquivos em contexto no início da sessão. O agente então segue suas convenções de projeto sem você repeti-las em cada prompt.
CLAUDE.md load locations
| Nível | Local | Quando carregado |
|---|---|---|
| Projeto (raiz) | <cwd>/CLAUDE.md ou <cwd>/.claude/CLAUDE.md |
settingSources inclui "project" |
| Regras do projeto | <cwd>/.claude/rules/*.md |
settingSources inclui "project" |
| Projeto (diretórios pai) | Arquivos CLAUDE.md em diretórios acima de cwd |
settingSources inclui "project", carregado no início da sessão |
| Projeto (diretórios filho) | Arquivos CLAUDE.md em subdiretórios de cwd |
settingSources inclui "project", carregado sob demanda quando o agente lê um arquivo nessa subárvore |
| Local (gitignored) | <cwd>/CLAUDE.local.md |
settingSources inclui "local" |
| Usuário | ~/.claude/CLAUDE.md |
settingSources inclui "user" |
| Regras do usuário | ~/.claude/rules/*.md |
settingSources inclui "user" |
Todos os níveis são aditivos: se existem arquivos CLAUDE.md de projeto e usuário, o agente vê ambos. Não há regra de precedência rígida entre níveis; se as instruções conflitarem, o resultado depende de como Claude as interpreta. Escreva regras não conflitantes, ou declare precedência explicitamente no arquivo mais específico ("Estas instruções de projeto substituem quaisquer padrões conflitantes de nível de usuário").
Para como estruturar e organizar conteúdo CLAUDE.md, veja Manage Claude's memory.
Skills
Skills são arquivos markdown que dão ao seu agente conhecimento especializado e fluxos de trabalho invocáveis. Diferentemente de CLAUDE.md (que carrega a cada sessão), skills carregam sob demanda. O agente recebe descrições de skills na inicialização e carrega o conteúdo completo quando relevante.
Skills são descobertos do sistema de arquivos através de settingSources. Quando a opção skills em query() é omitida, skills de usuário e projeto descobertos são habilitados e a ferramenta Skill fica disponível, correspondendo ao comportamento da CLI. Para controlar quais skills são habilitados, passe skills como "all", uma lista de nomes de skills, ou [] para desabilitar todos. O SDK habilita a ferramenta Skill automaticamente quando skills é definido, portanto você não precisa adicioná-la 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);
}
}
Para mais sobre criar e usar skills, veja Agent Skills in the SDK.
Hooks
O SDK suporta duas maneiras de definir hooks, e eles executam lado a lado:
- Filesystem hooks: comandos shell definidos em
settings.json, carregados quandosettingSourcesinclui a fonte relevante. Estes são os mesmos hooks que você configuraria para sessões interativas de Claude Code. - Programmatic hooks: funções de callback passadas diretamente para
query(). Estes executam em seu processo de aplicação e podem retornar decisões estruturadas. Veja Control execution with hooks.
Ambos os tipos executam durante o mesmo ciclo de vida de hook. Se você já tem hooks no settings.json do seu projeto e você define settingSources: ["project"], esses hooks executam automaticamente no SDK sem configuração extra.
Callbacks de hook recebem a entrada da ferramenta e retornam um dict de decisão. Retornar {} (um dict vazio) significa permitir que a ferramenta prossiga. Retornar {"decision": "block", "reason": "..."} previne execução e a razão é enviada para Claude como o resultado da ferramenta. Veja o hooks guide para a assinatura de callback completa e tipos de retorno.
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);
}
}
When to use which hook type
| Tipo de hook | Melhor para |
|---|---|
Filesystem (settings.json) |
Compartilhar hooks entre sessões CLI e SDK. Suporta "command" (scripts shell), "http" (POST para um endpoint), "mcp_tool" (chamar a ferramenta de um servidor MCP conectado), "prompt" (LLM avalia um prompt), e "agent" (spawns um agente verificador). Estes disparam no agente principal e em qualquer subagente que ele spawna. |
Programmatic (callbacks em query()) |
Lógica específica da aplicação; retornando decisões estruturadas; integração em processo. Escopo apenas para a sessão principal. |
Para detalhes completos sobre hooks programáticos, veja Control execution with hooks. Para sintaxe de hook do sistema de arquivos, veja Hooks.
Escolha o recurso certo
O Agent SDK oferece acesso a várias maneiras de estender o comportamento do seu agente. Se você não tem certeza qual usar, esta tabela mapeia objetivos comuns para a abordagem correta.
| Você quer... | Use | Superfície SDK |
|---|---|---|
| Definir convenções de projeto que seu agente sempre segue | CLAUDE.md | settingSources: ["project"] carrega automaticamente |
| Dar ao agente material de referência que ele carrega quando relevante | Skills | opção settingSources + skills |
| Executar um fluxo de trabalho reutilizável (deploy, review, release) | User-invocable skills | opção settingSources + skills |
| Delegar uma subtarefa isolada para um contexto fresco (research, review) | Subagents | parâmetro agents + allowedTools: ["Agent"] |
| Coordenar múltiplas instâncias de Claude Code com listas de tarefas compartilhadas e mensagens diretas entre agentes | Agent teams | Não configurado diretamente via opções SDK. Agent teams são um recurso CLI onde uma sessão atua como o líder da equipe, coordenando trabalho entre colegas independentes |
| Executar lógica determinística em chamadas de ferramenta (audit, block, transform) | Hooks | parâmetro hooks com callbacks, ou scripts shell carregados via settingSources |
| Dar a Claude acesso estruturado a ferramenta para um serviço externo | MCP | parâmetro mcpServers |
Cada recurso que você habilita adiciona à janela de contexto do seu agente. Para custos por recurso e como esses recursos se sobrepõem, veja Extend Claude Code.
Related resources
- Extend Claude Code: Visão geral conceitual de todos os recursos de extensão, com tabelas de comparação e análise de custo de contexto
- Skills in the SDK: Guia completo para usar skills programaticamente
- Subagents: Defina e invoque subagents para subtarefas isoladas
- Hooks: Intercepte e controle comportamento do agente em pontos-chave de execução
- Permissions: Controle acesso a ferramentas com modos, regras e callbacks
- System prompts: Injete contexto sem arquivos CLAUDE.md