Skip to main content
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
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:
Os parâmetros de solicitação da API de Mensagens temperature, top_p e max_tokens não têm campos no objeto de opções em nenhum idioma. Defina o nível de esforço ou um limite de gastos em vez disso, ou chame a API de Mensagens quando você precisar desses parâmetros diretamente.

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.
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.
Na API Claude, o programa imprime First turn model: claude-sonnet-5, depois Second turn model: claude-opus-5 após a mudança.
Cada modelo tem seu próprio cache de prompt, portanto após uma mudança no meio da sessão a próxima solicitação recomputa a conversa completa sem cache nas taxas do novo modelo. Para mais informações, consulte Alternando modelos.

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.

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