SpyBara
Go Premium

agent-sdk/claude-code-features.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 54 additions and 42 deletions.

2026
Wed 9 22:58 Mon 14 22:58 Fri 18 23:58

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.

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
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())

Quando isso é executado, a resposta do assistente é impressa em stdout, seguida por uma linha de resultado final quando a execução é concluída.

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" settings.json do projeto e hooks; CLAUDE.md do projeto e .claude/rules/*.md; skills, comandos e subagentes do projeto <cwd>/.claude/ para settings.json e hooks; <cwd> e cada diretório pai para CLAUDE.md e rules; <cwd> e cada diretório pai até a raiz do repositório para skills, comandos e subagentes, além das pastas .claude/skills/, .claude/commands/ e .claude/agents/ de cada diretório que você passa através da opção additionalDirectories ou add_dirs, que o SDK passa para Claude Code como --add-dir
"user" settings.json do usuário; CLAUDE.md do usuário e ~/.claude/rules/*.md; skills, comandos e subagentes do usuário ~/.claude/ para settings.json, CLAUDE.md e rules; ~/.claude/skills/, ~/.claude/commands/ e ~/.claude/agents/ para skills, comandos e subagentes
"local" CLAUDE.local.md, .claude/settings.local.json <cwd>/.claude/ para settings.local.json; <cwd> e cada diretório pai para CLAUDE.local.md

Omitir settingSources é equivalente a ["user", "project", "local"].

A opção cwd determina onde o SDK procura por entradas de nível de projeto. settings.json do projeto e hooks carregam apenas de <cwd>/.claude/ sem fallback de diretório pai.

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 Política gerenciada pelo endpoint, como um plist MDM, política de registro ou arquivo de configurações gerenciadas, carrega do host. Configurações gerenciadas pelo servidor são buscadas em uma configuração elegível quando a sessão se autentica com uma credencial qualificada, como um login OAuth de organização, uma chave de API configurada diretamente ou um perfil user_oauth do Anthropic Política de endpoint: remova o arquivo de configurações gerenciadas, plist ou política de registro do host. Configurações gerenciadas pelo servidor: um Proprietário em sua organização Claude controla; você não pode desabilitá-las do SDK
Configuração global ~/.claude.json Sempre lida Relocalize com CLAUDE_CONFIG_DIR em env
Memória automática em ~/.claude/projects/<project>/memory/ Carregada no prompt do sistema no início da sessão. O agente escreve novas memórias lá com as ferramentas padrão Write e Edit em vez de uma ferramenta de memória dedicada, portanto essas ferramentas devem estar habilitadas para o agente salvar memórias Defina autoMemoryEnabled: false nas configurações, ou CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 em env
Conectores MCP do claude.ai Carregados quando a sessão se autentica com seu login claude.ai. Não carregados quando CLAUDE_CODE_OAUTH_TOKEN contém um token de claude setup-token, que pode apenas fazer solicitações de modelo. Passar mcpServers: {} não suprime os conectores Defina strictMcpConfig: true, disableClaudeAiConnectors: true nas configurações, ou ENABLE_CLAUDEAI_MCP_SERVERS=false em env
Entradas deny de sandbox.credentials e entradas mask de arquivo em ~/.claude/settings.json Quando o sandbox de comando é executado, Claude Code aplica as entradas deny e mantém as entradas mask de credentials.files como restrições mesmo quando settingSources exclui configurações de usuário. Claude Code usa essas entradas apenas para restringir o que comandos em sandbox podem acessar Remova as entradas de ~/.claude/settings.json

Instruções do projeto (CLAUDE.md e regras)

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 e .claude/rules/*.md em cada diretório pai 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 <cwd>/CLAUDE.local.md e CLAUDE.local.md em cada diretório pai 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. Quando skills é definido, o SDK adiciona a ferramenta Skill a allowedTools automaticamente. Se você também passar uma lista explícita de tools, inclua "Skill" nessa lista para que Claude possa invocar 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())

Hooks

O SDK suporta duas maneiras de definir hooks, e eles executam lado a lado:

  • Filesystem hooks: comandos shell definidos em settings.json, carregados quando settingSources inclui 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 {} significa permitir que a ferramenta prossiga. Para bloquear a execução, retorne um objeto hookSpecificOutput com permissionDecision: "deny" e um permissionDecisionReason. 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
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())

Quando usar qual tipo de hook

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, decisões estruturadas e integração em processo. Estes também disparam dentro de subagentes. A entrada do hook, o primeiro argumento do callback, carrega campos agent_id e agent_type que identificam qual agente disparou o hook.

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.

  • 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