Políticas de permissão

As "permission policies" (políticas de permissão) controlam se as ferramentas executadas no 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.

Tipos de política de permissão

Cada tipo de conjunto de ferramentas tem seu próprio padrão: o conjunto de ferramentas de 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 completamente uma ferramenta do agente, desabilite-a. Consulte Desabilitando ferramentas específicas.

Definir uma política para um conjunto de ferramentas

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

Permissões do conjunto de ferramentas de 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 < agent.yaml

name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask

default_config é opcional. Se você o omitir, 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 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 as 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 < agent.yaml

name: Dev Assistant
model: claude-opus-5
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

Substituir a política de uma ferramenta individual

Use o array configs para substituir o padrão para ferramentas individuais. Os valores de name para o conjunto de ferramentas de agente estão listados em Ferramentas disponíveis. Este exemplo permite o conjunto completo de ferramentas de agente por padrão, mas exige confirmação antes da execução de qualquer comando bash:

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

Passe esta 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 informado 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. Depois que todos os eventos bloqueantes forem resolvidos, a sessão volta ao estado running. As ferramentas permitidas são executadas. As 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 inscreva-se em 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 ver o fluxo completo.

Próximos passos