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 ferramentas a seguir. Todas são habilitadas por padrão quando você inclui o conjunto de ferramentas na configuração do seu agente. Use os valores na coluna Nome para referenciar ferramentas no array configs.

Quando a saída de uma ferramenta excede 100.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 dele.



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 de configuração também pode definir uma permission_policy que controla se as chamadas da ferramenta são aprovadas automaticamente ou exigem confirmação. Consulte Políticas de permissão para conhecer os tipos de política disponíveis.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML



Desabilitando ferramentas específicas

Para desabilitar uma ferramenta, defina enabled: false na entrada de configuração correspondente no objeto do conjunto de ferramentas do array tools do seu agente:

{
  "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 individuais em configs 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 }
  ]
}



Ferramentas personalizadas

Além das ferramentas integradas, você pode definir ferramentas personalizadas. Ferramentas personalizadas são análogas às ferramentas de cliente definidas pelo usuário na Messages API.

Cada ferramenta personalizada define um contrato: você especifica quais operações estão disponíveis e o que elas retornam, e o Claude determina quando e como chamá-las. O modelo nunca executa nada por conta própria. Ele emite uma solicitação estruturada, seu código executa a operação e o resultado retorna para a conversa. Consulte Fluxo de eventos da sessão para saber como receber chamadas de ferramentas personalizadas e retornar resultados durante uma sessão.

ant beta:agents create <<'YAML'
name: Weather Agent
model: claude-opus-4-8
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
YAML

Depois de definir ferramentas personalizadas no agente, ele as invoca durante uma sessão.



Práticas recomendadas para definições de ferramentas personalizadas

• Forneça descrições extremamente detalhadas. Este é, de longe, o fator mais importante no desempenho das ferramentas. Suas descrições devem explicar o que a ferramenta faz e quando usá-la (e quando não usá-la). Explique o que cada parâmetro significa e como ele afeta o comportamento da ferramenta. Destaque quaisquer ressalvas ou limitações importantes. Quanto mais contexto você puder fornecer 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, ou mais se a ferramenta for complexa.
• Consolide operações relacionadas em menos ferramentas. Em vez de criar uma ferramenta separada para cada ação (create_pr, review_pr, merge_pr), agrupe-as em uma única ferramenta com um parâmetro action. Menos ferramentas, porém mais capazes, reduzem a ambiguidade na seleção e tornam seu conjunto de ferramentas mais fácil de navegar para o Claude.
• Use namespacing significativo 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, e inclua apenas os campos de que o Claude precisa para determinar seu próximo passo. Respostas inchadas desperdiçam contexto e dificultam para o Claude extrair o que importa.



Próximos passos