Vercel Agent의 안전한 운영 접근 방식

Vercel Agent의 안전한 프로덕션 접근 방식

프로덕션 시스템에서 작업하는 에이전트는 행동할 권한이 필요합니다. “이 배포를 수정해 주세요” 같은 요청만으로는 어떤 작업을 할지, 어떤 접근 권한이 필요할지 미리 알 수 없습니다. 에이전트에 광범위한 접근 권한을 주면 실수로 관련 없는 리소스에 영향을 줄 수 있습니다. 매 단계마다 승인을 요청하면 사용자는 에이전트가 문제를 어떻게 해결하려는지 알기 전에 개별 작업을 승인해야 합니다. 반복되는 프롬프트는 그런 검토를 승인 버튼을 누르는 습관으로 바꿔 버릴 수 있습니다.

Vercel Agent는 먼저 문제를 조사한 다음, 무엇을 할지와 어떤 접근 권한이 필요한지를 보여 주는 계획을 제안합니다. 그 계획을 승인하면 실행에 필요한 추가 권한이 부여되므로, 사용자는 어떤 변경도 승인하기 전에 제안된 수정안을 검토할 수 있습니다.

계획이 권한을 결정합니다

프로덕션 배포가 실패한 경우, Vercel Agent는 최근 배포와 빌드 로그를 검사한 뒤 실패한 배포와 마지막으로 정상 작동했던 배포를 비교할 수 있습니다. 읽기 전용 접근 권한만으로도 이런 조사는 자동으로 실행됩니다. 만약 재배포 제안으로 이어지면, Vercel Agent는 사용자가 한 번의 결정으로 검토하고 승인할 수 있는 계획 안에서 추가 접근 권한을 요청합니다.

접근 권한은 범위(scope)로 정의되며, 이는 Vercel 권한 부여 시스템이 인식하는 이름 붙은 기능입니다. 읽기 전용 기준선(read-only baseline)을 넘어서는 접근 권한을 요청하는 계획은, 그 안에 포함된 읽기 전용 작업을 포함해 전체가 승인될 때까지 대기합니다. 이 예시에서는 Vercel Agent가 재배포를 제안하기 전에 별도의 읽기 전용 계획 아래에서 조사를 수행합니다:

작업 범위와 요청하는 scope를 보여 주는 예시 계획입니다.

짧은 읽기 전용 조회는 계획 없이 실행할 수 있습니다. 더 긴 조사의 경우, Vercel Agent는 읽기 전용 계획을 만들어 사용자가 작업과 진행 상황을 따라볼 수 있게 하며, 그동안 작업은 자동으로 실행됩니다.

계획은 사용자가 원하는 것과 Vercel Agent가 할 수 있는 일을 연결합니다:

• 의도(Intent): 사용자가 요청한 결과.
• 작업(Work): 이를 달성하기 위해 Vercel Agent가 제안하는 작업들.
• 접근(Access): 해당 작업에 필요한 scope.
• 강제(Enforcement): 접근 제한을 적용하는 자격 증명과 API 검사.

배포 요청이 권한이 포함된 계획으로 바뀌는 방식.

저장된 각 계획에는 작업과 진행 상황이 기록되며, 요청한 scope가 각 작업에 연결되어 있습니다. 작업 설명은 왜 접근 권한이 필요한지 설명하고, scope는 계획 전체에서 결합됩니다.

실패한 배포를 조사하고 재배포 승인을 받는 과정.

읽기 전용 기준선에는 현재 read:로 시작하는 등록된 모든 scope가 포함됩니다. 계획이 이 기준선을 넘어서는 접근 권한을 요청하거나 GitHub pull request 열기 같은 지원되는 외부 작업을 포함하면 승인이 필요합니다. 읽기 전용 작업도 민감한 정보를 노출할 수 있으므로, 자동 승인이 곧 작업이 무해하다는 뜻은 아닙니다.

Vercel Agent는 사용자가 이미 가진 권한만 사용할 수 있습니다

Vercel Agent는 Vercel App으로 실행되며, 사용자는 이를 자신의 대신 팀 내에서 행동하도록 승인합니다. 그 승인은 사용자의 기존 권한에 의해 제한되므로, 계획을 승인해도 사용자가 갖고 있지 않은 접근 권한은 부여할 수 없습니다.

Vercel OAuth 서비스는 해당 권한 부여를 더 짧은 수명의 토큰으로 교환하며, 이 토큰에는 특정 스코프가 부여됩니다. 이 스코프는 토큰이 허용하는 기능, 예를 들어 배포를 읽거나 프로젝트 설정을 변경하는 기능을 정의합니다. Vercel API는 각 요청마다 토큰을 확인해 이러한 제한을 강제합니다.

Vercel Agent가 승인된 작업에 사용할 토큰을 얻는 방식.

사용자는 수십 개의 프로젝트가 있는 팀에 대해 Vercel Agent를 승인할 수 있습니다. 재배포 계획은 배포 쓰기 접근 권한을 요청합니다. 환경 변수를 편집하고, 도메인을 변경하고, 팀 멤버십을 관리하는 작업은 각각 별도의 권한이 필요합니다.

배포 쓰기 접근 권한은 단일 재배포보다 더 넓습니다. 계획에서 배포 X를 지정한다고 해서, 그 자체만으로 토큰이 해당 배포에만 제한되는 것은 아닙니다. Vercel Agent의 실행을 조정하는 소프트웨어인 런타임은 승인된 자격 증명을 선택하기 전에 계획이 활성 상태인지 확인합니다. Vercel API는 각 요청을 해당 자격 증명의 권한과 대조해 확인합니다.

승인에 따라 Vercel Agent가 사용할 수 있는 권한이 결정됩니다

사용자가 추가 Vercel 접근이 필요한 계획을 승인하면, 요청된 스코프를 다시 확인한 뒤 읽기 전용 기본 권한과 승인된 권한을 포함한 토큰이 준비됩니다. Vercel Agent의 실행을 조정하는 소프트웨어인 런타임은 승인된 자격 증명을 선택하기 전에 계획이 활성 상태인지 확인합니다. 그 자격 증명은 여전히 해당 스코프, 팀, 사용자의 권한, 만료 시간의 적용을 받습니다.

사용되는 자격 증명은 작업에 따라 달라집니다:

Vercel Agent가 각 종류의 작업에서 사용하는 자격 증명.

모델의 지시사항은 언제 계획을 제안하고 승인을 요청해야 하는지 알려줍니다. 토큰의 권한 범위를 벗어난 작업을 시도하면, 모델이 그 작업이 작업 완료에 필요하다고 판단하더라도 Vercel API는 요청을 거부합니다.

하나의 계획에는 Vercel 변경 사항과 GitHub pull request가 함께 포함될 수 있습니다. 사용자는 하나의 계획에서 둘 다 검토하지만, 각 제공자는 별도의 권한과 자격 증명을 사용합니다. GitHub pull request 접근 권한은 소유자와 저장소에 연결되어 있으므로, acme/storefront에서 pull request를 열 수 있도록 승인하면 사용자가 acme/payments에도 접근 권한이 있더라도 그 승인은 해당 저장소에만 적용됩니다. 다른 저장소에서 pull request를 열려면 별도의 승인이 필요합니다.

계획과 토큰은 동일한 권한 정의를 사용합니다

제안된 계획은 이름이 변경되었거나 제거된 권한을 요청할 수 있습니다. 처음에는 Vercel Agent를 위해 별도의 권한 목록을 유지했는데, 이 목록이 토큰을 발급하는 OAuth 서비스와 어긋날 수 있었습니다. 이러한 불일치를 계획 단계에서 포착할 수 있도록 동일한 스코프 정의를 사용하도록 변경했습니다.

세션 설정 시 Vercel Agent는 Vercel scope registry에서 해당 정의를 메모리 내 카탈로그로 불러옵니다. registry를 가져오려면 팀에 대한 권한 부여가 필요하지만, scope 정의 자체는 팀 간에 공유됩니다. 이 카탈로그는 다음 세 단계에서 사용되는 정의를 제공합니다:

• 계획 검증: 요청된 스코프를 정규화하며, 알 수 없거나 잘못된 이름은 계획이 저장되거나 승인 검토용으로 제시되기 전에 거부됩니다.
• 승인: 요청된 스코프를 통해 계획이 읽기 전용 기본 권한 범위 안에 있는지, 아니면 추가 접근이 필요한지 결정합니다.
• 토큰 준비: 유효한 스코프가 승인된 작업에 사용할 자격 증명을 정의합니다.

유효한 권한이 어디에서 오고 어떻게 검사되는지.

예를 들어, 방화벽 규칙을 업데이트하는 작업이 오래된 범위를 요청할 수 있습니다. 시스템은 제안된 계획을 거부하고 유효한 범위를 반환하므로, Vercel Agent가 승인 요청 전에 이를 수정할 수 있습니다. 이렇게 하면 계획 단계에서 불일치를 잡아내고, 더 넓은 접근 권한으로의 대체 처리 대신 명시적인 수정을 요구합니다.

레지스트리를 가져오면 지연 시간이 늘고 서비스 의존성이 생기므로, Vercel Agent는 카탈로그를 캐시하고 그 복사본을 사용해 저장된 계획이 불러와질 때 검사합니다. 이러한 검사는 레지스트리의 변경 사항으로 카탈로그가 갱신되기 전까지 캐시된 정의를 반영합니다.

작업 재개에는 활성 상태의 승인된 계획이 필요합니다

Vercel Agent는 원래의 채팅 요청이 끝난 뒤에 승인을 받을 수도 있고, 승인된 재배포를 수행하기 전에 연결이 끊길 수도 있습니다. 저장된 계획에는 작업과 요청된 권한과 함께 상태, 승인자, 승인 시점이 포함됩니다. 이 기록은 제안된 작업을 사용자가 허용한 접근 권한과 연결하고, 작업이 재개될 때 승인이 유효한지 확인할 수 있게 합니다.

계획이 승인, 거부 또는 중지될 때 일어나는 일.

재개하기 전에 런타임은 계획을 다시 불러오고, 승인된 권한을 가진 자격 증명을 선택하기 전에 해당 계획이 활성 상태인지 확인합니다. 중지된 계획은 토큰의 만료 시간이 아직 남아 있어도 이 검사를 통과하지 못합니다.

승인과 중지 요청이 동시에 도착하면, 중지가 이미 상태를 바꾸지 않은 경우에만 계획은 승인 대기 상태에서 활성 상태로 전환될 수 있습니다. 그다음 런타임은 승인된 자격 증명을 사용하기 전에 계획이 활성 상태인지 다시 확인합니다.

조사 결과 현재 계획을 교체해야 한다면, Vercel Agent는 다른 계획을 제안할 수 있습니다. 더 높은 권한을 요청하는 교체 계획은 별도의 승인이 필요하므로, 사용자는 수정된 작업과 권한을 함께 검토할 기회를 갖게 됩니다.

더 정밀한 권한이 필요한 지점

Vercel Agent가 플랫폼의 더 많은 부분에 도달하면서, 여러 리소스를 포함하거나 결과가 서로 다른 작업에 대한 접근 규칙을 수정해야 했습니다. 도메인 연결은 도메인 권한과 프로젝트 권한을 모두 필요로 할 수 있고, 방화벽 규칙을 준비하는 것과 이를 게시하는 것은 서로 다른 수준의 접근 권한을 필요로 합니다. 범위는 각 계획의 접근 요청을 관리 가능하게 유지하면서 이러한 차이를 포착해야 합니다.

제안된 수정에 이 범위들을 맞추려면 계획 전반에서 주의가 필요합니다.

• 범위 선택: Vercel Agent는 불완전한 정보로 범위를 선택하므로, 너무 적은 권한을 요청해 작업이 막히거나, 너무 많은 권한을 요청해 작업에 필요한 것보다 더 큰 권한을 부여할 수 있습니다. 작업 수준의 지침은 선택을 돕고, 검증은 잘못된 범위 이름을 잡아냅니다. 유효한 범위라도 필요한 것보다 더 넓은 권한을 줄 수 있습니다.
• 작업 설명: “마지막으로 성공한 빌드를 재배포”는 사용자가 평가할 수 있는 구체적인 행동을 제시하지만, 범위 이름만으로는 그 결과를 스스로 추론해야 합니다. 계획은 의도한 변경을 설명하고 토큰이 실제로 어떤 제한을 강제하는지 분명히 해야 합니다.
• 거부 이해하기: 거부된 작업은 누락된 범위, 잘못된 리소스, 또는 여전히 차단되어야 할 작업을 의미할 수 있습니다. Vercel Agent는 추가 권한을 요청하기 전에 이러한 경우를 구분해야 합니다.

올바른 권한이 있어도, 재배포에는 선택된 커밋이 배포해도 안전한지 판단하는 결정이 필요합니다. 이는 애플리케이션, 실패 원인, 제안된 수정에 따라 달라집니다. 사용자는 선택을 평가할 만큼 충분한 정보를 가져야 하고, Vercel Agent는 여전히 이를 올바르게 실행해야 합니다.

읽기 전용 조사 역시 검색한 정보에 대한 통제가 필요합니다. 여기에는 민감한 프로젝트 구성 정보와 운영 세부 정보도 포함됩니다. 우리는 Vercel Agent가 승인 요청 전에 먼저 조사할 수 있도록 읽기 전용 기본값을 선택했으며, 권한 범위와 그 권한이 노출하는 정보가 바뀌면 그 선택도 계속 검토해야 합니다. 다른 시스템은 더 좁은 기본값이 필요할 수 있습니다. 검색된 정보를 어떻게 처리하고 어디로 보낼지에 대해서는 별도의 통제가 필요합니다.

Vercel Agent는 빌드 로그와 같은 읽는 콘텐츠에서 잘못된 결정을 내리거나 악의적인 지침을 마주할 수 있습니다. 범위가 제한된 자격 증명은 두 경우 모두에서 수행할 수 있는 작업을 제한하지만, 허용된 작업도 여전히 피해를 줄 수 있습니다. 따라서 플랜은 샌드박스 격리, 네트워크 정책, 비밀 정보 처리, 속도 제한, 감사 로그, 서비스 권한 부여와 함께 작동합니다. 에이전트형 아키텍처의 보안 경계에 관한 우리의 작업은 에이전트, 그 자격 증명, 그리고 실행하는 코드 사이의 분리를 설명합니다.

조사에서 승인된 작업으로

권한은 그것이 필요한 작업에 그대로 연결되어 있습니다. 런타임은 활성 플랜에 대해 승인된 자격 증명을 선택하며, 그 범위가 Vercel Agent가 수행할 수 있는 작업을 정의합니다. 이미 조사가 끝났기 때문에 사용자는 제안된 수정안과 요청된 접근 권한을 함께 검토할 수 있습니다.

프로젝트의 문제를 조사하려면 Vercel Agent를 사용해 보세요. 발견한 내용을 검토하고, 변경을 제안한다면 승인하기 전에 플랜과 요청된 접근 권한을 함께 평가하세요.

기여자

Ben Sabic, Kevin Corbett

출처

• 원문: https://vercel.com/blog/how-vercel-agent-accesses-production-safely (2026-10-23 · Tom Dale)