Ferramentas

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 ao Claude, que os utiliza para continuar a tarefa. Para fornecer ao agente ferramentas de um servidor MCP, use o conector MCP.

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.

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 são avaliadas individualmente pelo servidor. 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 a busca na web

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 busca na web.

Tipos de entrada de configuração nos SDKs

Os SDKs de Python, TypeScript, Go, Java, C#, Ruby e PHP tipam cada entrada de configs por ferramenta. O tipo é uma união com um membro por 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, portanto 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 o conjunto de ferramentas integrado e uma ferramenta personalizada, get_weather:

ant apply agent.md

---
name: Weather Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
  - 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
---

O agente chama suas ferramentas personalizadas durante uma sessão. Para receber as chamadas e retornar resultados, consulte Fluxo de eventos da 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_pr e merge_pr em uma única ferramenta com um parâmetro action. 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_query ou storage_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