Gmail과 대화하는 Discord AI 어시스턴트를 구축한 방법

Discord에서 직접 받은 편지함과 대화할 수 있다면 어떨까요?

단순히 AI에게 이메일을 요약해달라고 요청하는 것을 넘어, 채팅 대화에서 실제로 Gmail 작업을 실행할 수 있습니다:

• 읽지 않은 이메일 읽기
• 기존 이메일에 답장하기
• 완전히 새로운 이메일 보내기
• Google 인증 처리
• 결과를 깔끔한 Discord 메시지로 다시 포맷팅하기

이것이 바로 제가 이 영상 튜토리얼에서 구축한 내용입니다:

이 튜토리얼에서 저는 셀프 호스팅(self-hosted) AI 챗봇 및 워크플로 자동화 플랫폼인 Hexabot을 사용하여 Gmail과 통신하는 Discord AI 어시스턴트를 구축합니다.

목표는 단순히 LLM을 Gmail에 연결하는 것이 아닙니다.

목표는 대화, 의도 탐지 (intent detection), 조건부 로직 (conditional logic), 도구 실행 (tool execution), 인증 처리 (authentication handling), 그리고 응답 포맷팅 (response formatting)을 포함하는, 더 제어된 방식의 AI 자동화 워크플로 (automation workflows) 구축 방법을 보여주는 것입니다.

왜 그냥 MCP Gmail 서버를 사용하지 않나요?

기술적으로는 더 빠르게 구축할 수도 있었습니다.

예를 들어, Gmail MCP 서버와 MCP 연결을 가진 AI 에이전트를 구성하고, 에이전트가 언제 Gmail 도구를 호출할지 결정하도록 할 수 있습니다.

그 방식은 특히 빠른 프로토타입 제작에 유용합니다.

하지만 이 튜토리얼은 의도적으로 다른 경로를 택했습니다.

에이전트에게 실행 흐름에 대한 완전한 자유를 주는 대신, 우리는 워크플로를 시각적으로 단계별로 구축합니다. 이를 통해 무엇이, 언제, 어떻게 발생하는지, 그리고 각 결정이 어떻게 처리되는지에 대해 더 많은 제어권을 가질 수 있습니다.

다시 말해, AI가 직접 "모든 것을 수행"하는 것이 아닙니다.

워크플로는 책임을 분리합니다:

• AI가 사용자의 의도 (intent)를 탐지합니다.
• 워크플로가 의도를 검증합니다.
• Gmail 작업이 실제 동작을 수행합니다.
• 조건부 분기 (conditional branch)가 인증을 처리합니다.
• 또 다른 AI 단계가 Discord를 위한 최종 응답을 포맷팅합니다.

이 방식은 어시스턴트를 디버깅하기 더 쉽게 만들고, 확장하기에 더 안전하며, 프로덕션 수준의 AI 자동화를 구축하려는 개발자들이 이해하기 더 쉽게 만듭니다.

어시스턴트가 할 수 있는 일

Discord Gmail 어시스턴트는 세 가지 주요 유스케이스 (use cases)를 지원합니다.

1. 이메일 읽기

예시 프롬프트 (prompt):

읽지 않은 이메일 중 상위 2개를 보여줘.

어시스턴트는 사용자가 이메일을 읽고 싶어 한다는 것을 이해하고, 제한 수치(limit)를 추출하며, Gmail을 호출하여 Discord에 최적화된 깔끔한 요약본을 반환합니다.

2. 이메일에 답장하기

예시 프롬프트 (prompt):

이 이메일에 "감사합니다, 잘 알겠습니다."라고 답장해줘.

어시스턴트는 동작을 reply로 추출하고, 대상 이메일을 식별하며, 답장 텍스트를 캡처하여 Gmail을 통해 응답을 보냅니다.

3. 새 이메일 보내기

예시 프롬프트 (prompt):

someone@example.com에게 지난 1년간의 AI 진화에 대해 이메일을 보내줘.

어시스턴트는 이것이 새 이메일임을 감지하고, 수신자를 추출하며, 제목과 내용을 준비하여 이메일을 보낸 뒤 Discord에서 결과를 확인합니다.

워크플로 아키텍처 (The workflow architecture)

전체 워크플로는 다음 패턴을 따릅니다:

Discord 메시지
   ↓
AI 의도 추론 (AI Infer Intent)
...

이 부분이 이 튜토리얼에서 가장 중요한 부분입니다.

우리는 무엇을 할지 무작위로 결정하는 블랙박스(black-box) AI 에이전트를 만드는 것이 아닙니다. 모든 중요한 단계가 가시적인, 제어된 실행 흐름(controlled execution flow)을 구축하고 있는 것입니다.

1단계: 사용자 의도 감지 (Detect the user intent)

첫 번째 단계는 AI Object 추론 (AI Infer Object) 액션입니다.

LLM에게 자유 형식의 텍스트 답변을 요청하는 대신, 구조화된 객체(structured object)를 반환하도록 요청합니다.

스키마(schema)에는 다음과 같은 필드들이 포함됩니다:

action
limit
targetMail
...

action 필드에는 다음과 같은 값이 들어갈 수 있습니다:

read
reply
new
...

이는 AI와 워크플로 사이의 계약(contract) 역할을 합니다.

예를 들어:

읽지 않은 이메일 중 상위 2개를 보여줘.

다음과 같은 형태가 됩니다:

{
  "action": "read",
  "limit": "2"
...

그리고:

마지막 이메일에 감사합니다라고 답장해줘.

다음과 같이 변환됩니다:

{
  "action": "reply",
  "mailText": "Thank you"
...

이것은 매우 강력한 패턴인데, 그 이유는 AI가 Gmail 작업을 직접 실행할 책임이 없기 때문입니다. AI는 오직 의도와 필요한 필드들을 추출할 뿐입니다.

그다음 무엇을 할지는 워크플로가 결정합니다.

2단계: 조건부 분기 추가 (Add a conditional branch)

의도 탐지 (intent detection) 이후, 워크플로(workflow)는 AI가 유효한 동작 (action)을 감지했는지 확인합니다.

동작이 존재하면, 워크플로는 Gmail 단계로 계속 진행합니다.

동작이 비어 있다면, 어시스턴트는 다음과 같은 폴백 메시지 (fallback message)를 보냅니다:

안녕하세요, 오늘 무엇을 도와드릴까요?

이는 사용자 요청이 불분명할 때 어시스턴트가 추측하는 것을 방지합니다.

어시스턴트가 이메일 전송과 같은 실제 동작에 접근할 수 있는 경우, 이 점은 매우 중요합니다.

3단계: Gmail 동작 실행 (Execute the Gmail action)

다음 단계는 Gmail 동작입니다.

이 단계는 워크플로가 구조화된 AI 출력값을 Gmail 작업으로 매핑 (mapping)하는 곳입니다:

mailText   → 이메일 본문 (email body)
subject    → 이메일 제목 (email subject)
targetMail → 수신자 또는 대상 이메일 (recipient or target email)
...

핵심 아이디어는 다음과 같습니다:

AI는 의도 (intent)를 탐지합니다.
Gmail 동작은 작업을 실행합니다.

이러한 분리가 워크플로를 더욱 예측 가능하게 만듭니다.

값을 검사하거나, 동작을 디버깅 (debug)하거나, 조건을 추가하거나, 검증 (validation)을 추가하거나, 이메일을 보내기 전에 승인 (approval) 단계를 삽입할 수 있습니다.

프로덕션 (production) 환경을 구축한다면, 특히 어시스턴트를 팀 단위로 사용하는 경우라면 이메일을 보내거나 답장하기 전에 확인 (confirmation) 단계를 추가할 것을 강력히 권장합니다.

4단계: Google 인증 처리 (Handle Google authentication)

Gmail 동작은 다양한 상태 (status)를 반환할 수 있습니다.

상태가 200이면, Gmail 작업이 성공한 것입니다.

상태가 401이면, 사용자가 여전히 Google 인증을 수행해야 합니다.

따라서 워크플로는 인증 케이스를 별도로 처리합니다.

인증이 필요한 경우, 어시스턴트는 Discord 버튼을 보냅니다:

Google로 로그인하기

이 버튼은 Google OAuth 흐름 (flow)으로 연결됩니다.

이를 통해 사용자 경험 (user experience)이 훨씬 매끄러워집니다. 사용자는 Discord에서 시작하여, 인증 버튼을 받고, Google로 로그인한 후, 대화를 계속할 수 있습니다.

5단계: Discord용 응답 형식 지정 (Format the response for Discord)

Gmail 동작이 성공하면, 가공되지 않은(raw) Gmail 결과값을 여전히 포맷팅 (formatting)해야 합니다.

이를 위해 워크플로는 AI Formatter라고 불리는 AI 에이전트 (AI Agent) 단계를 사용합니다.

그 역할은 간단합니다:

• Gmail 결과 가져오기
• 유용한 정보 유지하기
• Discord에 최적화된 메시지 형식으로 구성하기
• 불필요한 설명 피하기

이는 또 다른 훌륭한 설계 선택입니다.

Gmail 액션 (Action)은 도구 호출 (Tool Call)을 처리합니다.
AI 포매터 (AI Formatter)는 프레젠테이션 (Presentation)을 처리합니다.
최종 메시지는 Discord로 다시 전송됩니다.

다시 말하지만, 각 단계는 명확한 책임을 가집니다.

단계 6: 워크플로를 Discord에 연결하기

워크플로가 준비되면, 이를 Discord 채널에 연결합니다.

Hexabot에서 Discord 채널은 다음과 같이 구성됩니다:

• 대상 워크플로 (Target Workflow)
• Discord 봇 토큰 (Discord Bot Token)
• 애플리케이션 ID (Application ID)

연결되면, Discord 봇으로 전송된 메시지가 Gmail 어시스턴트 워크플로를 트리거 (Trigger)합니다.

이 시점에서 어시스턴트는 Discord 내부에서 직접 테스트할 준비가 완료됩니다.

데모: 받은 편지함과 대화하기

데모에서는 세 가지 실제 사용 사례 (Use Case)를 테스트합니다.

먼저, 어시스턴트에게 Gmail에 접속하도록 요청합니다. 사용자가 아직 인증 (Authentication)되지 않았기 때문에, 워크플로는 Google 로그인 버튼을 보냅니다.

그 다음, 읽지 않은 이메일 읽기를 테스트합니다:

읽지 않은 이메일 중 상위 2개를 보여줘.

어시스턴트는 이메일을 가져와서 Discord 내에 깔끔한 요약본을 반환합니다.

다음으로, 이메일 답장하기를 테스트합니다:

이 이메일에

이 지점에서 AI 자동화 (AI automation)가 더욱 실용적으로 변합니다.

완전히 자율적인 에이전트 (autonomous agent)를 구축하고 그것이 올바르게 동작하기를 바라는 대신, 비즈니스 로직 (business logic)은 명시적이고 가시적으로 유지하면서 AI가 적절한 곳에 사용되도록 하는 워크플로 (workflow)를 구축할 수 있습니다.

## 커스텀 액션 (custom actions)에 관한 참고 사항

이 튜토리얼은 Hexabot 에디터에서 워크플로를 시각적으로 구축하는 데 중점을 둡니다.

Gmail 커스텀 액션 자체를 개발하는 방법은 다루지 않습니다.

프로젝트의 소스 코드는 YouTube 설명란에 링크되어 있으며, 커스텀 액션 개발은 별도의 영상에서 다룰 예정입니다.

따라서 여러분의 목표가 워크플로를 구축하는 방법을 이해하는 것이라면, 이 튜토리얼이 도움이 될 것입니다.

만약 여러분의 목표가 처음부터 새로운 커스텀 액션을 만드는 것이라면, 후속 영상을 기다려 주세요.

## 보안 참고 사항

이 워크플로는 Gmail에 연결되므로 보안이 중요합니다.

유사한 것을 게시하거나 배포하기 전에 반드시 다음 사항을 확인하세요:

- API 키나 OAuth 클라이언트 비밀번호 (client secrets)를 절대 커밋하지 마세요
- 환경 변수 (environment variables) 또는 안전한 자격 증명 저장소 (credential storage)를 사용하세요
- OAuth 범위 (scopes)를 어시스턴트가 실제로 필요로 하는 수준으로 제한하세요
- 프로덕션 (production) 환경에서 이메일을 보내기 전에 확인 단계를 추가하세요
- 감사 가능성 (auditability)을 위해 중요한 작업을 로그로 남기세요
- 오류 및 만료된 세션을 적절하게 처리하세요

AI 에이전트는 강력하지만, 프로덕션 워크플로에는 가드레일 (guardrails)이 필요합니다.

## 전체 튜토리얼 시청하기

여기에서 전체 단계별 튜토리얼을 시청할 수 있습니다:

[https://www.youtube.com/watch?v=FKrzVK1fqK4](https://www.youtube.com/watch?v=FKrzVK1fqK4)

유용한 링크:

- Hexabot 웹사이트: [https://hexabot.ai](https://hexabot.ai)
- Hexabot 문서: [https://docs.hexabot.ai](https://docs.hexabot.ai)
- Hexabot GitHub: [https://github.com/hexabot-ai/hexabot](https://github.com/hexabot-ai/hexabot)
- 영상 튜토리얼: [https://www.youtube.com/watch?v=FKrzVK1fqK4](https://www.youtube.com/watch?v=FKrzVK1fqK4)

## 마치며

모든 것이 프롬프트 (prompt)일 때는 AI 어시스턴트를 구축하는 것이 쉽습니다.

유용한 AI 어시스턴트를 구축하려면 더 많은 구조 (structure)가 필요합니다.

이 Discord Gmail 어시스턴트는 간단한 예시일 뿐이지만, 중요한 아이디어를 보여줍니다. AI 에이전트 (AI agents)는 워크플로 (workflows), 조건 (conditions), 타입이 지정된 출력 (typed outputs), 인증 처리 (authentication handling), 그리고 제어된 도구 실행 (controlled tool execution)과 결합될 때 훨씬 더 신뢰할 수 있게 됩니다.

그것이 멋진 데모 (demo)와 실제로 그 위에 구축할 수 있는 무언가 사이의 차이점입니다.

만약 AI 자동화 (AI automations)를 구축하고 있다면, "하나의 거대한 에이전트"라는 관점보다는 "제어된 실행 흐름 (controlled execution flow)"이라는 관점에서 생각하도록 노력해 보세요.

그 지점에서 흥미로운 일들이 벌어집니다.