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 seu agente. Cada entrada no array configs é identificada pelo seu name, usando os valores da coluna Nome, e aceita um campo opcional type com o mesmo valor. As entradas web_search e web_fetch aceitam configurações adicionais; consulte Restringir domínios de busca na web e busca de conteúdo 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 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 ver os tipos de política disponíveis.

As entradas de configuração para web_search e web_fetch também aceitam filtros de domínio e outras configurações web; consulte Restringir domínios de busca na web e busca de conteúdo web.

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

Desabilitando ferramentas específicas

Para desabilitar uma ferramenta, defina enabled: false na sua entrada de configuração 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 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 }
  ]
}

Restringir domínios de busca na web e busca de conteúdo web

Para controlar quais sites as ferramentas web do agente podem acessar, defina allowed_domains (a ferramenta pode acessar apenas esses hosts) ou blocked_domains (a ferramenta nunca pode acessar esses hosts) nas entradas web_search e web_fetch do array configs do conjunto de ferramentas. Cada ferramenta mantém sua própria lista, portanto web_search e web_fetch podem ter restrições diferentes. Um domínio listado abrange esse host e todos os seus subdomínios. Em tempo de execução, uma chamada web_fetch para uma URL que suas listas não permitem retorna um resultado de erro ao agente (is_error: true no evento agent.tool_result, com conteúdo que indica o código de erro url_not_allowed), e web_search omite resultados que suas listas não permitem.

O conjunto de ferramentas a seguir limita web_search a dois sites e localiza seus resultados, e bloqueia um host para web_fetch enquanto limita a quantidade de conteúdo buscado que entra no contexto:

{
  "type": "agent_toolset_20260401",
  "configs": [
    {
      "type": "web_search",
      "name": "web_search",
      "allowed_domains": ["docs.example.com", "arxiv.org"],
      "user_location": {
        "type": "approximate",
        "country": "US",
        "timezone": "America/Los_Angeles"
      }
    },
    {
      "type": "web_fetch",
      "name": "web_fetch",
      "blocked_domains": ["ads.example.com"],
      "max_content_tokens": 50000
    }
  ]
}

A requisição a seguir cria um agente com esse conjunto de ferramentas e imprime o array configs da resposta:

ant beta:agents create --transform tools.0.configs <<'YAML'
name: Research Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_search
        name: web_search
        allowed_domains: [docs.example.com, arxiv.org]
        user_location:
          type: approximate
          country: US
          timezone: America/Los_Angeles
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000
YAML

No Claude Console, defina domínios permitidos ou bloqueados nas linhas web_search e web_fetch do cartão Built-in tools no formulário do agente; defina max_content_tokens e user_location na visualização Raw da configuração do agente.

Além de enabled e permission_policy, as entradas das ferramentas web aceitam as seguintes configurações:

Regras das listas de domínios

• Defina allowed_domains ou blocked_domains em uma entrada, não ambos. Uma entrada que define ambos é rejeitada.
• Cada lista contém de 1 a 64 domínios, cada um com 1 a 255 caracteres. Uma lista vazia é rejeitada: para não aplicar nenhuma restrição, omita o campo ou envie null.
• Cada domínio é um nome de domínio registrável, ou um subdomínio de um, escrito como um hostname simples: letras ASCII, dígitos, hífens, sublinhados e pontos, sem esquema, porta, credenciais, curinga ou espaço em branco, sem nenhum rótulo que comece ou termine com hífen, e sem caminho além do sufixo de caminho opcional de web_search descrito mais adiante nesta lista. Use example.com, não https://example.com, example.com:443 ou *.example.com. Os hostnames são comparados sem distinção entre maiúsculas e minúsculas, e uma única / final é ignorada.
• Um domínio listado corresponde a esse host e seus subdomínios: example.com abrange docs.example.com, mas docs.example.com não abrange example.com nem api.example.com. Um www. inicial é um subdomínio como qualquer outro, portanto www.example.com não abrange example.com; liste o domínio sem prefixo para abranger ambos.
• Endereços IP não são aceitos em nenhuma forma, seja IPv4, IPv6, entre colchetes ou abreviação numérica como 127.1. Liste o nome de domínio do site em vez disso.
• Um domínio de nível superior isolado ou sufixo de registro como com, co.uk ou gov.uk é rejeitado, assim como um nome de rótulo único como intranet. Liste um domínio completo como example.co.uk.
• localhost e hosts terminados em .localhost, .local, .internal, .localdomain ou .invalid são rejeitados.
• Use a forma xn-- (Punycode) para nomes de domínio internacionalizados; um domínio que contém caracteres não ASCII é rejeitado.
• Um domínio de web_fetch não pode incluir um caminho: use example.com, não example.com/*. Um domínio de web_search pode conter um sufixo de caminho como example.com/blog, no qual o caminho não pode conter espaços, ?, # ou qualquer um dos caracteres $ , | ^ !. Prefira hostnames simples também para web_search, porque o provedor de busca corresponde sufixos de caminho como padrões de URL e não como regras estritas de host.
• Domínios duplicados dentro de uma lista são rejeitados. www.example.com e example.com contam como domínios diferentes; consulte a regra de correspondência anterior para saber o que cada um abrange.

Quando as configurações são validadas

Violações de formato e de limite são rejeitadas com um erro 400 invalid_request_error quando você cria um agente ou atualiza um agente, e quando você cria ou atualiza uma sessão que fornece tools. Por exemplo, a mensagem para uma entrada que define ambas as listas inclui Only one of allowed_domains or blocked_domains may be set., e a mensagem para uma lista vazia inclui allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. A mensagem para um domínio que viola uma regra de formato indica sua lista e posição baseada em zero, por exemplo allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

As mesmas requisições também rejeitam três configurações que dependem dos provedores de busca e de busca de conteúdo: um domínio em allowed_domains que o crawler da Anthropic não tem permissão para acessar, um user_location.country que o provedor de busca não suporta (a mensagem termina em user_location.country: not a country the search provider supports) e um user_location.timezone que não é um nome IANA válido. A sessão verifica a configuração novamente quando inicializa a ferramenta pela primeira vez; se uma configuração que foi aceita anteriormente não for mais válida nesse momento, a sessão emite um evento session.error e retorna para idle sem tentar novamente. Corrija a configuração atualizando as ferramentas da sessão, atualize também o agente para que novas sessões comecem com a configuração corrigida e, em seguida, envie uma nova user.message para continuar.

Sessões multiagente, resultados e atualizações no meio da sessão

Em uma sessão multiagente, todas as listas de domínios que se aplicam a uma thread são aplicadas ao mesmo tempo: um agente na lista (roster) do coordenador está vinculado aos seus próprios allowed_domains e blocked_domains, aos de qualquer agente que o chamou e às listas atuais do coordenador.

• As listas de permissão se combinam nos domínios que todas elas abrangem, e as listas de bloqueio se somam, portanto um agente do roster pode restringir o que uma ferramenta acessa, mas nunca ampliar. Por exemplo, um agente do roster que define blocked_domains mantém os allowed_domains do coordenador e bloqueia esses hosts dentro deles, e um agente do roster que define seus próprios allowed_domains pode acessar apenas os hosts que tanto sua lista quanto a lista do coordenador abrangem.
• Se as listas de permissão combinadas não tiverem nenhum domínio em comum, a ferramenta permanece disponível para esse agente, mas toda chamada falha com um erro url_not_allowed informando que nenhum domínio é permitido, e a descrição da ferramenta informa isso ao modelo. Mantenha a lista de permissão de cada agente do roster dentro da do coordenador para evitar isso.
• max_content_tokens e user_location não são combinados: uma thread usa o valor da sua própria configuração de ferramenta, se definido; caso contrário, do agente que a chamou; caso contrário, da configuração atual do coordenador.
• Uma entrada de roster {"type": "self"} não tem configurações web próprias e segue as configurações atuais do coordenador.
• O avaliador em sessões orientadas a resultados é executado sem web_search e web_fetch, independentemente dessas configurações.
• Você pode alterar as listas em uma sessão ociosa atualizando suas ferramentas. As novas listas se aplicam ao restante da sessão; em uma sessão multiagente, cada thread as aplica a partir do seu próximo turno, enquanto as listas próprias de um agente do roster permanecem como sua definição de agente as estabeleceu quando a sessão foi criada.

Diferenças em relação às ferramentas da Messages API

Essas configurações usam o mesmo vocabulário allowed_domains e blocked_domains da filtragem de domínios nas ferramentas de servidor da Messages API, com as seguintes diferenças no Managed Agents:

• Cada lista é limitada a 64 domínios.
• Os domínios listados para web_fetch não podem incluir um caminho.
• Os domínios devem ser ASCII: use a forma xn-- (Punycode) para nomes de domínio internacionalizados. A Messages API aceita entradas Unicode, embora recomende não usá-las.
• max_uses, citations e cache_control não estão disponíveis no conjunto de ferramentas.

Ferramentas personalizadas

Além das ferramentas integradas, você pode definir ferramentas personalizadas. As 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 requisiçã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.

Se suas sessões são executadas em um sandbox auto-hospedado, o worker do ambiente pode servir ferramentas personalizadas a partir do seu sandbox, incluindo ferramentas que encapsulam um servidor MCP dentro da sua rede.

ant beta:agents create < agent.yaml

name: Weather Agent
model: claude-opus-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

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

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. 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 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.
• 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, mais capazes, reduzem a ambiguidade de seleção e tornam sua superfície de ferramentas mais fácil para o Claude navegar.
• 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, e inclua apenas os campos de que o Claude precisa para determinar seu próximo passo. Respostas inchadas desperdiçam contexto e tornam mais difícil para o Claude extrair o que importa.

Próximos passos