AI Sparkup

최신 AI 쉽게 깊게 따라잡기⚡

Claude Code 튜토리얼 – 서브에이전트로 Gmail 자동 분류하기

목차

이 튜토리얼은 Google 시니어 소프트웨어 엔지니어 Justin Poehnelt이 공개한 데모 프로젝트를 기반으로, Claude Code 서브에이전트를 활용해 Gmail 수신함을 자동 분류하는 시스템을 설명한다. 에이전트가 이메일을 읽고, 보안 위협을 검사하고, 발신자 관계를 분석하고, 내용을 요약한 뒤 라벨을 적용하는 전 과정을 자동화한다.

소스 코드: github.com/jpoehnelt/subagent-email-triage

아키텍처 개요

시스템은 1개의 오케스트레이터 + 5개의 전문 에이전트로 구성된다. 오케스트레이터가 배치(batch)를 관리하고, 전문 에이전트들이 병렬로 실행된다.

email-triage-orchestrator
├── email-security-analyzer (×10, 병렬) — 보안 위협 탐지
├── email-relationship-analyzer              — 발신자 관계 분석
├── email-content-summarizer                 — 콘텐츠 요약 및 컨텍스트 추출
├── email-label-applier                      — Gmail 라벨 적용
└── email-filter-manager                     — 필터 규칙 관리

에이전트들은 [gws CLI](https://github.com/googleworkspace/cli)를 도구로 사용해 Gmail API와 통신한다.

6개 에이전트 역할

1. email-triage-orchestrator

배치 단위로 이메일을 가져와 각 전문 에이전트에게 위임한다. 10개의 보안 분석 에이전트를 병렬 실행한 후, 관계 분석과 요약 에이전트를 동시에 실행하는 순서로 진행한다.

2. email-security-analyzer

각 이메일을 독립된 격리 환경(isolated agent)에서 분석해 피싱·스팸·악성 링크 여부를 판단한다. 10개가 병렬 실행되므로 대량 이메일을 빠르게 처리할 수 있다. 토큰 사용량의 대부분이 이 에이전트에서 발생한다.

3. email-relationship-analyzer

발신자가 누구인지, 이전 대화 이력이 있는지, 조직 내 관계인지를 분석해 우선순위 컨텍스트를 생성한다.

4. email-content-summarizer

이메일 내용을 요약하고, 요청 사항·마감일·후속 조치 항목을 추출한다.

5. email-label-applier

앞선 분석 결과를 바탕으로 Gmail 라벨을 적용한다. 보안 위협으로 판단된 메일, 우선순위 높은 메일, 후속 조치가 필요한 메일 등으로 자동 분류된다.

6. email-filter-manager

필터 규칙과 지식 베이스(allowlist, blocklist 등)를 관리한다.

구현 시 배운 점

메모리는 추가했다가 제거했다

처음에는 에이전트에 메모리를 주어 발신자 패턴을 학습하게 했으나, 오히려 복잡성과 오류를 늘렸다. 최종 버전에서는 메모리를 제거하고 각 배치를 독립적으로 처리한다.

토큰 비용의 대부분은 보안 검사

가장 많은 토큰을 소비하는 단계는 보안 분석이다. 이메일마다 맥락을 충분히 주어야 정확한 판단이 가능하기 때문이다.

도구 권한과 허용 목록 관리가 핵심

에이전트에게 어떤 gws 명령어를 허용할지, 어떤 Gmail 작업을 허용할지를 명시적으로 정의해야 한다. 과도한 권한은 의도치 않은 메일 삭제·이동을 유발할 수 있다.

누가 사용하면 좋은가

  • 수신량이 많아 수동 분류가 어려운 개발자나 매니저
  • Claude Code 서브에이전트 패턴을 실제 유스케이스로 배우고 싶은 엔지니어
  • 이메일 워크플로 자동화 시스템을 직접 구축하려는 팀

관련 문서

참고 자료

AI Sparkup 구독하기

최신 게시물 요약과 더 심층적인 정보를 이메일로 받아 보세요! (무료)