Políticas de permissão

As políticas de permissão controlam se as ferramentas executadas pelo servidor (o conjunto de ferramentas de agente pré-construído e o conjunto de ferramentas MCP) são executadas automaticamente ou aguardam sua aprovação. As ferramentas personalizadas são executadas pela sua aplicação e controladas por você, portanto não são regidas por políticas de permissão.

Todas as solicitações da API Managed Agents requerem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Tipos de políticas de permissão

Política	Comportamento
`always_allow`	A ferramenta é executada automaticamente sem confirmação.
`always_ask`	A sessão emite um evento `session.status_idle` e aguarda um evento `user.tool_confirmation` antes de executar.

Definir uma política para um conjunto de ferramentas

Permissões do conjunto de ferramentas de agente

Ao criar um agente, você pode opcionalmente aplicar uma política a todas as ferramentas em agent_toolset_20260401 usando default_config.permission_policy:

default_config é uma configuração opcional. Se você omiti-la, o conjunto de ferramentas de agente será habilitado com a política de permissão padrão, always_allow.

Permissões do conjunto de ferramentas MCP

Os conjuntos de ferramentas MCP têm como padrão always_ask. Isso garante que novas ferramentas adicionadas a um servidor MCP não sejam executadas na sua aplicação sem aprovação. Para aprovar automaticamente ferramentas de um servidor MCP confiável, defina permission_policy na entrada mcp_toolset.

O mcp_server_name deve corresponder ao name referenciado no array mcp_servers.

Este exemplo conecta um servidor MCP do GitHub e permite que suas ferramentas sejam executadas sem confirmação:

Substituir a política de uma ferramenta individual

Use o array configs para substituir o padrão de ferramentas individuais. Este exemplo permite o conjunto completo de ferramentas de agente por padrão, mas requer confirmação antes de qualquer comando bash ser executado:

Responder a solicitações de confirmação

Quando o agente invoca uma ferramenta com uma política always_ask:

A sessão emite um evento agent.tool_use ou agent.mcp_tool_use.
A sessão é pausada com um evento session.status_idle contendo stop_reason: requires_action. Os IDs de eventos bloqueantes estão no array stop_reason.requires_action.event_ids.
Envie um evento user.tool_confirmation para cada um, passando o ID do evento no parâmetro tool_use_id. Defina result como "allow" ou "deny". Use deny_message para explicar uma negação.
Assim que todos os eventos bloqueantes forem resolvidos, a sessão volta ao estado running.

Saiba mais sobre o tratamento de eventos no guia de fluxo de eventos de sessão.

Ferramentas personalizadas

As políticas de permissão não se aplicam a ferramentas personalizadas. Quando o agente invoca uma ferramenta personalizada, sua aplicação recebe um evento agent.custom_tool_use e é responsável por decidir se deve executá-la antes de enviar de volta um user.custom_tool_result. Consulte o Fluxo de eventos de sessão para o fluxo completo.

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-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }')

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": "Dev Assistant",
    "model": "claude-sonnet-4-6",
    "mcp_servers": [
      {"type": "url", "name": "github", "url": "https://mcp.example.com/github"}
    ],
    "tools": [
      {"type": "agent_toolset_20260401"},
      {
        "type": "mcp_toolset",
        "mcp_server_name": "github",
        "default_config": {
          "permission_policy": {"type": "always_allow"}
        }
      }
    ]
  }')

tools='[
  {
    "type": "agent_toolset_20260401",
    "default_config": {
      "permission_policy": {"type": "always_allow"}
    },
    "configs": [
      {
        "name": "bash",
        "permission_policy": {"type": "always_ask"}
      }
    ]
  }
]'

# Permitir que a ferramenta seja executada
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -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 '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
        "result": "allow"
      }
    ]
  }'

# Ou negar com uma explicação
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -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 '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$MCP_TOOL_USE_EVENT_ID'",
        "result": "deny",
        "deny_message": "Don'\''t create issues in the production project. Use the staging project."
      }
    ]
  }'