SpyBara
Go Premium

agent-sdk/configuration.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 315 additions and 0 deletions.

2026
Fri 18 23:58 Tue 22 23:59

Configure seu agente

Configure sessões do Agent SDK: componha o objeto de opções, defina o modelo, ambiente e limites, e encontre a página de cada opção de recurso.

Uma sessão do Agent SDK lê a configuração de arquivos de configuração, variáveis de ambiente e do objeto options que você passa ao iniciá-la. Esta página mostra como compor o objeto options e quais arquivos de configuração e variáveis de ambiente o controlam.

Para cada tipo de opção e padrão, consulte as referências Options (TypeScript) e ClaudeAgentOptions (Python).

Passar opções para uma sessão

Cada chamada query() aceita um objeto de opções: Options em TypeScript, ClaudeAgentOptions em Python. Cada campo é opcional, e uma sessão iniciada sem opções é executada com os padrões do SDK. O exemplo abaixo configura uma sessão somente leitura que resume os TODOs abertos de um projeto. Os pares são lidos como TypeScript / Python onde as grafias diferem:

  • model: escolhe o modelo
  • allowedTools / allowed_tools: pré-aprova uma lista de ferramentas somente leitura
  • maxTurns / max_turns: limita a contagem de turnos
  • cwd: define o diretório de trabalho
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Summarize the open TODOs in this repo",
options: {
model: "claude-sonnet-5",
allowedTools: ["Read", "Glob", "Grep"],
maxTurns: 8,
cwd: "/path/to/repo",
},
})) {
if (message.type === "result" && message.subtype === "success" && !message.is_error) {
console.log(message.result);
}
}

Aponte cwd para um de seus próprios projetos e execute o exemplo. O resumo dos TODOs abertos desse projeto é impresso quando a mensagem de resultado chega.

allowedTools (TypeScript) ou allowed_tools (Python) pré-aprova as ferramentas listadas, portanto as chamadas para elas são executadas sem parar para aprovação. As ferramentas fora da lista permanecem disponíveis. Quando Claude chama uma ferramenta não listada, o modo de permissão decide se a chamada é executada. Para mais informações, consulte Regras de permissão e negação.

Carregar arquivos de configuração

Os arquivos de configuração fornecem configuração além do objeto de opções. Duas opções controlam como eles são carregados:

  • settingSources / setting_sources: controla quais fontes do sistema de arquivos são carregadas: usuário, projeto e local. Os arquivos de configuração e arquivos CLAUDE.md chegam através dessas fontes.
  • settings: carrega um caminho de arquivo de configuração ou uma string JSON embutida em qualquer idioma, e TypeScript também aceita um objeto de configuração. Qualquer forma que você passar substitui as configurações do sistema de arquivos do usuário, projeto e local; apenas as configurações de política gerenciada têm classificação mais alta. As referências documentam a ordem de precedência completa em Precedência de configurações para TypeScript e Precedência de configurações para Python.

Passe [] para desabilitar as configurações do usuário, projeto e local. Para mais informações, consulte Usar recursos do Claude Code no SDK.

Escolher um modelo

A menos que a opção model, suas configurações ou seu ambiente selecionem um modelo, uma nova sessão é iniciada no modelo padrão do Claude Code. Para a ordem dessas fontes, consulte Definir seu modelo. Defina model para fixar um modelo específico ou para escolher um menor para agentes mais rápidos e baratos. O valor aceita um alias de modelo ou um nome de modelo completo; os aliases e as versões que eles resolvem estão listados em Aliases de modelo.

Defina fallbackModel (TypeScript) ou fallback_model (Python) para nomear um modelo de backup. Quando o primário está sobrecarregado ou indisponível, a sessão muda para o backup. O primário é retentado no início de cada turno do usuário, portanto a sessão retorna a ele assim que a interrupção passa.

Em qualquer idioma, a opção aceita um único modelo ou uma lista separada por vírgulas de backups. Para a ordem e o limite da cadeia, consulte Cadeias de modelo de fallback. Em TypeScript, um fallback igual a model lança um erro na inicialização.

Os exemplos abaixo mostram uma lista de fallback em TypeScript e um único fallback em Python:

const options = {
model: "claude-fable-5",
fallbackModel: "claude-opus-5,claude-sonnet-5",
};

Definir variáveis de ambiente

A opção env define variáveis de ambiente para o processo Claude Code que executa sua sessão. Se seus valores substituem o ambiente herdado ou se mesclam com ele difere por idioma:

  • TypeScript: env substitui o ambiente do subprocesso
  • Python: o SDK mescla seus valores sobre o ambiente herdado, e seus valores substituem os herdados

Em TypeScript, espalhe process.env em env para manter variáveis herdadas como PATH, HOME e ANTHROPIC_API_KEY. Quando você deixa env indefinido, o subprocesso herda seu ambiente em ambos os idiomas.

O exemplo roteia o tráfego de API através de um gateway definindo ANTHROPIC_BASE_URL.

const options = {
env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

As variáveis que você passa também podem configurar o próprio Claude Code. Para as variáveis que o processo Claude Code lê, consulte Variáveis de ambiente. Para ajustar os tempos limite de API e detecção de travamento dessa forma, siga a seção Lidar com respostas de API lentas ou travadas na referência TypeScript ou na referência Python.

Definir o diretório de trabalho

Defina cwd para executar a sessão em um diretório específico. Quando você deixa cwd indefinido, a sessão é executada no diretório de trabalho do seu processo. Nenhum SDK tem um setter para cwd. Para executar em um diretório diferente, inicie outra sessão com esse cwd.

Claude Code lê o diretório de trabalho para determinar:

Para permitir que as ferramentas acessem arquivos fora do diretório de trabalho, adicione caminhos com additionalDirectories (TypeScript) ou add_dirs (Python). Para o escopo dessa concessão, consulte Diretórios adicionais concedem acesso a arquivos, não configuração.

Limitar turnos e gastos

Limite turnos e gastos com maxTurns / max_turns e maxBudgetUsd / max_budget_usd. Ambos os limites estão desativados quando indefinidos. Quando uma sessão atinge um limite, a execução termina com uma mensagem de resultado cujo subtipo nomeia o limite, error_max_turns ou error_max_budget_usd. O que acontece a seguir difere por modo de entrada:

  • query() de disparo único: o SDK produz o resultado do limite e depois lança, portanto envolva o loop em um bloco try para continuar além do erro
  • Entrada de streaming: a sessão permanece viva além de um resultado de limite, e a contagem de turnos máximos recomeça para cada mensagem enfileirada. O total do orçamento se acumula entre mensagens, e uma vez que o gasto atinge o limite, mensagens posteriores na mesma conversa terminam com o mesmo resultado de orçamento. Um /clear reinicia o orçamento

Os dois limites tratam 0 de forma diferente:

  • maxTurns / max_turns: 0 executa a sessão sem um limite de turnos, o mesmo que deixar a opção indefinida
  • maxBudgetUsd / max_budget_usd: a CLI rejeita 0 como um valor inválido na inicialização, e a sessão nunca é executada

Para mais informações sobre ambos os limites, incluindo gastos de subagentes, consulte Turnos e orçamento.

Alterar configuração no meio da sessão

Quando você inicia uma sessão com entrada de streaming, você pode alternar seu modelo e modo de permissão enquanto ela é executada. Onde você chama os setters difere por idioma:

  • TypeScript: métodos no objeto que query() retorna
  • Python: métodos em ClaudeSDKClient, já que query() retorna um iterador simples sem métodos de controle

Ambos os idiomas têm os mesmos setters:

  • setModel() / set_model(): alterna o modelo. Chame-o sem modelo para alternar para o modelo padrão do Claude Code em vez do model que você passou nas opções.
  • setPermissionMode() / set_permission_mode(): alterna o modo de permissão

TypeScript também tem applyFlagSettings() e updateSettings():

  • applyFlagSettings(): aplica configurações em tempo de execução, como em await session.applyFlagSettings({ effortLevel: "high" }). O método aceita chaves de arquivo de configuração em vez de campos de opções, portanto verifique a referência applyFlagSettings() para o esquema e para quais chaves têm efeito no meio da sessão.
  • updateSettings(): escreve um conjunto de chaves na lista de permissões para o arquivo de configuração local do projeto, como em await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). As chaves escritas têm efeito na próxima solicitação da sessão e persistem para sessões posteriores que carregam configurações local. A linha do método na tabela de métodos nomeia as chaves na lista de permissões e o piso de versão.

O exemplo abaixo executa uma sessão de dois turnos, altera a configuração entre os turnos e imprime o modelo que respondeu cada turno. Em TypeScript, o fluxo de prompt mantém a segunda mensagem até que os setters tenham sido executados, e o segundo turno é executado no novo modelo.

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

function userMessage(text: string): SDKUserMessage {
return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
yield userMessage("Reply with exactly: ready");
await secondTurnReady;
yield userMessage("Reply with exactly: done");
}

const session = query({
prompt: turnPrompts(),
options: {
model: "claude-sonnet-5",
},
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
if (message.type === "assistant") {
turnModel = message.message.model;
} else if (message.type === "result") {
completedTurns += 1;
if (completedTurns === 1) {
console.log(`First turn model: ${turnModel}`);
await session.setModel("claude-opus-5");
await session.setPermissionMode("acceptEdits");
startSecondTurn();
} else {
console.log(`Second turn model: ${turnModel}`);
break;
}
}
}

Na API Claude, o programa imprime First turn model: claude-sonnet-5, depois Second turn model: claude-opus-5 após a mudança.

Configurar recursos específicos

A tabela abaixo mapeia cada opção para o recurso que ela configura. Para opções que esta página não cobre, consulte as referências TypeScript e Python. Se você conhece seu objetivo mas não qual opção o serve, comece em Escolher o recurso certo.

TypeScript Python Controla Coberto em
permissionMode permission_mode O que o agente pode fazer sem aprovação Configurar permissões
allowedTools allowed_tools Quais chamadas de ferramentas são pré-aprovadas Configurar permissões
canUseTool can_use_tool Seu callback de aprovação para chamadas de ferramentas Lidar com solicitações de aprovação de ferramentas
systemPrompt system_prompt As instruções do agente Modificando prompts do sistema
settingSources setting_sources Quais configurações do sistema de arquivos são carregadas Usar recursos do Claude Code no SDK
mcpServers mcp_servers Servidores de ferramentas externas Conectar a ferramentas externas com MCP
agents agents Definições de subagentes Subagentes
hooks hooks Callbacks em pontos do ciclo de vida Hooks
skills skills Quais skills são carregadas Estender agentes com skills
plugins plugins Quais plugins são carregados Plugins
outputFormat output_format Esquemas de saída estruturada Saídas estruturadas
resume resume Continuando uma sessão armazenada Sessões
forkSession fork_session Ramificando uma sessão Sessões
sessionStore session_store Persistência de sessão externa Armazenamento de sessão
enableFileCheckpointing enable_file_checkpointing Edições de arquivo rebobináveis Checkpointing de arquivo
effort effort Quanto trabalho Claude coloca nas respostas Nível de esforço
sandbox sandbox Comportamento de sandbox para execução de ferramentas TypeScript e referências Python, com contexto de implantação em Implantação segura

Próximas etapas

Para ver a configuração composta em agentes funcionais:

  • Quickstart: construa e execute um primeiro agente de ponta a ponta
  • Exemplos: encontre um projeto completo e executável ou uma receita guiada do Claude Cookbook que corresponda ao que você deseja construir
  • Isolamento multi-tenant: isole as configurações e memória de cada tenant com settingSources / setting_sources, env e cwd