Ferramentas
Configure as ferramentas disponíveis para o seu agente.
O Claude Managed Agents fornece um conjunto de ferramentas integradas que o Claude pode usar de forma autônoma dentro de uma sessão. Você controla quais ferramentas estão disponíveis especificando-as na configuração do agente.
O Claude Managed Agents também oferece suporte a ferramentas personalizadas, definidas pelo usuário. Sua aplicação executa essas ferramentas separadamente e retorna os resultados para Claude, que os usa para continuar a tarefa. Para dar ao agente ferramentas de um servidor MCP, use o conector MCP em vez disso.
Ferramentas disponíveis
O conjunto de ferramentas do agente inclui as seguintes ferramentas. Todas são habilitadas por padrão quando você inclui o conjunto de ferramentas na configuração do agente.
| Ferramenta | Nome | Descrição |
|---|---|---|
| Bash | bash | Executar comandos bash em uma sessão de shell |
| Read | read | Lê um arquivo do sistema de arquivos do sandbox |
| Write | write | Grava um arquivo no sistema de arquivos do sandbox |
| Edit | edit | Realiza substituição de strings em um arquivo |
| Glob | glob | Realizar correspondência rápida de padrões de arquivos usando padrões glob |
| Grep | grep | Pesquisar texto usando padrões regex |
| Web fetch | web_fetch | Busca conteúdo de uma URL |
| Pesquisa na web | web_search | Pesquisa informações na web |
Quando a saída de uma ferramenta excede 100.000 caracteres (cerca de 25.000 tokens), ela é automaticamente gravada em um arquivo no sandbox. O modelo recebe uma prévia truncada com o caminho do arquivo e pode ler o conteúdo completo a partir dali.
Configurando o conjunto de ferramentas
Habilite o conjunto completo de ferramentas com agent_toolset_20260401 ao criar um agente. Use o array configs para desabilitar ferramentas específicas ou substituir suas configurações. Cada entrada é identificada pelo seu name, que recebe um valor da coluna Nome em Ferramentas disponíveis. Uma entrada também aceita um campo opcional type com o mesmo valor.
Cada entrada de configuração também pode definir uma permission_policy. A política controla se as chamadas da ferramenta são executadas sem confirmação, exigem confirmação ou vão para o servidor, que avalia cada chamada. Consulte Políticas de permissão para ver os tipos de política disponíveis.
O exemplo a seguir habilita o conjunto de ferramentas e desabilita web_fetch:
ant apply agent.md---
name: Coding Assistant
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
configs:
- name: web_fetch
enabled: false
---Desabilitando ferramentas específicas
Para desabilitar uma ferramenta, defina enabled: false na sua entrada em configs:
{
"type": "agent_toolset_20260401",
"configs": [
{ "name": "web_fetch", "enabled": false },
{ "name": "web_search", "enabled": false }
]
}Habilitando apenas ferramentas específicas
O objeto default_config define a base para todas as ferramentas do conjunto, e as entradas configs por ferramenta a substituem. Para começar com tudo desativado e habilitar apenas o que você precisa, defina default_config.enabled como false:
{
"type": "agent_toolset_20260401",
"default_config": { "enabled": false },
"configs": [
{ "name": "bash", "enabled": true },
{ "name": "read", "enabled": true },
{ "name": "write", "enabled": true }
]
}Restringindo a pesquisa na web e o web fetch
As entradas web_search e web_fetch também aceitam listas de domínios, um limite para o conteúdo buscado e uma localização de pesquisa. Consulte Restringir domínios de pesquisa na web e web fetch.
Tipos de entrada de configuração nos SDKs
Os SDKs tipam cada entrada de configs por ferramenta. O tipo é uma união com um membro para cada ferramenta integrada, discriminada por type.
Em Go, Java, C# e PHP, você constrói as entradas a partir de valores tipados em vez de dicionários ou hashes simples. Nesses SDKs, o tipo de elemento de configs é a própria união, então construa cada entrada a partir do seu tipo de membro por ferramenta.
Você pode omitir type ao construir uma entrada, porque o servidor o infere a partir de name. As respostas sempre o incluem. Essa tipagem não altera o JSON para o qual uma entrada é serializada. Uma requisição cujas entradas definem apenas name, enabled e permission_policy é válida com ou sem type.
Ferramentas personalizadas
As ferramentas personalizadas são análogas às ferramentas de cliente definidas pelo usuário na Messages API. Você especifica quais operações estão disponíveis e o que elas retornam, e o Claude determina quando e como chamá-las.
O Claude não executa uma ferramenta personalizada por conta própria. Ele emite uma requisição estruturada, seu código executa a operação e você retorna o resultado para a sessão.
O exemplo a seguir cria um agente com uma ferramenta personalizada, get_weather, e nenhuma ferramenta integrada:
ant apply agent.md---
name: Weather Agent
model: claude-opus-5-5
tools:
- type: custom
name: get_weather
description: Get current weather for a location
input_schema:
type: object
properties:
location:
type: string
description: City name
required:
- location
---Novos nomes de ferramentas personalizadas não podem começar com mcp__ ou ant__, nem corresponder ao nome de uma ferramenta integrada do agente. Uma requisição que viola essa regra retorna um erro 400. No entanto, uma ferramenta personalizada existente pode começar com ant__. Um agente com tal ferramenta aceita uma atualização somente se a atualização enviar tools sem esse nome, então renomeie ou remova a ferramenta na sua próxima atualização. Uma nova sessão é recusada com um erro 400 se tal ferramenta estiver no agente da sessão (após quaisquer substituições), em um agente na lista predefined_agents de subagents, ou em um agente na lista predefined_agents de workflows. Sessões que já existem não são afetadas.
O agente chama suas ferramentas personalizadas durante uma sessão. Para receber as chamadas e retornar resultados, consulte Responder a chamadas de ferramentas que pausam a sessão.
Para sessões executadas em um sandbox auto-hospedado, o worker do ambiente pode servir ferramentas personalizadas a partir do sandbox. Elas podem incluir ferramentas que encapsulam um servidor MCP dentro da sua rede.
Melhores práticas para definições de ferramentas personalizadas
- Forneça descrições extremamente detalhadas. Este é, de longe, o fator mais importante no desempenho das ferramentas. Quanto mais contexto você puder dar ao Claude sobre suas ferramentas, melhor ele será em determinar quando e como usá-las. Procure escrever de três a quatro frases para cada descrição de ferramenta, mais se a ferramenta for complexa. Suas descrições devem abordar:
- O que a ferramenta faz
- Quando usá-la e quando não usá-la
- O que cada parâmetro significa e como ele afeta o comportamento da ferramenta
- Quaisquer ressalvas ou limitações importantes
- Consolide operações relacionadas em menos ferramentas. Agrupe ações como
create_pr,review_premerge_prem uma única ferramenta com um parâmetroaction. Menos ferramentas, porém mais capazes, reduzem a ambiguidade na seleção e tornam sua superfície de ferramentas mais fácil de navegar para o Claude. - Use namespaces significativos nos nomes das ferramentas. Quando suas ferramentas abrangem vários serviços ou recursos, prefixe os nomes com o recurso (por exemplo,
db_queryoustorage_read). Isso torna a seleção de ferramentas inequívoca à medida que sua biblioteca cresce. - Projete as respostas das ferramentas para retornar apenas informações de alto valor. Retorne identificadores semânticos e estáveis (por exemplo, slugs ou UUIDs) em vez de referências internas opacas. Inclua apenas os campos de que o Claude precisa para determinar seu próximo passo. Respostas inchadas desperdiçam contexto e dificultam que o Claude extraia o que importa.
Próximos passos
Controle quais sites as ferramentas web podem acessar, limite o conteúdo buscado e localize os resultados de pesquisa.
Conecte servidores MCP aos seus agentes para acessar ferramentas e fontes de dados externas.
Controle quando as ferramentas do agente e do MCP são executadas.
Envie eventos, faça streaming de respostas e interrompa ou redirecione sua sessão enquanto ela é executada.
Disponibilidade
Claude API
- Status
- Beta
- API
- Managed Agents
- Cabeçalho beta
- Requer
- Modelos
- Todos os modelos
Claude Platform on AWS
- Status
- Beta
- API
- Managed Agents
- Cabeçalho beta
- Requer
- Modelos
- Todos os modelos
Tratamento de dados
Visão geral do tratamento de dadosEndpoints aplicáveis
/v1/agents/v1/sessions/v1/environments
Não é elegível para ZDR, exceto o Managed Agents auto-hospedado. Sessões são recursos com estado; as transcrições persistem até que você as exclua. Saiba mais
Não é elegível para HIPAA. Aplica-se a todos os sub-recursos do Managed Agents.
Esta página foi útil?