//
Busque em todas as páginas da documentação
Uma referência detalhada para as opções que você passa para uma execução do Claude Agent SDK, em Python e TypeScript.
Use esta página para procurar o nome, tipo e padrão de uma opção específica, em vez de reler as páginas conceituais a cada vez.
AgentOptions(...); exemplos em TypeScript usam o objeto de opções equivalente passado para query().snake_case em Python, camelCase em TypeScript).| Opção (Python) | Opção (TypeScript) | Tipo | Descrição |
|---|---|---|---|
model | model | str | Qual modelo Claude executa a etapa de decisão do loop, por exemplo, "claude-sonnet-5" |
cwd | cwd | str | Diretório raiz de trabalho para file_edit e bash |
system_prompt | systemPrompt | str | Instruções adicionais de nível de sistema sobrepostas aos padrões do SDK |
max_turns | maxTurns | int | Limite rígido nas iterações do loop de uso de ferramentas antes que ele pare |
| Opção (Python) | Opção (TypeScript) | Tipo | Descrição |
|---|---|---|---|
allowed_tools | allowedTools | list[str] | Lista de permissão de nomes de ferramentas internas que o loop pode chamar |
tool_config | toolConfig | dict | Escopo por ferramenta (comandos permitidos, caminhos, domínios) |
mcp_servers | mcpServers | list | Servidores MCP stdio ou HTTP registrados nos quais o loop pode chamar ferramentas |
subagents | subagents | list | Configurações de agente filho nomeadas, cada uma com seu próprio escopo de ferramentas |
| Opção (Python) | Opção (TypeScript) | Tipo | Descrição |
|---|---|---|---|
permission_mode | permissionMode | str | Se as chamadas de ferramenta permitidas ainda precisam de aprovação humana, por exemplo, "default", "bypass" |
checkpoint_hook | checkpointHook | callable | Função invocada antes de uma chamada de ferramenta sinalizada, para aprová-la/rejeitá-la/modificá-la |
checkpoint_tools | checkpointTools | list[str] | Quais nomes de ferramentas acionam uma pausa de checkpoint |
| Opção (Python) | Opção (TypeScript) | Tipo | Descrição |
|---|---|---|---|
resume | resume | str | Um ID de sessão anterior para retomar a conversa e o histórico de resultados de ferramentas |
session_store | sessionStore | object | Onde o estado da sessão é persistido (em memória, arquivo ou um backend personalizado) |
| Modo | Comportamento | Uso Típico |
|---|---|---|
default | Pausa antes de chamadas de ferramentas destrutivas/sinalizadas para aprovação | A maioria dos agentes de produção |
bypass | Nenhum portão de aprovação; toda chamada de ferramenta permitida executa imediatamente | Automações estritamente definidas e de baixo risco |
Personalizado (via checkpoint_hook) | Sua própria lógica decide aprovar/rejeitar/modificar por chamada | Regras de aprovação granulares ou condicionais |
| Formato do Escopo | Quando Usar |
|---|---|
Família única de ferramentas (por exemplo, ["file_edit"]) | A tarefa é estritamente um tipo de ação |
Múltiplas famílias, sem restrição de tool_config | Ambiente confiável, tarefa bem compreendida |
Múltiplas famílias com restrições de tool_config | Agentes de produção que acessam dados ou sistemas reais |
| Lista vazia | Geração de texto pura, sem necessidade de agir sobre nada |
Os campos mapeiam um para um, mas a convenção de nomenclatura difere: Python usa snake_case (allowed_tools), TypeScript usa camelCase (allowedTools).
allowed_tools decide o que o loop pode acessar. permission_mode decide se uma chamada permitida e alcançável ainda precisa de um humano para aprová-la antes de ser executada.
Não. max_turns limita as iterações do loop interno de uma única chamada query(). Sessões abrangem várias chamadas query() separadas ao longo do tempo.
Não, cada configuração de subagente carrega seu próprio allowed_tools e tool_config, independentemente do pai.
O comportamento volta para o modo padrão do SDK, que geralmente ainda controla ações destrutivas; verifique as notas de lançamento atuais do SDK para o padrão exato, pois os padrões seguros podem ser refinados entre os lançamentos.
Sim, mcp_servers aceita uma lista, e pode misturar registros de servidor stdio (local) e HTTP (remoto) na mesma execução.
O histórico da conversa e o histórico de resultados de ferramentas capturados sob esse ID de sessão, para que o loop continue com esse contexto já presente em vez de começar em branco.
Não estritamente, mas omiti-lo faz com que file_edit e bash voltem para o diretório de trabalho ambiente do processo, o que é frágil entre ambientes. Defina-o explicitamente para qualquer coisa além de um teste local rápido.
from claude_agent_sdk import AgentOptions
options = AgentOptions() # todos os padrões: modelo padrão, conjunto de ferramentas padrão, sem retomada de sessãoInclua web_search e/ou web_fetch em allowed_tools; eles são entradas separadas, pois a pesquisa e a busca de URL única têm perfis de risco diferentes.
checkpoint_tools nomeia quais chamadas de ferramenta acionam uma pausa; checkpoint_hook é a função que é executada durante essa pausa para decidir o resultado. Usar um sem o outro geralmente volta para um comportamento de confirmação padrão em vez de lógica personalizada.
Versões da Pilha: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o Claude Agent SDK (último lançamento, Python e TypeScript). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.