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

«Permission policies» (политики разрешений) определяют, будут ли инструменты, выполняемые на сервере (готовый «agent toolset» (набор инструментов агента) и набор инструментов «Model Context Protocol», или MCP), запускаться автоматически, ожидать вашего одобрения или проходить оценку сервером при каждом вызове. Пользовательские инструменты выполняются вашим приложением и контролируются вами, поэтому политики разрешений на них не распространяются.

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

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

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

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

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

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

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

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

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

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

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

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
---

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

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

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

Оценка каждого вызова сервером с помощью auto

При политике разрешений auto сервер оценивает каждый вызов перед его выполнением. Поскольку при оценке учитываются инструмент, входные данные вызова и содержимое сессии на этот момент, сервер может по-разному обработать два вызова одного и того же инструмента. У каждого вызова один из трёх исходов:

• Вызов выполняется. Если сервер определяет, что вызов безопасен, инструмент выполняется так же, как при always_allow.
• Вызов отклоняется. Если сервер оценивает вызов как высокорисковый, инструмент не выполняется. Агент получает «tool result» (результат инструмента) с ошибкой, содержащий Permission to use {tool_name} has been denied. и is_error: true. Сессия продолжает работу, и ваш клиент не может отменить это отклонение.
• Вызов приостанавливается до вашего одобрения. Если сервер не приходит к определённому решению, сессия приостанавливается так же, как при always_ask. См. Ответ на запросы подтверждения.

Чтобы включить auto, задайте для permission_policy значение {"type": "auto"}. Оно указывается в тех же двух местах, что и другие политики: в default_config набора инструментов — для всего набора, или в записи configs — для одного инструмента. Его принимают как набор инструментов агента, так и наборы инструментов MCP. Ни один набор инструментов не использует auto по умолчанию.

В следующем примере auto задаётся по умолчанию для набора инструментов агента и для набора инструментов MCP github, а для bash переопределяется на 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
---

То, что вы отправляете в событиях user.message, считается вашим намерением и может привести к тому, что сервер разрешит вызов, который в противном случае отклонил бы. Сервер не считывает намерение из результата инструмента, загруженной веб-страницы, ответа MCP-сервера или сообщения между потоками сессии. Он оценивает это содержимое, но не принимает из него инструкций. Некоторые вызовы сервер оценивает как высокорисковые независимо от того, кто их запрашивает. Если вы передаёте в событиях user.message недоверенные входные данные конечного пользователя, сервер также воспринимает их как ваше намерение, и это может привести к разрешению вызова. Настройте always_ask для тех инструментов, которые вы не позволили бы этому конечному пользователю запускать без проверки.

Просмотр результатов оценки каждого вызова

При любой политике разрешений каждое событие agent.tool_use и agent.mcp_tool_use содержит evaluated_permission — результат проверки разрешений для вызова: "allow", "ask" или "deny". Большинство событий также содержат объект evaluation, поле type которого указывает политику, давшую этот результат. При auto объект также фиксирует решение сервера, а если результат — ask или deny, то и reason_code.

Например, если для bash задана политика auto и сервер оценивает вызов как высокорисковый, отклонённый вызов появляется в потоке событий следующим образом:

{
  "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"
}

Объект evaluation принимает одну из форм, приведённых в следующей таблице.

Когда evaluation.type равно "auto", вложенное поле evaluated_permission.type повторяет evaluated_permission верхнего уровня события, поэтому результат можно прочитать из любого из этих полей. reason_code — это значение, по которому ваш клиент может выбирать ветку логики и которое стоит сохранять в журналах аудита, а не текст для показа конечным пользователям.

evaluation отсутствует в двух случаях. Если агент указывает инструмент, не включённый в сессии, сервер отклоняет вызов без оценки политики: событие содержит evaluated_permission: "deny" и не содержит evaluation. События, записанные до появления evaluation, также не содержат его: интерпретируйте их как always_allow, если evaluated_permission равно "allow", и как always_ask, если оно равно "ask".

Пишите клиент так, чтобы он корректно обрабатывал нераспознанные значения evaluation.type или reason_code. События agent.custom_tool_use не содержат ни одного из этих полей, поскольку политики разрешений не распространяются на пользовательские инструменты.

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

Вызов инструмента получает результат ask при политике always_ask или при auto, если сервер не пришёл к определённому решению. В этом случае:

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.

Если вы отправите user.tool_confirmation для события, у которого evaluated_permission не равно ask, API отклонит его с ошибкой 400. Это касается и вызовов, отклонённых сервером при auto: ваш клиент не может их переопределить.

Чтобы отвечать в интерактивном режиме, используйте ant beta:sessions connect — эта команда показывает ожидающий вызов и отправляет это событие, когда вы разрешаете или отклоняете его. См. Подключение к сессии Managed Agents из терминала.

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

# Разрешить выполнение инструмента
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

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

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

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

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