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

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

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

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-8
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-4-8
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. Полный поток описан в разделе Поток событий сессии.



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