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.

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

Resumo

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.

Receita

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:

Você sabe exatamente quais famílias de ferramentas uma tarefa precisa e deseja conceder apenas essas.
Você está construindo um agente que será executado sem supervisão e precisa do permission_mode como uma rede de segurança.
Você deseja que as operações de arquivo e bash sejam escopadas para um diretório de projeto específico via cwd.
Você está auditando o acesso a ferramentas de um agente existente antes de implantá-lo.

Exemplo de Trabalho

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:

Combinação de três famílias de ferramentas (bash, file_edit, web_fetch) para uma tarefa que genuinamente precisa ler histórico, buscar dados externos e escrever um arquivo.
Restringindo bash ainda mais com allowed_commands em vez de conceder acesso irrestrito ao shell.
Omitindo deliberadamente web_search porque a tarefa só precisa buscar URLs conhecidas, não pesquisar na web.
Imprimindo eventos de chamada de ferramenta separadamente do texto para que você possa ver as ações do loop conforme elas acontecem.

Mergulho Profundo

Como Funciona

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.

Famílias de Ferramentas em Destaque

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

Notas Python

# 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âmetros e Valores de Retorno

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

Armadilhas

Assumir que um 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.
Confundir 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.
Esquecer 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.
Tratar 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.
Conceder 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.
Não testar comandos 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.

Alternativas

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

FAQs

Eu tenho que habilitar as quatro famílias de ferramentas integradas juntas?

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.

O que acontece se o modelo tentar chamar uma ferramenta que não está em allowed_tools?

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.

O acesso bash é sempre perigoso?

Bash irrestrito é de alto risco, pois pode executar qualquer comando de shell.
Bash escopado, limitado a prefixos de comando específicos, é de risco muito menor.
O risco também depende de qual permission_mode e pontos de verificação estão sobre ele.

Posso restringir file_edit a arquivos ou pastas específicas?

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.

Qual é a diferença entre web_search e web_fetch?

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.

O escopo das ferramentas deixa o agente mais lento?

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.

Devo sempre usar permission_mode junto com o escopo?

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.

O escopo das ferramentas pode diferir entre um agente pai e seus subagentes?

Sim, cada subagente tem seu próprio allowed_tools e tool_config, independentes do escopo do pai.

Como sei quais comandos colocar em uma lista allowed_commands?

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.

cwd é obrigatório?

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.

Posso alterar o escopo das ferramentas no meio da sessão?

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.

Relacionado

O Modelo Mental do Claude Agent SDK - como o escopo das ferramentas se encaixa no loop mais amplo
Noções Básicas do Claude Agent SDK - uma primeira chamada query() com ferramentas padrão
Adicionando Checkpoints Human-in-the-Loop a um Fluxo de Trabalho do Agent SDK - a camada de aprovação acima do escopo
Referência de Opções de Configuração do Claude Agent SDK - comparação completa de opções entre Python e TypeScript
Conectando o Claude Agent SDK a Servidores MCP - estendendo o alcance além das ferramentas integradas

Versõ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.

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.

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

Resumo

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.

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.

Receita

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:

Você sabe exatamente quais famílias de ferramentas uma tarefa precisa e deseja conceder apenas essas.
Você está construindo um agente que será executado sem supervisão e precisa do permission_mode como uma rede de segurança.
Você deseja que as operações de arquivo e bash sejam escopadas para um diretório de projeto específico via cwd.
Você está auditando o acesso a ferramentas de um agente existente antes de implantá-lo.

Exemplo de Trabalho

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:

Combinação de três famílias de ferramentas (bash, file_edit, web_fetch) para uma tarefa que genuinamente precisa ler histórico, buscar dados externos e escrever um arquivo.
Restringindo bash ainda mais com allowed_commands em vez de conceder acesso irrestrito ao shell.
Omitindo deliberadamente web_search porque a tarefa só precisa buscar URLs conhecidas, não pesquisar na web.
Imprimindo eventos de chamada de ferramenta separadamente do texto para que você possa ver as ações do loop conforme elas acontecem.

Mergulho Profundo

Como Funciona

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.

Famílias de Ferramentas em Destaque

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

Notas Python

# 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âmetros e Valores de Retorno

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

Armadilhas

Assumir que um 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.
Confundir 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.
Esquecer 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.
Tratar 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.
Conceder 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.
Não testar comandos 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.

Alternativas

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

FAQs

Eu tenho que habilitar as quatro famílias de ferramentas integradas juntas?

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.

O que acontece se o modelo tentar chamar uma ferramenta que não está em allowed_tools?

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.

O acesso bash é sempre perigoso?

Bash irrestrito é de alto risco, pois pode executar qualquer comando de shell.
Bash escopado, limitado a prefixos de comando específicos, é de risco muito menor.
O risco também depende de qual permission_mode e pontos de verificação estão sobre ele.

Posso restringir file_edit a arquivos ou pastas específicas?

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.

Qual é a diferença entre web_search e web_fetch?

O escopo das ferramentas deixa o agente mais lento?

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.

Devo sempre usar permission_mode junto com o escopo?

O escopo das ferramentas pode diferir entre um agente pai e seus subagentes?

Sim, cada subagente tem seu próprio allowed_tools e tool_config, independentes do escopo do pai.

Como sei quais comandos colocar em uma lista allowed_commands?

cwd é obrigatório?

Posso alterar o escopo das ferramentas no meio da sessão?

Relacionado

O Modelo Mental do Claude Agent SDK - como o escopo das ferramentas se encaixa no loop mais amplo
Noções Básicas do Claude Agent SDK - uma primeira chamada query() com ferramentas padrão
Adicionando Checkpoints Human-in-the-Loop a um Fluxo de Trabalho do Agent SDK - a camada de aprovação acima do escopo
Referência de Opções de Configuração do Claude Agent SDK - comparação completa de opções entre Python e TypeScript
Conectando o Claude Agent SDK a Servidores MCP - estendendo o alcance além das ferramentas integradas

Versõ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.

Habilitando Ferramentas de Edição de Arquivos, Bash e Web no Agent SDK

Buscar na documentação

Habilitando Ferramentas de Edição de Arquivos, Bash e Web no Agent SDK