Políticas de permissão

As políticas de permissão controlam se as ferramentas executadas no servidor (o conjunto de ferramentas pré-construído do agente e o conjunto de ferramentas MCP) são executadas automaticamente ou aguardam sua aprovação. 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.



Tipos de política de permissão

Cada tipo de conjunto de ferramentas tem seu próprio padrão: o conjunto de ferramentas do agente usa always_allow por padrão, e os conjuntos de ferramentas MCP usam always_ask por padrão.

Uma política de permissão controla quando uma ferramenta habilitada é executada. Para remover uma ferramenta do agente completamente, desabilite-a em vez disso. Consulte Desabilitar ferramentas específicas.



Definir uma política para um conjunto de ferramentas

Você define políticas de permissão na configuração tools do agente ao criá-lo, e pode alterá-las posteriormente atualizando o agente. Sessões em execução mantêm a configuração de conjunto de ferramentas com a qual foram criadas. As atualizações se aplicam a sessões criadas posteriormente.



Permissões do conjunto de ferramentas do agente

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

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

default_config é opcional. Se você omiti-lo, o conjunto de ferramentas do agente é habilitado com a política de permissão padrão, always_allow.



Permissões do conjunto de ferramentas MCP

Os conjuntos de ferramentas MCP usam always_ask por padrão. 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 default_config.permission_policy na entrada mcp_toolset.

O mcp_server_name deve corresponder ao name de um servidor 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-8
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 de ferramentas individuais. Os valores de name para o conjunto de ferramentas do agente estão listados em Ferramentas disponíveis. Este exemplo permite todo o conjunto de ferramentas do agente por padrão, mas exige confirmação antes que qualquer comando bash seja executado:

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

Passe essa configuração tools na requisição de criação do agente (a aba CLI mostra o comando completo). Os conjuntos de ferramentas MCP suportam as mesmas substituições por ferramenta, com name definido como o nome da ferramenta reportado pelo servidor MCP. Consulte Configurar quais ferramentas MCP estão disponíveis.



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 cujo stop_reason.type é requires_action. Os IDs dos eventos bloqueantes estão no array stop_reason.event_ids. A sessão aguarda indefinidamente por uma resposta.
3. Envie um evento user.tool_confirmation para cada evento bloqueante, 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. Você pode enviar várias confirmações em uma única requisição events.
4. Assim que todos os eventos bloqueantes forem resolvidos, a sessão volta ao estado running. Ferramentas permitidas são executadas. Ferramentas negadas não são executadas, e o agente recebe um resultado de ferramenta informando que a chamada foi rejeitada, incluindo sua deny_message.

Nos exemplos a seguir, os IDs dos eventos de uso de ferramentas vêm do array stop_reason.event_ids do evento session.status_idle. Saiba mais sobre como receber eventos no guia Fluxo de eventos da sessão, ou assine webhooks para ser notificado quando uma sessão pausar aguardando entrada.

# Permitir que a ferramenta seja executada
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# Ou negá-la com uma explicação
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{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. Consulte Fluxo de eventos da sessão para o fluxo completo.



Próximos passos