TL;DR

  • 에이전트에게 사용자의 비밀번호를 넘기는 대신 자체 이메일 받은편지함과 AgentID 로그인을 부여하면, 앱이 에이전트를 사용자와 구분하고 사용자를 책임 소유자로 기록할 수 있음.
  • 빌린 로그인은 에이전트의 활동을 사용자 이름으로 기록하고 에이전트 메일을 사용자 받은편지함으로 보내며, 접근을 끊으려면 사용자 비밀번호를 변경해야 하는 구조임.
  • 자체 AgentID는 앱에 에이전트의 안정적인 식별자를 제공하고, 비밀번호나 재사용 가능한 키를 앱에 전달하지 않으며, 유출 피해 범위를 해당 에이전트의 로그인으로 제한함.
  • 설정은 agentmail inboxes create로 받은편지함을 만든 뒤 agentmail apps connect 또는 승인 API로 앱 로그인을 연결하는 두 단계임.
  • 에이전트는 받은편지함에 묶인 P-256 로그인 키의 개인 키를 보유하며, 키는 활성화 후 30일, 앱 승인 기록은 받은편지함과 앱별로 180일 유지됨.

에이전트가 사용자 로그인을 쓰면 어떤 문제가 생기나?

  • 에이전트가 사용자 로그인을 쓰면 앱은 사용자를 고객으로, 에이전트를 사용자 본인으로 취급함. 에이전트의 이메일은 사용자 받은편지함으로 전달되고, 에이전트의 활동은 사용자 이름으로 기록되며, 접근을 취소하는 유일한 방법은 사용자 비밀번호 변경임.
  • 로그인 방식에 따른 차이는 다음과 같음.
  • 앱이 고객으로 인식하는 대상: 빌린 로그인은 사용자, AgentID는 에이전트이며 사용자는 소유자로 기록됨.
  • 앱 이메일을 받는 곳: 빌린 로그인은 사용자 받은편지함, AgentID는 에이전트 자체 받은편지함임.
  • 에이전트 활동에 표시되는 이름: 빌린 로그인은 사용자 이름, AgentID는 에이전트의 고유하고 안정적인 식별자임.
  • 로그인 시 앱에 전달되는 정보: 빌린 로그인은 사용자 비밀번호, AgentID는 비밀번호나 재사용 가능한 키가 아님.
  • 인증 정보 유출 시 영향 범위: 빌린 로그인은 사용자 계정 전체, AgentID는 해당 에이전트 로그인에 한정됨.
  • 에이전트 접근 차단 방법: 빌린 로그인은 사용자 비밀번호 변경, AgentID는 에이전트 로그인 키 삭제임.
  • 특히 유출 피해 범위와 접근 차단 방식이 중요함. 빌린 로그인은 모든 에이전트에 사용자 계정 전체의 피해 범위를 부여하며, 문제를 일으킨 에이전트의 접근을 끊을 때 사용자 본인도 계정 접근을 잃게 됨.

사용자를 대신해 행동하는 에이전트와 자체 계정을 가진 에이전트는 어떻게 다른가?

  • 사용자를 대신해 행동하는 에이전트는 사용자의 권한을 빌려 사용자로 기록되는 반면, 자체 계정을 가진 에이전트는 앱이 독립된 주체로 인식하고 사용자를 책임 소유자로 연결함.
  • 두 모델 모두 유효하며, 위임 방식은 사용자 자신의 계정 안에서 작동하는 에이전트에 적합함.
  • 서비스에 가입하고 서비스 이메일을 받으며 계정을 장기간 보유하는 에이전트에는 두 번째 모델이 더 잘 맞음. 앱은 토큰에서 두 모델을 구분할 수 있음.

두 가지 명령으로 에이전트에 AgentID를 부여하는 방법

  • 에이전트의 받은편지함을 만드는 명령과 앱에 로그인을 연결하는 명령을 사용함. 받은편지함 주소가 에이전트의 AgentID가 됨.
  • 첫 번째 단계에서 표시 이름을 지정해 받은편지함을 만듦.
  • agentmail inboxes create --display-name "Research Agent"
  • 두 번째 단계는 agentmail apps connect이며, AgentMail API를 호출해 AgentID를 지원하는 앱의 로그인을 시작함.
  • POST /v0/apps/{app_id}/connect 호출은 5분간 유효한 일회용 magic_url과 api_key_id를 반환함.
  • 로그인 완료 후 GET /v0/api-keys/{api_key_id}로 키 상태를 확인함. 로그인 완료 전 상태는 pending이며 완료 후 active로 바뀜.
  • 연결 요청에 사용하는 AgentMail API 키에는 app_connect 권한이 필요하며, 새 키에서는 기본적으로 비활성화되어 있으므로 에이전트가 사용하는 키에 활성화해야 함.
  • 호출은 대기 상태의 로그인 키를 생성하며, 브라우저나 클라이언트에서 로그인을 완료하면 키가 활성화됨.
  • 앱이 소유자 정보를 요청하면 키에 app_share_owner 권한도 필요함. 권한이 없으면 에이전트가 단독으로 완료할 수 없으며, AgentMail 계정에서 로그인을 승인해야 함.
  • 다른 방법으로는 에이전트가 앱의 AgentID 대기 페이지에 먼저 접속한 뒤, 페이지의 auth_token을 사용해 POST /v0/inboxes/{inbox_id}/authorize를 호출하거나 CLI의 agentmail inboxes authorize 명령을 사용할 수 있음.
  • 요청에 accept_disclosure: true를 지정하면 에이전트가 앱의 정보 공개 내용을 대신 수락할 수 있음.
  • 전체 에이전트 측 절차는 AgentMail의 AgentID 로그인 가이드에 있음.

에이전트가 헤드리스로 실행되거나 브라우저가 없는 경우

  • 화면이 없는 브라우저를 제어하는 에이전트도 일반 브라우저와 같은 방식으로 로그인할 수 있음.
  • 브라우저가 전혀 없는 에이전트는 에이전트가 시작한 로그인 세션과 동일한 브라우저에서 AgentMail 콘솔을 열어 직접 로그인을 완료해야 함.
  • 자체 서명자를 실행하는 애플리케이션에는 세 번째 방법이 있음. 브라우저에서 키를 생성하는 대신 AgentMail API Keys 엔드포인트를 통해 자체 공개 P-256 키를 등록할 수 있으며, 공개 키 인증 가이드에서 자세한 내용을 다룸.

에이전트가 보유하는 정보와 유지 기간

  • 에이전트는 자체 받은편지함에 한정된 로그인 키의 개인 키를 보유하고, AgentMail은 공개 키만 기록함. 키는 브라우저에서 생성되는 P-256 키 쌍임.
  • 개인 키는 브라우저에서 생성되고 저장되며, 브라우저 자바스크립트 API를 통해 내보낼 수 없음.
  • 로그인 키는 활성화 시점부터 30일 동안 유효함. 이 키는 키를 만든 AgentMail API 키와 별개이므로 해당 API 키를 삭제해도 로그인 키는 취소되지 않음. 에이전트의 접근을 차단하려면 로그인 키 자체를 삭제해야 함.
  • 에이전트가 승인한 앱별 승인은 받은편지함과 앱 조합별로 180일 동안 기억됨.
  • 에이전트는 빌린 로그인으로는 얻지 못하는 작동하는 이메일 받은편지함도 보유함. 앱은 온보딩 안내, 제품 업데이트, 영수증, 청구서를 보낼 수 있으며, 에이전트는 지원 티켓을 열고 해결할 수도 있음.
  • 첫 에이전트를 설정할 때는 AgentMail의 AgentID 페이지에서 시작할 수 있음.
  • 시작하기
  • 문서 읽기