---
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
  zdr:
    eligibility: not-eligible
    note: 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.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
---

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 para Claude, que os usa para continuar a tarefa. Para dar ao agente ferramentas de um servidor MCP, use o [conector MCP](https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector) 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](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 vão para o servidor, que avalia cada chamada. 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
  curl -fsSL https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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
          {
              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{
  			Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{
  				OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{
  					Enabled: anthropic.Bool(false),
  				},
  			}},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```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()
          .addConfig(BetaManagedAgentsWebFetchToolConfigParams.builder()
              .enabled(false)
              .build())
          .build())
      .build());
  ```

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

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

  ```ruby Ruby
  agent = client.beta.agents.create(
    name: "Coding Assistant",
    model: Anthropic::Beta::BetaManagedAgentsModel::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 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](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions).

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

Os SDKs tipam cada entrada de `configs` (csharp, go: `Configs`) por ferramenta. O tipo é uma união com um membro para cada 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 uma ferramenta personalizada, `get_weather`, e nenhuma ferramenta integrada:

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

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

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

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

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

  ```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 BetaManagedAgentsCustomToolParams
          {
              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{{
  		OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
  			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)
  }
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  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(BetaManagedAgentsCustomToolParams.builder()
          .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\BetaManagedAgentsCustomToolInputSchema;
  use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams;
  use Anthropic\Beta\Agents\BetaManagedAgentsModel;

  $agent = $client->beta->agents->create(
      name: 'Weather Agent',
      model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
      tools: [
          BetaManagedAgentsCustomToolParams::with(
              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: Anthropic::Beta::BetaManagedAgentsModel::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"]
        }
      }
    ]
  )
  ```
</CodeGroup>

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` (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 [Responder a chamadas de ferramentas que pausam a 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 web fetch" 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 enquanto ela é executada.
  </Card>
</CardGroup>

## Disponibilidade

Conjunto de ferramentas do agente está em beta em todos os modelos.

### Suporte da API

#### [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview)

* Disponibilidade: Disponível

| Status | Plataformas de nuvem |
| ----- | ----- |
| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws) |

### Cabeçalhos beta obrigatórios

[Visão geral dos cabeçalhos beta](https://platform.claude.com/docs/pt-BR/api/beta-headers)

Os cabeçalhos beta permitem que você acesse recursos experimentais e novas capacidades de modelos antes que eles se tornem parte da API padrão.

* `managed-agents-2026-04-01`

### Tratamento de dados

[Visão geral do tratamento de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#feature-eligibility)

| Item | Retenção zero de dados | HIPAA |
| ----- | ----- | ----- |
| Status | Não elegível | Não elegível |
| Detalhes | 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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-data-and-access#how-long-data-is-kept) | Não é elegível para HIPAA. Aplica-se a todos os sub-recursos do Managed Agents. |

Endpoints aplicáveis:

* `/v1/agents`
* `/v1/sessions`
* `/v1/environments`
