Политики разрешений

Политики разрешений управляют тем, выполняются ли инструменты, исполняемые на сервере (предварительно созданный набор инструментов агента и набор инструментов MCP), автоматически или ожидают вашего одобрения. Пользовательские инструменты выполняются вашим приложением и контролируются вами, поэтому они не регулируются политиками разрешений.



Типы политик разрешений

Каждый вид набора инструментов имеет своё значение по умолчанию: набор инструментов агента по умолчанию использует always_allow, а наборы инструментов MCP по умолчанию используют always_ask.

Политика разрешений управляет тем, когда запускается включённый инструмент. Чтобы полностью удалить инструмент из агента, вместо этого отключите его. См. Отключение определённых инструментов.



Установка политики для набора инструментов

Вы устанавливаете политики разрешений в конфигурации tools агента при создании агента и можете изменить их позже, обновив агента. Запущенные сессии сохраняют конфигурацию набора инструментов, с которой они были созданы. Обновления применяются к сессиям, созданным после этого.



Разрешения набора инструментов агента

При создании агента вы можете применить политику к каждому инструменту в agent_toolset_20260401, используя default_config.permission_policy:

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

default_config является необязательным. Если вы его опустите, набор инструментов агента будет включён с политикой разрешений по умолчанию, always_allow.



Разрешения набора инструментов MCP

Наборы инструментов MCP по умолчанию используют always_ask. Это гарантирует, что новые инструменты, добавленные на сервер MCP, не будут выполняться в вашем приложении без одобрения. Чтобы автоматически одобрять инструменты с доверенного сервера MCP, установите default_config.permission_policy в записи mcp_toolset.

Значение mcp_server_name должно совпадать с name сервера в массиве mcp_servers.

Этот пример подключает сервер GitHub MCP и позволяет его инструментам работать без подтверждения:

ant beta:agents create <<'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
YAML



Переопределение политики отдельного инструмента

Используйте массив configs, чтобы переопределить значение по умолчанию для отдельных инструментов. Значения name для набора инструментов агента перечислены в разделе Доступные инструменты. Этот пример разрешает полный набор инструментов агента по умолчанию, но требует подтверждения перед запуском любой команды 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

Передайте эту конфигурацию tools в запросе на создание агента (вкладка CLI показывает полную команду). Наборы инструментов MCP поддерживают те же переопределения для отдельных инструментов, где name устанавливается в имя инструмента, сообщаемое сервером MCP. См. Настройка доступных инструментов MCP.



Ответ на запросы подтверждения

Когда агент вызывает инструмент с политикой always_ask:

1. Сессия генерирует событие agent.tool_use или agent.mcp_tool_use.
2. Сессия приостанавливается с событием session.status_idle, у которого stop_reason.type равен requires_action. Идентификаторы блокирующих событий находятся в массиве stop_reason.event_ids. Сессия ожидает ответа неограниченное время.
3. Отправьте событие user.tool_confirmation для каждого блокирующего события, передав идентификатор события в параметре tool_use_id. Установите result в значение "allow" или "deny". Используйте deny_message, чтобы объяснить отказ. Вы можете отправить несколько подтверждений в одном запросе events.
4. Как только все блокирующие события разрешены, сессия переходит обратно в состояние running. Разрешённые инструменты выполняются. Отклонённые инструменты не запускаются, и агент получает результат инструмента, сообщающий, что вызов был отклонён, включая ваше deny_message.

В следующих примерах идентификаторы событий использования инструментов берутся из массива stop_reason.event_ids события session.status_idle. Узнайте больше о получении событий в руководстве Поток событий сессии или подпишитесь на вебхуки, чтобы получать уведомления, когда сессия приостанавливается в ожидании ввода.

# Разрешить выполнение инструмента
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# Или отклонить его с объяснением
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.}"



Пользовательские инструменты

Политики разрешений не применяются к пользовательским инструментам. Когда агент вызывает пользовательский инструмент, ваше приложение получает событие agent.custom_tool_use и отвечает за принятие решения о его выполнении перед отправкой обратно user.custom_tool_result. См. Поток событий сессии для ознакомления с полным процессом.



Следующие шаги