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

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



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

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

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



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

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



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

При создании агента вы можете применить политику ко всем инструментам в agent_toolset_20260401 с помощью 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 необязателен. Если его опустить, набор инструментов агента будет включён с политикой разрешений по умолчанию — always_allow.



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

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

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

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

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



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

Используйте массив 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. Полная последовательность описана в разделе Поток событий сессии.



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