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

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

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

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

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

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

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

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

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

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

mcp_server_name должно совпадать с name, на которое ссылается массив mcp_servers.

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

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-7
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 для переопределения значения по умолчанию для отдельных инструментов. Этот пример позволяет полному набору инструментов агента работать по умолчанию, но требует подтверждения перед выполнением любой команды bash:

tools = [
    {
        "type": "agent_toolset_20260401",
        "default_config": {
            "permission_policy": {"type": "always_allow"},
        },
        "configs": [
            {
                "name": "bash",
                "permission_policy": {"type": "always_ask"},
            },
        ],
    },
]

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

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

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

Узнайте больше об обработке событий в руководстве поток событий сеанса.

# Allow the tool to execute
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Or deny it with an explanation
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. Полный процесс см. в разделе Поток событий сеанса.