Агент, работающий с продакшен-системами, нуждается в разрешении на действия. Запрос вроде «исправь этот деплой» не позволяет заранее понять, какие именно действия он предпримет и какой доступ ему потребуется. Если предоставить агентам широкий доступ, одна ошибка может затронуть несвязанные ресурсы. Если же запрашивать одобрение на каждом шаге, пользователю придется подтверждать отдельные действия еще до того, как он поймет, как именно агент собирается решить проблему. Повторяющиеся запросы могут превратить такую проверку в механическое нажатие кнопки «одобрить».
Vercel Agent начинает с исследования проблемы, после чего предлагает план, в котором указано, что он собирается сделать и какой доступ для этого потребуется. Одобрение этого плана предоставляет дополнительные разрешения для его выполнения, поэтому пользователь может изучить предлагаемое исправление перед тем, как санкционировать любые изменения.
Copy link to headingПлан определяет права доступа
Для устранения сбоя деплоя в продакшене Vercel Agent может изучить недавние деплои и логи сборки, а затем сравнить упавший деплой с последней известной рабочей версией. Доступ только для чтения позволяет запустить это исследование автоматически. Если оно приводит к предложению повторного деплоя, Vercel Agent запрашивает дополнительный доступ в виде плана, который пользователь может изучить и одобрить одним решением.
Доступ определяется областями (scopes) — поименованными возможностями, которые распознает система авторизации Vercel. Любой план, запрашивающий доступ сверх базового уровня «только для чтения», ожидает одобрения целиком, включая все содержащиеся в нем задачи чтения. В этом примере исследование выполняется в рамках отдельного плана только для чтения, прежде чем Vercel Agent предложит повторный деплой:
План
Работа
Запрошенная область доступа
Исследовать сбой
Изучить недавние деплои и логи сборки, а затем сравнить упавший деплой с последним успешным
read:deployment
Повторно развернуть последнюю известную рабочую сборку
Создать деплой
read-write:deployment
Примеры планов с охватываемой ими работой и запрашиваемыми областями доступа.
Короткий поиск в режиме только для чтения может выполняться без плана. Для более длительных исследований Vercel Agent создает план только для чтения, чтобы пользователь мог следить за его задачами и прогрессом в ходе автоматического выполнения.
План связывает то, что хочет сделать пользователь, с тем, что разрешено делать Vercel Agent:
- Намерение: результат, о котором просит пользователь.
Намерение: результат, о котором просит пользователь.
- Работа: задачи, которые Vercel Agent предлагает для достижения этого результата.
Работа: задачи, которые Vercel Agent предлагает для достижения этого результата.
- Доступ: области, необходимые для выполнения этих задач.
Доступ: области, необходимые для выполнения этих задач.
- Принудительное применение: учетные данные и проверки API, ограничивающие доступ.
Принудительное применение: учетные данные и проверки API, ограничивающие доступ.
Каждый сохраненный план фиксирует свои задачи и ход выполнения, причем к каждой задаче привязаны запрошенные области доступа. Описания задач объясняют, почему требуется доступ, а области объединяются по всему плану.
Базовый уровень только для чтения в настоящее время включает каждую зарегистрированную область, начинающуюся с read:. Планам требуется одобрение, если они запрашивают доступ за пределами этого базового уровня или включают поддерживаемые внешние действия, такие как открытие пулл-реквеста на GitHub. Операции только для чтения все равно могут раскрывать конфиденциальную информацию, поэтому автоматическое одобрение не означает, что работа полностью безопасна.
Copy link to headingVercel Agent может использовать только те разрешения, которые уже есть у пользователя
Vercel Agent работает как приложение Vercel App, которое пользователь уполномочивает действовать от своего имени в рамках команды. Эта авторизация ограничена существующими разрешениями пользователя, поэтому одобрение плана не может предоставить доступ, которого у пользователя нет.
Служба OAuth от Vercel обменивает эту авторизацию на токены с меньшим сроком действия и специфическими областями применения. Эти области определяют, какие возможности разрешает токен, например чтение деплоев или изменение настроек проекта. API Vercel проверяют токен при каждом запросе для соблюдения этих ограничений.
Пользователь может авторизовать Vercel Agent для команды, у которой есть десятки проектов. План повторного деплоя запрашивает доступ на запись для деплоев. Редактирование переменных окружения, изменение доменов и управление членством в команде требуют собственных разрешений.
Доступ на запись для деплоев шире, чем один конкретный повторный деплой. Упоминание деплоя X в плане само по себе не ограничивает токен только этим деплоем. Среда выполнения (программное обеспечение, координирующее выполнение Vercel Agent) проверяет, активен ли план, перед тем как выбрать утвержденные учетные данные. API Vercel проверяют каждый запрос на соответствие разрешениям этих учетных данных.
Copy link to headingОдобрение определяет, какие разрешения может использовать Vercel Agent
Когда пользователь одобряет план, требующий дополнительного доступа к Vercel, запрошенные им области проверяются повторно, и подготавливается токен, содержащий базовый уровень только для чтения плюс одобренные разрешения. Среда выполнения (программное обеспечение, координирующее выполнение Vercel Agent) проверяет, активен ли план, перед тем как выбрать утвержденные учетные данные. Эти учетные данные по-прежнему подчиняются своим областям, команде, разрешениям пользователя и сроку действия.
Используемые учетные данные зависят от выполняемой работы:
Работа
Учетные данные
Исследование в режиме только для чтения
Базовый токен с областями только для чтения
Одобренные изменения в Vercel
Токен с базовыми областями плюс одобренные дополнительные области
Внешние действия
Учетные данные и разрешения, специфичные для этого провайдера
Какие учетные данные Vercel Agent использует для каждого типа работы.
Инструкции модели сообщают ей, когда следует предложить план и запросить одобрение. Если она пытается выполнить операцию вне разрешений токена, API Vercel отклоняют запрос, даже если модель считает это действие необходимым для завершения задачи.
Один план может включать изменения в Vercel и пулл-реквест на GitHub. Пользователь проверяет и то, и другое в рамках одного плана, в то время как каждый провайдер использует раздельные разрешения и учетные данные. Доступ к пулл-реквестам GitHub привязан к владельцу и репозиторию, поэтому одобрение на открытие пулл-реквеста в acme/storefront применяется к этому репозиторию, даже если у пользователя также есть доступ к acme/payments. Открытие пулл-реквеста там потребует отдельного одобрения.
Copy link to headingПланы и токены используют одинаковые определения разрешений
Предлагаемый план может запрашивать разрешение, которое было переименовано или удалено. Изначально мы поддерживали отдельный список разрешений для Vercel Agent, который мог рассинхронизироваться со службой OAuth, выпускающей его токены. Мы перешли на те же определения областей, чтобы такие несоответствия можно было выявлять на этапе планирования.
При настройке сеанса Vercel Agent загружает эти определения из реестра областей Vercel в каталог, хранящийся в памяти. Получение реестра требует авторизации для команды, в то время как сами определения областей являются общими для всех команд. Каталог предоставляет определения, используемые на трех этапах:
- Проверка плана: запрошенные области нормализуются, а неизвестные или некорректные имена отклоняются до того, как план будет сохранен или представлен на одобрение.
Проверка плана: запрошенные области нормализуются, а неизвестные или некорректные имена отклоняются до того, как план будет сохранен или представлен на одобрение.
- Одобрение: запрошенные области определяют, укладывается ли план в базовый уровень только для чтения или требует дополнительного доступа.
Одобрение: запрошенные области определяют, укладывается ли план в базовый уровень только для чтения или требует дополнительного доступа.
- Подготовка токена: действительные области определяют учетные данные для одобренной работы.
Подготовка токена: Действующие области определяют учетные данные для одобренной работы.
Например, задача по обновлению правил брандмауэра может запрашивать устаревшую область. Система отклоняет предложенный план и возвращает действующие области, чтобы Vercel Agent мог исправить их перед запросом одобрения. Это позволяет выявить несоответствие на этапе планирования и требует явного исправления вместо отката к расширенному доступу.
Получение реестра увеличивает задержку и создает зависимость от службы, поэтому Vercel Agent кэширует каталог и использует эту копию для проверки сохраненных планов при их загрузке. Эти проверки отражают кэшированные определения до тех пор, пока каталог не будет обновлен изменениями из реестра.
Copy link to headingВозобновление работы требует активного, одобренного плана
Vercel Agent может получить одобрение после завершения исходного запроса чата или потерять соединение перед выполнением одобренного повторного развертывания. Сохраненный план включает свое состояние, информацию о том, кто и когда его одобрил, а также задачи и запрошенные разрешения. Эта запись связывает предполагаемую работу с доступом, который авторизовал пользователь, и позволяет проверить одобрение при возобновлении работы.
Перед возобновлением среда выполнения перезагружает план и проверяет, что он активен, прежде чем выбрать учетные данные с одобренными разрешениями. Остановленный план не проходит эту проверку, даже если у его токена осталось время до истечения срока действия.
Если одобрение и запрос на остановку поступают одновременно, план может перейти из состояния ожидания одобрения в активное состояние только в том случае, если остановка еще не изменила его статус. Затем среда выполнения повторно проверяет, что план активен, перед использованием одобренных учетных данных.
Если расследование показывает, что текущий план нуждается в замене, Vercel Agent может предложить другой. Замена, запрашивающая повышенный доступ, требует собственного одобрения, что дает пользователю возможность рассмотреть измененную работу и разрешения вместе.
Copy link to headingГде разрешения требуют большей точности
По мере того как Vercel Agent получал доступ к большей части платформы, нам приходилось корректировать правила доступа для действий, которые затрагивают несколько ресурсов или имеют разные последствия. Подключение домена может требовать разрешений как для домена, так и для проекта, в то время как подготовка правила брандмауэра и его публикация требуют разных уровней доступа. Области должны отражать эти различия, сохраняя при этом управляемость запроса доступа для каждого плана.
Сопоставление этих областей с предложенным исправлением требует внимательности на протяжении всего планирования:
- Выбор областей: Vercel Agent выбирает области с неполной информацией, поэтому он может запросить слишком мало доступа и оставить задачу заблокированной или слишком много и предоставить больше полномочий, чем требуется для работы. Рекомендации на уровне задач помогают ему сделать выбор, в то время как валидация выявляет недействительные имена областей. Даже действительная область может предоставить более широкий доступ, чем необходимо.
Выбор областей: Vercel Agent выбирает области с неполной информацией, поэтому он может запросить слишком мало доступа и оставить задачу заблокированной или слишком много и предоставить больше полномочий, чем требуется для работы. Рекомендации на уровне задач помогают ему сделать выбор, в то время как валидация выявляет недействительные имена областей. Даже действительная область может предоставить более широкий доступ, чем необходимо.
- Описание работы: «Повторно развернуть последнюю успешную сборку» дает пользователю конкретное действие для оценки, в то время как одни только имена областей оставляют им задачу самостоятельного определения последствий. План должен объяснять предполагаемое изменение и четко указывать, какие ограничения фактически накладывает токен.
Описание работы: «Повторно развернуть последнюю успешную сборку» дает пользователю конкретное действие для оценки, в то время как одни только имена областей оставляют им задачу самостоятельного определения последствий. План должен объяснять предполагаемое изменение и четко указывать, какие ограничения фактически накладывает токен.
- Понимание отказов: Отклоненная операция может указывать на отсутствующую область, неверный ресурс или операцию, которая должна оставаться заблокированной. Vercel Agent должен различать эти случаи перед запросом дополнительных разрешений.
Понимание отказов: Отклоненная операция может указывать на отсутствующую область, неверный ресурс или операцию, которая должна оставаться заблокирована. Vercel Agent должен различать эти случаи перед запросом дополнительных разрешений.
Даже при наличии правильных разрешений повторное развертывание требует оценки того, безопасно ли выпускать выбранный коммит. Это зависит от приложения, сбоя и предложенного исправления. Пользователю нужна достаточная информация для оценки выбора, а Vercel Agent все равно должен выполнить его правильно.
Исследование в режиме «только чтение» также нуждается в средствах контроля извлекаемой информации, включая конфиденциальную конфигурацию проекта и операционные детали. Мы выбрали базовый уровень только для чтения, чтобы Vercel Agent мог провести расследование перед запросом одобрения, и этот выбор нуждается в постоянном пересмотре по мере изменения областей и информации, которую они раскрывают. Другим системам может потребоваться более узкий базовый уровень. Отдельные средства контроля должны регулировать обработку извлеченной информации и направления ее передачи.
Vercel Agent может принять неверное решение или столкнуться с вредоносными инструкциями в прочитанном контенте, таком как журналы сборки. Учетные данные с ограниченными областями ограничивают операции, которые он может выполнять в любом случае, но разрешенные операции все равно могут нанести вред. Поэтому планы работают в сочетании с песочницей, сетевыми политиками, обработкой секретов, ограничениями частоты запросов, журналами аудита и авторизацией служб. Наша работа по обеспечению безопасности границ в агентских архитектурах объясняет разделение между агентом, его учетными данными и исполняемым им кодом.
Copy link to headingОт расследования к одобренному действию
Полномочия остаются привязанными к работе, которая их потребовала. Среда выполнения выбирает одобренные учетные данные для активного плана, а его области определяют операции, которые может выполнять Vercel Agent. Поскольку расследование уже проведено, пользователь может одновременно оценить предложенное исправление и запрошенный доступ.
Попробуйте Vercel Agent для расследования проблемы в вашем проекте. Ознакомьтесь с результатами и, если он предлагает изменение, оцените план и запрашиваемый доступ перед его утверждением.
