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

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



Дальнейшие шаги