Vercel Agent는 어떻게 프로덕션 환경에 안전하게 접근할까

프로덕션 시스템에서 일하는 에이전트에게는 작업을 수행할 권한이 필요합니다. 하지만 "이 배포 좀 고쳐 줘" 같은 요청만으로는 에이전트가 어떤 작업을 하고 어떤 접근 권한이 필요한지 미리 알 수 없습니다. 에이전트에게 넓은 권한을 주면 실수 하나가 관련 없는 리소스까지 영향을 줄 수 있습니다. 반대로 단계마다 승인을 요구하면 사용자는 에이전트가 문제를 어떻게 해결할지 모른 채 개별 작업을 승인해야 합니다. 이런 요청이 반복되면 검토는 형식적으로 승인 버튼만 누르는 습관이 되기 쉽습니다.

Vercel Agent는 먼저 문제를 조사한 다음, 어떤 작업을 하고 어떤 접근 권한이 필요한지 담은 계획을 제안합니다. 사용자가 이 계획을 승인하면 계획 실행에 필요한 추가 권한이 부여됩니다. 따라서 사용자는 변경을 허용하기 전에 제안된 해결 방안을 먼저 검토할 수 있습니다.

계획이 권한을 결정합니다

프로덕션 배포가 실패했다면 Vercel Agent는 최근 배포와 빌드 로그를 살펴보고, 실패한 배포를 마지막으로 정상 동작했던 배포와 비교할 수 있습니다. 읽기 전용 권한이면 이 조사를 자동으로 진행할 수 있습니다. 조사 결과 재배포가 필요하다고 판단하면, Vercel Agent는 추가로 필요한 권한을 계획에 담아 요청합니다. 사용자는 이 계획을 검토하고 한 번에 승인할 수 있습니다.

접근 권한은 스코프(scope)로 정의됩니다. 스코프는 Vercel 인증 시스템이 인식하는, 이름이 붙은 기능 단위입니다. 읽기 전용 기준선을 넘는 권한을 요청하는 계획은, 그 안에 읽기 전용 작업이 있더라도 계획 전체가 승인을 기다립니다. 이 예시에서는 Vercel Agent가 재배포를 제안하기 전에, 별도의 읽기 전용 계획으로 조사를 먼저 진행합니다.

짧은 읽기 전용 조회는 계획 없이도 실행할 수 있습니다. 조사가 길어지면 Vercel Agent는 읽기 전용 계획을 만듭니다. 이렇게 하면 작업이 자동으로 진행되는 동안에도 사용자가 각 작업과 진행 상황을 따라갈 수 있습니다.

계획은 사용자가 원하는 결과와 Vercel Agent에게 허용된 작업을 연결합니다.

• 의도: 사용자가 요청한 결과입니다.

• 작업: 그 결과를 달성하기 위해 Vercel Agent가 제안하는 작업입니다.

• 접근 권한: 해당 작업에 필요한 스코프입니다.

• 적용: 접근 제한을 강제하는 자격 증명과 API 검사입니다.

저장된 각 계획에는 작업과 진행 상황이 기록되고, 작업마다 요청한 스코프가 붙습니다. 작업 설명은 접근 권한이 왜 필요한지 설명하며, 스코프는 계획 전체 기준으로 합산됩니다.

현재 읽기 전용 기준선에는 read:로 시작하는 등록된 모든 스코프가 포함됩니다. 이 기준선을 넘는 접근 권한을 요청하거나 GitHub 풀 리퀘스트 생성처럼 지원되는 외부 작업이 포함된 계획은 승인이 필요합니다. 읽기 전용 작업도 민감한 정보를 노출할 수 있으므로, 자동 승인이 곧 작업이 무해하다는 뜻은 아닙니다.

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

Vercel Agent는 Vercel App으로 실행되며, 사용자는 팀 안에서 자신을 대신해 작업하도록 이 앱을 승인합니다. 이 승인은 사용자가 이미 가진 권한 범위로 제한되므로, 계획을 승인하더라도 사용자에게 없는 접근 권한이 생기지는 않습니다.

Vercel OAuth 서비스는 이 승인을 특정 스코프가 지정된, 수명이 더 짧은 토큰으로 교환합니다. 스코프는 배포 읽기나 프로젝트 설정 변경처럼 토큰이 허용하는 기능을 정의합니다. Vercel API는 요청이 올 때마다 토큰을 검사해 이 제한을 강제합니다.

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

배포 쓰기 권한은 단일 재배포보다 넓은 범위입니다. 계획에 배포 X를 명시했다고 해서 토큰이 그 배포로만 제한되는 것은 아닙니다. Vercel Agent의 실행을 조율하는 소프트웨어인 런타임은 승인된 자격 증명을 선택하기 전에 계획이 활성 상태인지 확인합니다. 그 뒤 Vercel API가 요청마다 해당 자격 증명의 권한에 맞는지 검사합니다.

승인이 Vercel Agent가 쓸 수 있는 권한을 결정합니다

사용자가 추가 Vercel 접근 권한이 필요한 계획을 승인하면, 요청된 스코프를 다시 검사하고 읽기 전용 기준선에 승인된 권한을 더한 토큰을 준비합니다. Vercel Agent의 실행을 조율하는 소프트웨어인 런타임은 승인된 자격 증명을 선택하기 전에 계획이 활성 상태인지 확인합니다. 이 자격 증명은 스코프, 팀, 사용자의 권한, 만료 시점의 제한을 계속 받습니다.

어떤 자격 증명을 쓰는지는 작업에 따라 달라집니다.

모델에게는 언제 계획을 제안하고 승인을 요청할지 지침이 주어집니다. 모델이 토큰의 권한을 벗어나는 작업을 시도하면, 작업을 완료하는 데 필요하다고 판단했더라도 Vercel API가 그 요청을 거부합니다.

하나의 계획에 Vercel 변경과 GitHub 풀 리퀘스트를 함께 담을 수도 있습니다. 사용자는 두 가지를 한 계획에서 검토하지만, 제공자마다 권한과 자격 증명은 따로 사용합니다. GitHub 풀 리퀘스트 권한은 소유자와 저장소에 묶여 있습니다. 따라서 acme/storefront에 풀 리퀘스트를 여는 것을 승인했다면 그 승인은 해당 저장소에만 적용되며, 사용자가 acme/payments에도 접근 권한이 있더라도 마찬가지입니다. 그곳에 풀 리퀘스트를 열려면 별도의 승인이 필요합니다.

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

제안된 계획이 이름이 바뀌었거나 삭제된 권한을 요청할 수 있습니다. 초기에는 Vercel Agent 전용 권한 목록을 따로 관리했는데, 이 목록이 토큰을 발급하는 OAuth 서비스와 어긋날 수 있었습니다. 그래서 같은 스코프 정의를 사용하도록 바꿔, 이런 불일치를 계획 단계에서 잡아낼 수 있게 했습니다.

Vercel Agent는 세션을 설정할 때 Vercel 스코프 레지스트리에서 이 정의를 불러와 메모리 내 카탈로그에 담습니다. 레지스트리를 가져오려면 팀에 대한 인증이 필요하지만, 스코프 정의 자체는 팀 간에 공유됩니다. 카탈로그가 제공하는 정의는 세 단계에서 쓰입니다.

• 계획 검증: 요청된 스코프를 정규화하고, 알 수 없거나 형식이 잘못된 이름은 계획을 저장하거나 승인 요청으로 보여 주기 전에 거부합니다.

• 승인: 요청된 스코프를 보고 계획이 읽기 전용 기준선 안에 들어가는지, 추가 접근 권한이 필요한지 판단합니다.

• 토큰 준비: 유효한 스코프가 승인된 작업에 쓸 자격 증명을 정의합니다.

예를 들어 방화벽 규칙을 업데이트하는 작업이 더 이상 쓰이지 않는 스코프를 요청할 수 있습니다. 이 경우 시스템은 제안된 계획을 거부하고 유효한 스코프를 알려 줍니다. Vercel Agent는 승인을 요청하기 전에 이를 바로잡을 수 있습니다. 이렇게 하면 불일치를 계획 단계에서 잡아내고, 더 넓은 권한으로 대체하는 대신 명시적인 수정을 거치게 됩니다.

레지스트리를 가져오는 일은 지연 시간을 늘리고 서비스 의존성을 만듭니다. 그래서 Vercel Agent는 카탈로그를 캐시해 두고, 저장된 계획을 불러올 때 이 사본으로 검사합니다. 따라서 이 검사에는 레지스트리의 변경 사항으로 카탈로그가 갱신되기 전까지는 캐시된 정의가 반영됩니다.

작업을 재개하려면 승인된 활성 계획이 필요합니다

원래 채팅 요청이 끝난 뒤에야 Vercel Agent가 승인을 받거나, 승인된 재배포를 실행하기 전에 연결이 끊길 수 있습니다. 저장된 계획에는 작업과 요청된 권한뿐 아니라 계획의 상태, 승인한 사람, 승인 시각도 들어 있습니다. 이 기록은 제안된 작업을 사용자가 승인한 접근 권한과 연결하며, 작업을 재개할 때 승인 여부를 확인할 수 있게 해 줍니다.

런타임은 작업을 재개하기 전에 계획을 다시 불러와 활성 상태인지 확인한 뒤, 승인된 권한이 담긴 자격 증명을 선택합니다. 중단된 계획은 토큰의 만료 시점이 남아 있어도 이 검사를 통과하지 못합니다.

승인과 중단 요청이 동시에 들어오면, 중단 요청이 아직 상태를 바꾸지 않았을 때만 계획이 승인 대기 상태에서 활성 상태로 넘어갈 수 있습니다. 그 뒤 런타임은 승인된 자격 증명을 쓰기 전에 계획이 활성 상태인지 다시 확인합니다.

조사 결과 현재 계획을 교체해야 한다고 드러나면 Vercel Agent는 다른 계획을 제안할 수 있습니다. 상향된 접근 권한을 요청하는 대체 계획은 별도의 승인이 필요합니다. 덕분에 사용자는 수정된 작업과 권한을 함께 검토할 수 있습니다.

권한을 더 정밀하게 다뤄야 하는 부분

Vercel Agent가 플랫폼의 더 많은 영역을 다루게 되면서, 여러 리소스가 얽힌 작업이나 결과가 서로 다른 작업의 접근 규칙을 바로잡아야 했습니다. 도메인을 연결하려면 도메인과 프로젝트 권한이 둘 다 필요할 수 있고, 방화벽 규칙을 스테이징하는 것과 게시하는 것은 필요한 권한 수준이 다릅니다. 스코프는 이런 차이를 담아내면서도 계획마다 접근 권한 요청이 관리 가능한 수준에 머물러야 합니다.

이런 스코프를 제안된 해결 방안에 맞추려면 계획 전반에 걸쳐 신중해야 합니다.

• 스코프 선택: Vercel Agent는 불완전한 정보로 스코프를 고르기 때문에, 너무 적은 권한을 요청해 작업이 막히거나 너무 많은 권한을 요청해 작업에 필요 이상의 권한을 줄 수 있습니다. 작업 단위 가이드가 선택을 돕고, 검증이 잘못된 스코프 이름을 걸러냅니다. 하지만 유효한 스코프라도 필요 이상으로 넓은 접근 권한을 줄 수 있습니다.

• 작업 설명: "마지막으로 성공한 빌드를 재배포"처럼 쓰면 사용자는 구체적인 작업을 보고 판단할 수 있습니다. 스코프 이름만 있으면 그 결과가 어떨지 사용자가 직접 짐작해야 합니다. 계획은 의도한 변경 내용을 설명하고, 토큰이 실제로 강제하는 제한이 무엇인지 분명히 밝혀야 합니다.

• 거부 상황 이해: 작업이 거부되는 이유는 스코프 누락, 잘못된 리소스, 계속 막아 두어야 할 작업 중 하나일 수 있습니다. Vercel Agent는 추가 권한을 요청하기 전에 이 경우들을 구분해야 합니다.

권한이 정확하더라도, 선택한 커밋을 배포해도 안전한지는 별도로 판단해야 합니다. 이는 애플리케이션, 장애 내용, 제안된 수정안에 따라 달라집니다. 사용자는 이 선택을 평가할 충분한 정보를 받아야 하고, Vercel Agent는 여전히 그 작업을 올바르게 실행해야 합니다.

읽기 전용 조사에도 조회한 정보에 대한 통제가 필요합니다. 민감한 프로젝트 설정이나 운영 세부 정보가 여기에 포함됩니다. Vercel Agent가 승인을 요청하기 전에 조사할 수 있도록 읽기 전용 기준선을 택했으며, 이 선택은 스코프와 그 스코프가 노출하는 정보가 바뀜에 따라 계속 검토해야 합니다. 시스템에 따라서는 더 좁은 기준선이 필요할 수도 있습니다. 조회한 정보를 어떻게 처리하고 어디로 보낼 수 있는지는 별도의 통제로 관리해야 합니다.

Vercel Agent가 잘못된 판단을 내리거나, 빌드 로그처럼 읽어 들인 콘텐츠에서 악의적인 지시를 만날 수도 있습니다. 범위가 제한된 자격 증명은 어느 경우든 수행할 수 있는 작업을 제한하지만, 허용된 작업이 해를 끼칠 가능성은 여전히 있습니다. 그래서 계획은 샌드박스 격리, 네트워크 정책, 시크릿 처리, 속도 제한, 감사 로그, 서비스 인가와 함께 작동합니다. 에이전트 아키텍처의 보안 경계에 관한 글에서는 에이전트, 에이전트의 자격 증명, 에이전트가 실행하는 코드를 분리하는 방식을 설명합니다.

조사에서 승인된 작업까지

권한은 그 권한이 필요했던 작업에 묶여 있습니다. 런타임은 활성 계획에 대해 승인된 자격 증명을 선택하며, 그 자격 증명의 스코프가 Vercel Agent가 수행할 수 있는 작업을 정의합니다. 조사가 이미 끝난 상태이므로, 사용자는 제안된 해결 방안과 요청된 접근 권한을 함께 평가할 수 있습니다.

Vercel Agent로 프로젝트의 이슈를 조사해 보세요. 조사 결과를 살펴보고, 변경을 제안하면 승인하기 전에 계획과 요청된 접근 권한을 검토하세요.

기여자