에이전트에 도구 붙이는 게 왜 이렇게 귀찮았을까
에이전트 개발하다 보면 제일 지치는 순간이 있어요. 모델은 똑똑한데, 도구 하나 붙일 때마다 인증 토큰 발급하고, 권한 스코프 정하고, 위험한 호출엔 승인 게이트 달고... 이거 다 수동으로 하다 보면 에이전트 로직 짤 시간이 사라집니다.
Vercel이 공개한 @github-tools/eve-extension은 이 반복 작업을 설정 파일 한 개로 압축한 시도예요. 패키지 설치하고, agent/extensions/ 디렉터리에 파일 하나 떨어뜨리면 GitHub 도구 세트가 통째로 에이전트에 붙습니다.
핵심은 이거예요. 도구 등록, 인증, 권한 스코프, 승인 규칙이 전부 하나의 선언적 설정으로 묶인다는 점. 이건 단순한 편의 기능이 아니라, 에이전트가 어떤 권한으로 무엇을 할 수 있는지를 코드 리뷰 가능한 형태로 남기는 구조적 변화입니다. 실제 배포 리스크 관리 관점은 AI가 생성한 코드, 그대로 배포하면 생기는 재앙과 Vercel의 해법에서 더 깊게 다뤘어요.
근거자료: Vercel Changelog - GitHub tools eve extension
설치와 등록, 딱 두 단계
먼저 패키지를 추가합니다.
# 패키지 설치
pnpm add @github-tools/eve-extension
그 다음 agent/extensions/ 안에 파일을 하나 만들고 확장을 등록하세요.
// agent/extensions/github.ts
import githubExtension from '@github-tools/eve-extension'
export default githubExtension({
// Vercel Connect 커넥터 지정 (런타임에 단기 스코프 토큰 발급)
connector: 'github/my-connector',
// code-review 프리셋이 필요한 스코프를 자동 매핑
preset: 'code-review',
// 쓰기 도구별 승인 규칙: 조건부 predicate도 가능
requireApproval: {
// 내 조직 외부에 코멘트 달 때만 승인 요구
addPullRequestComment: ({ toolInput }) => toolInput?.owner !== 'vercel-labs',
},
})
이 파일 하나로 code-review 툴셋 전체가 등록됩니다. 파일명이 곧 네임스페이스가 돼서, 에이전트 안에서는 github__addPullRequestComment 같은 이름으로 도구가 노출돼요. 패키지를 업그레이드하면 새 도구와 수정사항이 자동으로 따라오고, 설정 스키마는 import 시점에 검증됩니다.
프리셋이 스코프를 대신 정해준다
여기가 실무에서 제일 반가운 부분이에요. 프리셋마다 필요한 Connect 스코프가 미리 매핑돼 있어서, 토큰이 딱 필요한 권한만 들고 다닙니다.
| 프리셋 | 용도 |
|---|---|
code-review | PR 리뷰, 코멘트, 코드 검토 |
issue-triage | 이슈 분류, 라벨링 |
repo-explorer | 레포 구조 탐색, 파일 조회 |
ci-ops | CI 파이프라인 조작 |
maintainer | 유지보수자 수준의 관리 작업 |
connector에 Vercel Connect 커넥터를 넘기면, 확장이 런타임에 단기 수명의 스코프 제한 GitHub 토큰을 발급받아요. 장기 토큰을 코드에 박아두는 안티패턴이 여기서 사라집니다.
승인 규칙은 설정과 함께 다닌다
에이전트가 진짜 무서운 지점은 쓰기 동작이에요. 읽기는 뭐가 잘못돼도 데이터가 안 변하지만, 코멘트 달고 PR 올리고 이슈 닫는 건 되돌리기 비쌉니다.
이 확장은 모든 쓰기 도구에 기본적으로 승인을 요구합니다. 그리고 세 가지 방식으로 게이트를 세밀하게 조절할 수 있어요.
always: 매번 사람 승인once: 세션당 한 번만 승인- predicate 함수: 입력값에 따라 조건부 승인 (예: 자기 조직 외부에 코멘트할 때만)
위 예제 코드에서 addPullRequestComment에 걸린 predicate가 바로 그 케이스예요. toolInput?.owner !== 'vercel-labs' 조건이 참일 때만 승인을 요구하니, 내부 레포에서는 마찰 없이 돌고 외부 레포에서는 사람이 개입합니다.
주의할 점
- predicate는 순수 함수로 유지하세요. 여기서 외부 API 호출하거나 상태를 바꾸면 승인 흐름이 예측 불가능해집니다.
- 프리셋 스코프는 최소 권한이지만, 최소는 아닐 수 있어요.
maintainer프리셋은 이름값 하니까, 프로덕션 에이전트에는 정말 필요한 프리셋만 붙이세요. - 토큰 수명이 짧다는 건 좋은 소식이자 운영 부담입니다. 커넥터 자체의 가용성이 곧 에이전트 가용성이 돼요.
에이전트 도구 승인 흐름을 어떻게 테스트 전략과 엮을지는 전통적 테스트의 종말? 에이전트 개발 시대를 살리는 JIT 테스팅의 부상에서 이어집니다.
한국 개발 생태계에서의 적용 맥락
국내 SI·사내 자동화 환경에서는 GitHub Enterprise나 사내 Git 서버를 쓰는 경우가 많아서, Vercel Connect 커넥터를 그대로 못 붙이는 케이스가 생깁니다. 이럴 땐 확장의 승인 규칙 계층만 떼어내서 사내 봇에 이식하는 게 현실적이에요. always/once/predicate 3단 구조는 특정 벤더에 종속된 개념이 아니라 그냥 좋은 설계 패턴이니까요.
또 하나, 국내 팀은 코드 리뷰 코멘트 자동화에 특히 민감합니다. "봇이 단 코멘트"에 대한 신뢰 이슈가 있어서, predicate로 외부 기여자 PR에만 자동 코멘트를 달고 내부 PR은 사람이 다는 식의 절충이 잘 먹힙니다.
다음 단계 학습 방향
- Vercel Connect 커넥터 생성부터 시작해서, 본인 GitHub 조직에 붙여보세요.
code-review프리셋으로 시작해서 승인 로그를 며칠 관찰한 뒤, predicate 조건을 좁혀나가세요.- 익숙해지면
ci-ops나maintainer프리셋을 별도 에이전트에 붙여 권한을 분리하는 구조로 확장하세요.
결국 이 확장이 던지는 메시지는 명확해요. 에이전트의 권한은 프롬프트가 아니라 설정 파일에 명시되어야 한다. 그게 리뷰 가능하고, 감사 가능하고, 되돌릴 수 있는 구조니까요.