Políticas de permissão

As políticas de permissão controlam se 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. Ferramentas personalizadas são executadas por sua aplicação e controladas por você, portanto não são regidas por políticas de permissão.

Tipos de política de permissão

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 cada ferramenta em agent_toolset_20260401 usando default_config.permission_policy:

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-7
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
YAML

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

Permissões do conjunto de ferramentas MCP

Os conjuntos de ferramentas MCP usam como padrão always_ask. Isso garante que novas ferramentas adicionadas a um servidor MCP não sejam executadas em 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:

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

Substituir a política de uma ferramenta individual

Use o array configs para substituir o padrão para 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:

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

Responder a solicitações de confirmação

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

1. A sessão emite um evento agent.tool_use ou agent.mcp_tool_use.
2. A sessão pausa com um evento session.status_idle contendo stop_reason: requires_action. Os IDs de eventos bloqueadores estão no array stop_reason.requires_action.event_ids.
3. 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.
4. Depois que todos os eventos bloqueadores forem resolvidos, a sessão faz a transição de volta para running.

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

# Permitir que a ferramenta seja executada
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Ou negá-la com uma explicação
client.beta.sessions.events.send(
    session.id,
    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.",
        },
    ],
)

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. Veja fluxo de eventos de sessão para o fluxo completo.