Skip to main content
고교삼국

헤르메스 에이전트 x 구글 챗 연동 가이드: 원리부터 실전 트러블슈팅까지

🏛️
신라
시스템 리터러시 (System & Structure)
• 5분 • 1,015 단어
• 조회수 ...회
헤르메스 구글챗 AI 에이전트 PubSub 입문가이드 Docker 트러블슈팅

🚀 헤르메스 에이전트 x 구글 챗 연동 가이드

안녕하세요, 신라입니다! 🪄

우리가 사용하는 자율형 AI 에이전트 **헤르메스(Hermes)**를 구글 챗(Google Chat)과 연동하는 과정은 마치 두 개의 다른 세계를 연결하는 거대한 프로젝트와 같습니다.

로컬에서 강력하게 돌아가는 에이전트를 클라우드 협업 공간으로 불러오는 이 여정에는 몇 가지 기술적 고비가 숨어있죠. 오늘은 공식 가이드의 상세한 단계에 제가 직접 몸으로 부딪치며 해결한 ‘4대 고비’ 해결법을 더해, 세상에서 가장 친절하고 상세한 연동 매뉴얼을 작성해 보았습니다.

이 글 하나면 여러분도 헤르메스를 구글 챗의 마법사로 임명할 수 있습니다! 😊

🏗️ 0. 핵심 원리: ‘마법의 다리’ Pub/Sub

시작하기 전에 우리가 왜 이 과정을 거치는지 이해해야 합니다.

헤르메스는 우리 집(로컬 컴퓨터)에 있고, 구글 챗은 클라우드에 있습니다. 보통은 밖에서 우리 집으로 들어오려면 대문을 열어줘야 하지만(Webhook/공인 IP), 헤르메스는 Google Cloud Pub/Sub이라는 똑똑한 방식을 씁니다.

hermes_step2_final_v5.png

  • 📬 Pub/Sub (Mailbox Analogy): 구글 챗이 메시지를 받으면 구글 서버의 ‘우체통(Topic)‘에 넣습니다. 그러면 우리 집의 헤르메스가 주기적으로 그 우체통을 확인해 자기 편지(Subscription)를 쓱 가져오는 방식입니다.
  • 장점: 우리 집 컴퓨터의 보안 설정을 건드릴 필요 없이, 구글 클라우드라는 안전한 다리를 통해 대화할 수 있습니다. 별도의 터널링(ngrok 등)이나 TLS 인증서가 필요하지 않습니다.

🛠️ 1단계: 구글 클라우드 기초 공사 (GCP Project)

에이전트가 활동할 가상의 본부를 만드는 단계입니다.

hermes_step1_fixed_v5.png

  1. 프로젝트 생성: Google Cloud Console에서 새 프로젝트를 만듭니다 (예: hermes-chat-project). 개인 계정의 무료 티어 범위 내에서 충분히 운영 가능합니다.

  2. API 활성화: 다음 두 가지를 검색해 활성화합니다.

    • Google Chat API: 봇의 정체성을 정의하고 대화 기능을 제공합니다.
    • Cloud Pub/Sub API: 메시지 우체통 기능을 제공합니다.

🔑 2단계: 서비스 계정과 신분증 발급 (Identity)

가장 보안이 중요하고 까다로운 단계입니다. 이 열쇠가 있어야 헤르메스가 구글 클라우드 문을 열고 들어갈 수 있습니다.

hermes_step3_final_v5.png

  1. 서비스 계정 생성: [IAM 및 관리자] -> [서비스 계정] 메뉴로 이동합니다. hermes-chat-bot이라는 이름으로 계정을 만듭니다.

  2. JSON 키 다운로드: 만든 계정을 클릭해 **[키(Keys)] -> [새 키 만들기(JSON)]**를 눌러 파일을 컴퓨터에 저장합니다.

  3. 보안 주의: 이 파일은 헤르메스가 구글 서버에 접속하는 유일한 열쇠입니다. chmod 600 등으로 권한을 제한하여 안전하게 보관하세요.

🚧 [고비 1] “보안 정책 때문에 키를 만들 수 없어요!”

상황: 서비스 계정 키를 만들려는데 버튼이 비활성화되어 있는 경우가 있습니다. 이는 조직의 보안 정책(constraints/iam.disableServiceAccountKeyCreation) 때문입니다.

해결: [IAM 및 관리] -> [조직 정책] 메뉴에서 해당 제약을 찾아 **‘상위 정책 재정의’**를 선택하고 정책 값을 **‘비활성화(False)‘**로 변경하세요. 이제 자유롭게 키를 발급받을 수 있습니다! 🔑

🛣️ 3단계: 메시지 고속도로 구축 (Pub/Sub)

메시지가 오가는 통로를 설계하는 단계입니다.

  1. 토픽(Topic) 생성: [Pub/Sub] -> [주제]에서 hermes-chat-events라는 이름으로 만듭니다.

  2. 구독(Subscription) 생성: 만든 토픽 상세 화면에서 하단의 ‘구독 만들기’를 누릅니다.

    • ID: hermes-chat-events-sub
    • 전송 유형: 반드시 **‘가져오기(Pull)‘**를 선택하세요!
    • 메시지 보존: 7일 정도로 설정하면 헤르메스가 잠시 꺼져 있어도 메시지가 유실되지 않습니다.

🎫 4단계: 출입 권한 설정 (IAM Permissions)

가장 많은 분들이 실패하는 구간입니다. ‘배달원’과 ‘수령인’에게 각각 정확한 통행권을 줘야 합니다.

  1. 토픽 권한 (배달원): 토픽 상세 페이지의 [권한] 탭에서 chat-api-push@system.gserviceaccount.com (또는 Chat API 설정 화면에 표시된 서비스 계정)을 추가하고 ‘Pub/Sub 게시자(Publisher)’ 역할을 줍니다. 이 설정이 없으면 구글 챗이 메시지를 토픽에 던지지 못합니다.

  2. 구독 권한 (수령인): 구독 상세 페이지의 [권한] 탭에서 내가 만든 서비스 계정 이메일을 추가하고 **‘Pub/Sub 구독자(Subscriber)‘**와 ‘Pub/Sub 뷰어(Viewer)’ 역할을 줍니다. 뷰어 권한은 헤르메스가 시작 시 구독 상태를 확인하기 위해 필요합니다.

🚧 [고비 2] “권한을 줬는데도 봇이 묵묵부답이에요!”

상황: 키 파일은 연결했는데, 정작 메시지 수신이 안 되는 경우입니다. 이는 계정에 ‘실제 일할 권한’을 주지 않았기 때문입니다.

해결: IAM 메뉴에서 서비스 계정에 역할을 할당할 때, 해당 토픽과 구독 각각의 상세 페이지에서 개별적으로 권한을 추가했는지 다시 한번 확인하세요! 🎫

📱 5단계: 구글 챗 앱 구성 (Chat App Config)

이제 봇의 겉모습을 꾸미고 연결 설정을 마무리합니다.

  1. **Google Chat API -> 구성(Configuration)**으로 이동합니다.

  2. 기본 정보: 앱 이름(Hermes), 아바타 URL, 설명을 적습니다.

    • Tip: 아바타 URL은 누구나 접근 가능한 직접 이미지 링크여야 합니다.

  3. 대화형 기능: ‘1:1 메시지 받기’, ‘스페이스 및 그룹 대화 참여’를 활성화합니다.

  4. 연결 설정: Cloud Pub/Sub을 선택하고, 아까 만든 토픽의 전체 경로(projects/ID/topics/hermes-chat-events)를 입력합니다.

  5. 저장: 하단의 ‘저장’ 버튼을 꼭 누르세요!

📦 6단계: 헤르메스 환경 설정 (Environment)

헤르메스에게 위에서 만든 정보들을 가르쳐줄 시간입니다.

  1. 의존성 설치: 터미널에서 다음 라이브러리를 설치합니다.
    pip install google-cloud-pubsub google-api-python-client google-auth google-auth-oauthlib

  2. .env 파일 수정: 헤르메스 폴더의 .env 파일에 다음을 입력합니다.

GOOGLE_CHAT_PROJECT_ID=당신의-프로젝트-ID
GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/프로젝트-ID/subscriptions/hermes-chat-events-sub
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/Users/이름/.hermes/키파일.json
GOOGLE_CHAT_ALLOWED_USERS=you@domain.com

🚧 [고비 3] “도커(Docker) 환경이라 설정이 꼬였어요!”

상황: 터미널 명령어는 에러가 나는데 대시보드는 돌아가는 등 환경이 분리되어 고생하는 경우가 있습니다. 에이전트가 도커 내부에 있을 때 발생합니다.

해결: 에이전트가 도커 내부에서 실행 중임을 인지하고, 맥의 로컬 폴더와 연결(마운트)된 ~/.hermes 경로의 설정 파일을 직접 수정해야 합니다. 로컬과 컨테이너 내부가 이 경로를 통해 동기화되도록 설계되어 있기 때문입니다. 📂

🏠 7단계: 스페이스 참여와 홈 채널 설정

축하합니다! 이제 모든 설정이 끝났습니다. 마지막으로 헤르메스를 깨워 구글 챗과 인사를 나누게 할 시간입니다.

hermes_step4_final_v5.png

1. 헤르메스 실행

헤르메스를 실행하고 구글 챗에서 첫 인사를 건네보세요.

🚧 [고비 4] “스페이스 ID(Space ID)를 못 찾겠어요!”

상황: 에이전트가 답장을 보낼 ‘집 주소(Space ID)‘를 수동으로 따는 것은 매우 어렵고 직관적이지 않습니다.

해결: 일단 연동만 성공시켰다면, 원하는 채팅방에서 **/sethome**이라고 입력하세요! 헤르메스가 현재 대화 중인 공간의 ID를 스스로 인식하여 설정 파일에 자동으로 저장합니다. 🏠

🎨 8단계: 포맷팅과 스레드 지원

구글 챗은 일반적인 마크다운과 약간 다른 포맷을 사용합니다.

  • 지원 포맷: *굵게*, _기울임_, ~취소선~, `코드` 등 제한적인 문법을 사용합니다. 헤르메스는 시스템 프롬프트를 통해 이 제한을 인지하고 답변합니다.
  • 글자 수 제한: 메시지당 4000자로 제한되며, 긴 답변은 에이전트가 자동으로 분할해서 보냅니다.
  • 스레드(Thread): 사용자가 스레드 안에서 답장하면 헤르메스도 이를 감지하고 해당 스레드 내에서 별도의 세션을 유지하며 답변합니다.

📎 9단계: 네이티브 파일 첨부 (Step 10, 선택사항)

헤르메스가 텍스트뿐만 아니라 실제 파일 위젯으로 파일을 보내게 하려면 추가 설정이 필요합니다.

  1. 왜 필요한가요?: 서비스 계정은 구글 챗의 파일 업로드 엔드포인트를 직접 사용할 수 없습니다. 따라서 봇이 ‘사용자’로서 파일을 올리도록 OAuth 권한을 부여해야 합니다.

  2. 호스트 설정: GCP 콘솔에서 ‘데스크톱 앱’용 OAuth 클라이언트 ID를 생성하고 JSON을 다운로드합니다.

  3. 권한 부여: 채팅창에서 /setup-files start 명령어를 입력하고 안내되는 URL을 통해 권한을 승인합니다.

🏁 마치며: 마법사와 함께하는 업무 자동화

이제 헤르메스는 구글 챗 안에서 여러분의 든든한 파트너가 되었습니다. 직접 겪은 시행착오가 담긴 이 가이드가 여러분의 AI 에이전트 여정에 밝은 등불이 되길 바랍니다! ✨

더 자세한 기술적 세부 사항은 아래 공식 가이드를 참고해 주세요.

🔗 공식 안내 사이트: Hermes Agent - Google Chat Integration Guide

필진: 신라 (silla)
“기술은 복잡하지만, 그 경험은 공유될 때 가치가 있다”고 믿습니다. 헤르메스와 함께 더 창의적인 하루를 만드세요!

🏛️

필진: 신라

교육, 노동, 사회 시스템 전반에 걸친 구조적 변화와 시스템 리터러시에 관심이 많으며, AI가 바꾸는 사회 구조에 대한 통찰을 제공합니다.

시스템리터러시 사회구조 교육정책