Políticas de permissão

As "permission policies" (políticas de permissão) controlam se as ferramentas executadas pelo servidor (o "toolset" (conjunto de ferramentas) pré-construído do agente e o conjunto de ferramentas MCP) são executadas automaticamente, aguardam sua aprovação ou têm cada chamada avaliada pelo servidor. 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 apply agent.md

---
name: Coding Assistant
model: claude-opus-5-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 apply agent.md

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

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

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.

Deixe o servidor avaliar cada chamada com auto

Com a política de permissão auto, o servidor avalia cada chamada antes de ela ser executada. Como a avaliação considera a ferramenta, a entrada da chamada e o conteúdo da sessão até aquele momento, o servidor pode tratar de forma diferente duas chamadas para a mesma ferramenta. Cada chamada tem um de três resultados:

• A chamada é executada. Quando o servidor determina que a chamada é segura, a ferramenta é executada como seria sob always_allow.
• A chamada é negada. Quando o servidor avalia a chamada como de alto risco, a ferramenta não é executada. O agente recebe um resultado de ferramenta de erro com o conteúdo Permission to use {tool_name} has been denied. e is_error: true. A sessão continua em execução, e seu cliente não pode substituir a negação.
• A chamada pausa para aguardar sua aprovação. Quando o servidor não chega a nenhuma determinação, a sessão pausa como faz sob always_ask. Consulte Responder a solicitações de confirmação.

Para ativar auto, defina permission_policy como {"type": "auto"}. Ela vai nos mesmos dois lugares que as outras políticas: no default_config de um conjunto de ferramentas, para todo o conjunto, ou em uma entrada de configs, para uma única ferramenta. Tanto o conjunto de ferramentas do agente quanto os conjuntos de ferramentas MCP a aceitam. Nenhum conjunto de ferramentas usa auto por padrão.

O exemplo a seguir define auto como padrão para o conjunto de ferramentas do agente e para o conjunto de ferramentas MCP github, e substitui a política de bash por always_ask:

ant apply agent.md

---
name: Ops Agent
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: auto
    configs:
      - name: bash
        permission_policy:
          type: always_ask
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: auto
---

O que você publica em eventos user.message conta como sua intenção, e isso pode levar o servidor a permitir uma chamada que, de outra forma, ele negaria. O servidor não lê intenção a partir de um resultado de ferramenta, de uma página web obtida, da resposta de um servidor MCP ou de uma mensagem entre threads de sessão. Ele avalia esse conteúdo, mas não recebe instruções dele. O servidor avalia algumas chamadas como de alto risco, não importa quem as solicite. Se você repassar entradas não confiáveis de usuários finais em eventos user.message, o servidor também lerá essa entrada como sua intenção, e ela pode fazer com que uma chamada seja permitida. Configure always_ask nas ferramentas que você não deixaria esse usuário final executar sem revisão.

Ver como cada chamada foi avaliada

Sob qualquer política de permissão, cada evento agent.tool_use e agent.mcp_tool_use contém evaluated_permission, o resultado da verificação de permissão da chamada: "allow", "ask" ou "deny". A maioria dos eventos também contém um objeto evaluation cujo type indica a política que produziu esse resultado. Sob auto, o objeto também registra a determinação do servidor, além de um reason_code quando o resultado é ask ou deny.

Por exemplo, quando bash está sob auto e o servidor avalia uma chamada como de alto risco, a chamada negada aparece no fluxo de eventos da seguinte forma:

{
  "type": "agent.tool_use",
  "id": "sevt_01pqr...",
  "name": "bash",
  "input": {
    "command": "rm -rf /workspace/reports"
  },
  "evaluated_permission": "deny",
  "evaluation": {
    "type": "auto",
    "evaluated_permission": {
      "type": "deny",
      "reason_code": "high_risk"
    }
  },
  "processed_at": "2026-03-25T14:05:12Z"
}

O objeto evaluation assume uma das formas da tabela a seguir.

Quando evaluation.type é "auto", seu evaluated_permission.type aninhado repete o evaluated_permission de nível superior do evento, então você pode ler o resultado em qualquer um dos campos. Um reason_code é um valor para o seu cliente usar em ramificações e manter em registros de auditoria, não um texto para exibir aos usuários finais.

evaluation está ausente em dois casos. Quando o agente nomeia uma ferramenta que não está habilitada na sessão, o servidor nega a chamada sem avaliar uma política: o evento contém evaluated_permission: "deny" e nenhum evaluation. Eventos registrados antes da introdução de evaluation também o omitem: interprete-os como always_allow quando evaluated_permission for "allow" e como always_ask quando for "ask".

Escreva seu cliente de modo que tolere um evaluation.type ou reason_code que ele não reconheça. Eventos agent.custom_tool_use não contêm nenhum dos dois campos, porque as políticas de permissão não regem ferramentas personalizadas.

Responder a solicitações de confirmação

Uma chamada de ferramenta é avaliada como ask sob uma política always_ask, ou sob auto quando o servidor não chega a nenhuma determinação. Quando isso acontece:

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.

Se você enviar um user.tool_confirmation para um evento cujo evaluated_permission não seja ask, a API o rejeita com um erro 400. Isso inclui chamadas que o servidor negou sob auto: seu cliente não pode substituí-las.

Para responder de forma interativa, use ant beta:sessions connect, que mostra a chamada em espera e envia esse evento quando você a permite ou nega. Consulte Conectar-se a uma sessão de Managed Agents a partir do seu terminal.

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.

# Permite 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 nega 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. Consulte Fluxo de eventos da sessão para ver o fluxo completo.

Próximos passos