---
title: Ferramentas
url: https://platform.claude.com/docs/pt-BR/managed-agents/tools
description: Configure as ferramentas disponíveis para o seu agente.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

O Claude Managed Agents fornece um conjunto de ferramentas integradas que o Claude pode usar de forma autônoma dentro de uma [sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions). 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](https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector).

## 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`       | Executa 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`       | Correspondência rápida de padrões de arquivos usando padrões glob |
| Grep       | `grep`       | Busca de texto usando padrões regex                               |
| Web fetch  | `web_fetch`  | Busca conteúdo de uma URL                                         |
| Web search | `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](https://platform.claude.com/docs/pt-BR/managed-agents/environments). 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` (csharp, go: `Configs`) para desabilitar ferramentas específicas ou substituir suas configurações. Cada entrada é identificada pelo seu `name` (csharp, go: `Name`), que recebe um valor da coluna Nome em [Ferramentas disponíveis](https://platform.claude.com/docs/pt-BR/managed-agents/tools#available-tools). Uma entrada também aceita um campo opcional `type` (csharp, go: `Type`) com o mesmo valor.

Cada entrada de configuração também pode definir uma `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). 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](https://platform.claude.com/docs/pt-BR/managed-agents/permission-policies) para ver os tipos de política disponíveis.

O exemplo a seguir habilita o conjunto de ferramentas e desabilita `web_fetch`:

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "Coding Assistant",
      "model": "claude-opus-5-5",
      "tools": [
        {
          "type": "agent_toolset_20260401",
          "configs": [
            {"name": "web_fetch", "enabled": false}
          ]
        }
      ]
    }'
  )
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply agent.md
    ```

    <File filename="agent.md">
      ```markdown
      ---
      name: Coding Assistant
      model: claude-opus-5-5
      tools:
        - type: agent_toolset_20260401
          configs:
            - name: web_fetch
              enabled: false
      ---
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  agent = client.beta.agents.create(
      name="Coding Assistant",
      model="claude-opus-5-5",
      tools=[
          {
              "type": "agent_toolset_20260401",
              "configs": [
                  {"name": "web_fetch", "enabled": False},
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  const agent = await client.beta.agents.create({
    name: "Coding Assistant",
    model: "claude-opus-5-5",
    tools: [
      {
        type: "agent_toolset_20260401",
        configs: [{ name: "web_fetch", enabled: false }]
      }
    ]
  });
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Agents;

  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Coding Assistant",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Type = "agent_toolset_20260401",
              Configs =
              [
                  new BetaManagedAgentsWebFetchToolConfigParams { Enabled = false },
              ],
          },
      ],
  });
  ```

  ```go Go
  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name: "Coding Assistant",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{
  		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  	},
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
  			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
  			Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{
  				OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{
  					Enabled: anthropic.Bool(false),
  				},
  			}},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  _ = agent
  ```

  ```java Java
  import com.anthropic.models.beta.agents.*;

  var agent = client.beta().agents().create(AgentCreateParams.builder()
      .name("Coding Assistant")
      .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
      .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
          .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
          .addConfig(BetaManagedAgentsWebFetchToolConfigParams.builder()
              .enabled(false)
              .build())
          .build())
      .build());
  ```

  ```php PHP
  use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
  use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams;

  $agent = $client->beta->agents->create(
      name: 'Coding Assistant',
      model: 'claude-opus-5-5',
      tools: [
          BetaManagedAgentsAgentToolset20260401Params::with(
              type: 'agent_toolset_20260401',
              configs: [
                  BetaManagedAgentsWebFetchToolConfigParams::with(enabled: false),
              ],
          ),
      ],
  );
  ```

  ```ruby Ruby
  agent = client.beta.agents.create(
    name: "Coding Assistant",
    model: "claude-opus-5-5",
    tools: [
      {
        type: :agent_toolset_20260401,
        configs: [
          {name: :web_fetch, enabled: false}
        ]
      }
    ]
  )
  ```
</CodeGroup>

### Desabilitando ferramentas específicas

Para desabilitar uma ferramenta, defina `enabled: false` na sua entrada em `configs`:

```json
{
  "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`:

```json
{
  "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](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions).

### Tipos de entrada de configuração nos SDKs

Os SDKs de Python, TypeScript, Go, Java, C#, Ruby e PHP tipam cada entrada de `configs` (csharp, go: `Configs`) por ferramenta. O tipo é uma união com um membro por ferramenta integrada, discriminada por `type` (csharp, go: `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` (csharp, go: `Configs`) é a própria união, então construa cada entrada a partir do seu tipo de membro por ferramenta.

Você pode omitir `type` (csharp, go: `Type`) ao construir uma entrada, porque o servidor o infere a partir de `name` (csharp, go: `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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/how-tool-use-works#user-defined-tools-client-executed) 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`:

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "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"]
          }
        }
      ]
    }'
  )
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply agent.md
    ```

    <File filename="agent.md">
      ```markdown
      ---
      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
      ---
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  agent = client.beta.agents.create(
      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"],
              },
          },
      ],
  )
  ```

  ```typescript TypeScript
  const agent = await client.beta.agents.create({
    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"]
        }
      }
    ]
  });
  ```

  ```csharp C#
  using System.Text.Json;
  using Anthropic.Models.Beta.Agents;

  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Weather Agent",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Type = "agent_toolset_20260401",
          },
          new BetaManagedAgentsCustomToolParams
          {
              Type = "custom",
              Name = "get_weather",
              Description = "Get current weather for a location",
              InputSchema = new()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(
                          new { type = "string", description = "City name" }
                      ),
                  },
                  Required = ["location"],
              },
          },
      ],
  });
  ```

  ```go Go
  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name: "Weather Agent",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{
  		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  	},
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
  			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
  		},
  	}, {
  		OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
  			Type:        anthropic.BetaManagedAgentsCustomToolParamsTypeCustom,
  			Name:        "get_weather",
  			Description: "Get current weather for a location",
  			InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{
  						"type":        "string",
  						"description": "City name",
  					},
  				},
  				Required: []string{"location"},
  			},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  _ = agent
  ```

  ```java Java
  import com.anthropic.models.beta.agents.*;
  import java.util.Map;

  var agent = client.beta().agents().create(AgentCreateParams.builder()
      .name("Weather Agent")
      .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
      .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
          .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
          .build())
      .addTool(BetaManagedAgentsCustomToolParams.builder()
          .type(BetaManagedAgentsCustomToolParams.Type.CUSTOM)
          .name("get_weather")
          .description("Get current weather for a location")
          .inputSchema(BetaManagedAgentsCustomToolInputSchema.builder()
              .properties(BetaManagedAgentsCustomToolInputSchema.Properties.builder()
                  .putAdditionalProperty("location", JsonValue.from(Map.of(
                      "type", "string",
                      "description", "City name")))
                  .build())
              .addRequired("location")
              .build())
          .build())
      .build());
  ```

  ```php PHP
  use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
  use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema;
  use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams;

  $agent = $client->beta->agents->create(
      name: 'Weather Agent',
      model: 'claude-opus-5-5',
      tools: [
          BetaManagedAgentsAgentToolset20260401Params::with(
              type: 'agent_toolset_20260401',
          ),
          BetaManagedAgentsCustomToolParams::with(
              type: 'custom',
              name: 'get_weather',
              description: 'Get current weather for a location',
              inputSchema: BetaManagedAgentsCustomToolInputSchema::with(
                  properties: ['location' => ['type' => 'string', 'description' => 'City name']],
                  required: ['location'],
              ),
          ),
      ],
  );
  ```

  ```ruby Ruby
  agent = client.beta.agents.create(
    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"]
        }
      }
    ]
  )
  ```
</CodeGroup>

O nome de uma ferramenta personalizada não pode 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. Um agente que já possui uma ferramenta personalizada cujo nome começa com `ant__` aceita uma atualização somente se a atualização enviar `tools` (csharp, go: `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](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#override-agent-configuration-for-a-session)), em um agente na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), ou em um agente na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `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 [Fluxo de eventos da sessão](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#handling-custom-tool-calls).

Para sessões executadas em um sandbox auto-hospedado, o worker do ambiente pode [servir ferramentas personalizadas a partir do sandbox](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-custom-tools). 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

<CardGroup cols={2}>
  <Card title="Restringir domínios de pesquisa na web e busca na web" icon="shield" href="https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions">
    Controle quais sites as ferramentas web podem acessar, limite o conteúdo buscado e localize os resultados de pesquisa.
  </Card>

  <Card title="Conector MCP" icon="link" href="https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector">
    Conecte servidores MCP aos seus agentes para acessar ferramentas e fontes de dados externas.
  </Card>

  <Card title="Políticas de permissão" icon="lock" href="https://platform.claude.com/docs/pt-BR/managed-agents/permission-policies">
    Controle quando as ferramentas do agente e do MCP são executadas.
  </Card>

  <Card title="Fluxo de eventos da sessão" icon="lightning" href="https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming">
    Envie eventos, faça streaming de respostas e interrompa ou redirecione sua sessão durante a execução.
  </Card>
</CardGroup>