Habilitando Ferramentas de Edição de Arquivos, Bash e Web no Agent SDK
O Claude Agent SDK vem com quatro famílias de ferramentas integradas prontas para uso: edição de arquivos, execução de bash, pesquisa na web e busca na web.
//
Busque em todas as páginas da documentação
O Claude Agent SDK vem com quatro famílias de ferramentas integradas prontas para uso: edição de arquivos, execução de bash, pesquisa na web e busca na web.
Nenhuma delas está ativada por padrão de forma irrestrita; você escolhe quais ferramentas um agente pode acessar, e muitas vezes até onde cada uma pode alcançar, antes mesmo de chamar query().
As ferramentas integradas são o que permitem que o loop de uso de ferramentas realmente altere arquivos, execute comandos ou obtenha informações da web, em vez de apenas produzir texto.
Cada família de ferramentas tem sua própria superfície de configuração, não apenas um interruptor de ligar/desligar, então "habilitar bash" e "habilitar bash irrestrito" são duas decisões diferentes.
Acertar isso é importante porque cada ferramenta que você habilita é algo que o loop pode invocar por conta própria, sujeito apenas a qualquer modo de permissão e pontos de verificação que você tenha adicionado.
Esta página cobre como habilitar e escopar cada família de ferramentas integrada, e como elas interagem com os modos de permissão do SDK.
Cartão de receita de referência rápida - pronto para copiar e colar.
from claude_agent_sdk import query, AgentOptions
options = AgentOptions(
allowed_tools=["file_edit", "bash", "web_search", "web_fetch"],
cwd="/path/to/project",
permission_mode="default",
)
async for message in query(
prompt="Atualize o changelog e verifique se os testes ainda passam.",
options=options,
):
print(message)Quando usar isso:
permission_mode como uma rede de segurança.cwd.import asyncio
from claude_agent_sdk import query, AgentOptions
async def run_release_notes_agent(repo_path: str) -> None:
options = AgentOptions(
cwd=repo_path,
allowed_tools=["bash", "file_edit", "web_fetch"],
# bash é escopado para comandos de inspeção somente leitura que o agente precisa
# para coletar contexto; ele não recebe web_search, pois a tarefa
# só precisa buscar um URL conhecido, não pesquisar na web aberta.
tool_config={
"bash": {"allowed_commands": ["git log", "git diff", "git status"]},
},
permission_mode="default",
)
prompt = (
"Leia o log do git desde a última tag, busque o issue vinculado "
"para cada commit de https://api.example.com/issues/{id}, e "
"escreva um RELEASE_NOTES.md resumindo as alterações."
)
async for message in query(prompt=prompt, options=options):
if message.get("type") == "text":
print(message["text"], end="", flush=True)
elif message.get("type") == "tool_call":
print(f"\n[chamada de ferramenta: {message['tool_name']}]")
asyncio.run(run_release_notes_agent("/home/dev/my-project"))O que isso demonstra:
bash, file_edit, web_fetch) para uma tarefa que genuinamente precisa ler histórico, buscar dados externos e escrever um arquivo.allowed_commands em vez de conceder acesso irrestrito ao shell.web_search porque a tarefa só precisa buscar URLs conhecidas, não pesquisar na web.allowed_tools é avaliado antes da etapa de decisão do loop; um nome de ferramenta que não está na lista é invisível para o modelo, não apenas bloqueado no tempo de execução.file_edit cobre a leitura e escrita de arquivos sob cwd; algumas versões do SDK permitem restringi-lo ainda mais a caminhos ou globs específicos via tool_config.bash executa comandos de shell no diretório de trabalho; escopá-lo para uma lista allowed_commands (ou uma lista de negação, dependendo da versão do SDK) o limita a prefixos de comando específicos em vez de um shell aberto.web_search consulta um índice de pesquisa e retorna resultados sobre os quais o modelo pode raciocinar; web_fetch recupera o conteúdo de um URL específico. São ferramentas separadas porque "pesquisar na web" e "buscar esta página" têm perfis de risco e custo diferentes.permission_mode opera independentemente de allowed_tools: o escopo decide o que é acessível, o modo de permissão decide se uma chamada permitida e acessível ainda precisa de aprovação humana.| Ferramenta | O que faz | Botão de escopo comum |
|---|---|---|
file_edit | Ler/escrever arquivos sob cwd | Restrições de caminho ou glob |
bash | Executar comandos de shell | Prefixo de comando permitido/negado |
web_search | Consultar um índice de pesquisa | Contagem de resultados, restrições de domínio |
web_fetch | Recuperar o conteúdo de um URL | Lista de permissão de domínio |
# Escopar file_edit para um subdiretório impede que um agente monorepo grande
# toque em arquivos fora do pacote em que foi solicitado a trabalhar.
options = AgentOptions(
cwd="/repo",
allowed_tools=["file_edit"],
tool_config={
"file_edit": {"allowed_paths": ["packages/billing/**"]},
},
)| Parâmetro | Tipo | Descrição |
|---|---|---|
allowed_tools | list[str] | Lista de permissão de nomes de ferramentas integradas que o loop pode chamar |
cwd | str | Diretório raiz de trabalho para file_edit e bash |
tool_config | dict | Opções de escopo por ferramenta (comandos permitidos, caminhos, domínios) |
permission_mode | str | Se as chamadas permitidas ainda precisam de aprovação humana (default, bypass, etc.) |
tool_config não definido significa "irrestrito". Uma entrada bash irrestrita em allowed_tools pode significar acesso total ao shell em algumas configurações. Correção: sempre combine bash com allowed_commands explícito ou restrição equivalente, a menos que você realmente precise de acesso arbitrário ao shell.web_search com web_fetch. Habilitar web_search quando a tarefa só precisa ler um URL conhecido dá ao agente uma capacidade muito maior e menos previsível do que ele precisa. Correção: habilite web_fetch sozinho para tarefas com URLs conhecidos; reserve web_search para pesquisa aberta.cwd em ambientes multi-projeto. Sem um cwd explícito, file_edit e bash usam por padrão o diretório de trabalho do processo, o que pode diferir entre execuções locais e ambientes implantados. Correção: sempre defina cwd explicitamente em vez de confiar no diretório ambiente.permission_mode como substituto para escopo. Uma lista ampla de allowed_tools com portões de aprovação apenas para chamadas "obviamente destrutivas" ainda deixa muitas ações sem revisão. Correção: escopo as ferramentas primeiro; use o modo de permissão como uma segunda camada, não a única camada.file_edit a um agente de relatórios somente leitura. Se uma tarefa nunca precisar escrever arquivos, incluir file_edit de qualquer maneira é uma área de superfície desnecessária. Correção: conceda apenas as ferramentas que as saídas reais da tarefa exigem.bash escopados com antecedência. Uma lista allowed_commands muito restrita silencia o agente no meio da tarefa com um erro de permissão que o modelo precisa contornar. Correção: faça um teste dos comandos exatos que você espera que o agente precise antes de bloquear a lista de permissões.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Conceder todas as ferramentas integradas, confiar em pontos de verificação | Prototipagem local com um humano observando cada etapa | Execução sem supervisão ou contra dados de produção |
| Servidor MCP como a única ferramenta externa | A tarefa precisa de um sistema externo específico, não de acesso geral a arquivos/bash/web | A tarefa realmente precisa editar arquivos locais ou executar comandos de shell |
| Sem ferramentas, geração simples | A tarefa é pura geração de texto sem necessidade de agir sobre nada | A tarefa requer leitura, escrita ou busca de dados reais |
Não. Habilite apenas o que a tarefa precisa; allowed_tools aceita qualquer subconjunto, e uma lista vazia ou mínima é válida para tarefas puramente de texto.
A ferramenta não é exposta ao modelo em primeiro lugar, então ele não pode solicitá-la; o loop se comporta como se essa ferramenta não existisse.
permission_mode e pontos de verificação estão sobre ele.Sim, tipicamente através de tool_config com restrições de caminho ou glob, para que o agente só possa ler ou escrever dentro de um subconjunto definido do projeto.
web_search consulta um índice de pesquisa e retorna resultados classificados para o modelo raciocinar. web_fetch recupera o conteúdo de um URL específico e conhecido. Habilite o que realmente corresponde à tarefa.
Nenhum custo de tempo de execução significativo; o escopo é avaliado antes mesmo que o loop ofereça a ferramenta ao modelo, portanto, não adiciona latência por chamada.
Para qualquer coisa que toque em sistemas de produção, dados reais de usuários ou ações irreversíveis, sim. O escopo limita o que é possível; o modo de permissão adiciona uma verificação antes que o possível realmente aconteça.
Sim, cada subagente tem seu próprio allowed_tools e tool_config, independentes do escopo do pai.
Comece com os comandos reais que a tarefa exige (inspecionar, testar, construir), teste-os manualmente primeiro e adicione à lista apenas conforme as necessidades reais surgirem, em vez de adivinhar amplamente antecipadamente.
Não é estritamente obrigatório, mas omiti-lo faz com que file_edit e bash usem por padrão o diretório de trabalho ambiente do processo, o que é frágil entre ambientes. Defina-o explicitamente.
O escopo das ferramentas é definido por chamada query() via AgentOptions; para alterá-lo no meio da tarefa, você normalmente encerraria a chamada atual e iniciaria uma nova com opções atualizadas, opcionalmente retomando a sessão.
query() com ferramentas padrãoVersões da Stack: 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.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026