Grant 추상화 재사용을 통한 신규 기능 통합 비용 제로화

Under the Hood: An Agent Account Is Just a Grant

Qasim Muhammad2026년 6월 15일6분intermediate

AI 요약

Context

AI Agent를 위한 호스팅 메일함 기능 추가 시 전용 리소스와 SDK, 인증 체계를 새로 구축해야 하는 중복 개발 비용 발생 가능성 존재. 기존의 복잡한 OAuth 기반 연결 계정 구조와 새로운 Agent 계정 간의 파편화된 API 설계 방지 필요.

기존 OAuth 인증 기반의 'Grant' 개념을 Agent Account에 동일하게 적용하여 /v3/grants/{grant_id} 엔드포인트를 공유하는 설계 채택
Agent Account를 provider: nylas라는 특정 속성을 가진 Grant로 정의하여 기존의 메시지, 캘린더, 연락처 CRUD 로직을 그대로 상속
OAuth 핸드셰이크와 Refresh Token 과정을 생략하고 직접 Grant를 생성하는 connect/custom API를 통해 프로비저닝 간소화
통합 핸들러 내에서 provider 필드 분기 처리만으로 인간 사용자 계정과 AI Agent 계정의 트래픽을 구분하는 구조 설계
메일함 표면의 기능은 상속하되, 정책(Policies), 규칙(Rules), 감사 추적(Rule evaluations) 등 관리자 제어 평면(Admin Surface)만 신규 구축하여 책임 분리

실천 포인트

1. 신규 기능 추가 시 기존의 identity handle이나 resource abstraction으로 대체 가능한지 검토

2. 기능적 요구사항을 '사용자 표면(Surface)'과 '관리 표면(Admin)'으로 분리하여 상속 범위 결정

3. 새로운 리소스 타입 도입 전, 기존 SDK와 Webhook 스키마를 그대로 사용할 수 있는 인터페이스 설계 우선 고려

태그