heremes agent discord연결 원리와 연결방법

요약

• Hermes Agent는 hermes gateway를 통해 Discord 같은 메시징 플랫폼과 연결합니다.
• Discord 쪽에서는 Discord Gateway의 WebSocket 연결로 메시지 이벤트를 받고, Hermes Agent가 만든 응답은 Discord로 다시 전달됩니다.
• 실제 운영에서는 Bot token만으로 충분하지 않습니다. DISCORD_ALLOWED_USERS 또는 DISCORD_ALLOWED_ROLES로 누가 Hermes Agent를 사용할 수 있는지 제한해야 합니다.

 

Hermes Agent와 Discord가 통신하는 원리

Hermes Agent는 메시징 플랫폼과 직접 섞이지 않고 hermes gateway를 중간 계층으로 사용합니다. Hermes 공식 문서에 따르면 gateway는 여러 플랫폼 adapter를 실행하고, adapter는 들어온 메시지를 per-chat session store로 라우팅한 뒤 AI Agent에 전달합니다.

 

Discord는 Discord Gateway API를 통해 앱과 Discord 사이에 안전한 WebSocket 연결을 엽니다. 이 연결은 서버나 채널에서 발생한 이벤트를 앱이 실시간으로 받기 위한 통로입니다. 리소스 생성이나 메시지 전송 같은 대부분의 작업은 HTTP API를 함께 사용한다고 이해하면 됩니다.

 

Hermes Agent를 Discord와 연결하면 메시지는 아래 흐름으로 처리됩니다.

sequenceDiagram
  participant User as Discord 사용자
  participant Discord as Discord Gateway/API
  participant Gateway as Hermes gateway
  participant Agent as Hermes Agent

  User->>Discord: Bot 멘션 또는 DM 전송
  Discord->>Gateway: WebSocket 이벤트 전달
  Gateway->>Gateway: 권한 확인과 session 조회
  Gateway->>Agent: 메시지와 session context 전달
  Agent->>Gateway: 응답 생성
  Gateway->>Discord: 응답 전송
  Discord->>User: 채널 또는 DM에 표시

 

중요한 점은 Hermes Agent의 Discord 연동이 stateless webhook이 아니라는 점입니다. Hermes는 권한 확인, 멘션 규칙, session 조회, transcript 로딩, tool 사용, memory, slash command 실행을 모두 거친 뒤 응답합니다.

 

Discord 연동 방법

아래 절차는 Hermes Agent 공식 Discord 연동 문서를 기준으로 정리했습니다.

 

1. Discord 애플리케이션 생성

Discord Developer Portal에 접속합니다.

 

오른쪽 위의 New Application을 클릭하고, Hermes Agent와 연결할 Discord application을 생성합니다.

 

2. Bot 설정

Application의 왼쪽 메뉴에서 Bot을 클릭합니다. Bot은 Discord에서 사용자가 대화하게 될 대상입니다.

 

Authorization Flow에서 아래 값을 설정합니다.

• Public Bot: ON
• Require OAuth2 Code Grant: OFF

 

Public Bot을 ON으로 두면 Installation 탭에서 Discord Provided Link를 사용할 수 있습니다. Private bot으로 운영하려면 Public Bot을 OFF로 둘 수 있지만, 이 경우 Installation 탭의 자동 초대 링크 대신 수동 OAuth2 URL을 만들어야 합니다.

 

Privileged Gateway Intents에서는 아래 값을 활성화합니다. Message Content Intent가 꺼져 있으면 Bot이 메시지 이벤트를 받아도 메시지 본문을 읽지 못합니다. Server Members Intent가 꺼져 있으면 허용 사용자 확인이나 사용자 이름 해석에서 문제가 생길 수 있습니다.

• Server Members Intent
• Message Content Intent

 

3. Bot token 생성

Bot 페이지의 Token 섹션에서 token을 생성합니다. Bot token은 Hermes Agent가 Discord Bot으로 로그인할 때 사용하는 인증 정보입니다.

 

Token은 외부에 공개하면 안 됩니다. token을 잃어버렸거나 노출되었다면 reset token으로 새 token을 발급해야 합니다.

 

4. Bot 권한 설정

Installation 메뉴에서 Guild Install의 기본 권한을 설정합니다. Hermes Agent가 메시지를 읽고 응답하려면 최소한 아래 권한이 필요합니다. Thread 안에서 답변하게 하려면 Send Messages in Threads 권한도 함께 추가하는 것이 좋습니다.

• View Channels: Bot이 접근 가능한 채널을 볼 수 있습니다.
• Send Messages: 사용자의 메시지에 답장할 수 있습니다.
• Embed Links: rich response를 표시할 수 있습니다.
• Attach Files: 이미지, 오디오, 파일 결과물을 보낼 수 있습니다.
• Read Message History: 대화 context를 유지할 수 있습니다.

 

5. Discord 서버에 Bot 초대

Installation 메뉴에서 Install Link를 복사한 뒤 웹브라우저에서 엽니다.

 

Add to Server를 클릭하고 Bot을 초대할 서버를 선택합니다.

 

권한을 확인한 뒤 Continue와 Authorize를 클릭합니다.

 

6. Discord 사용자 ID 확인

Hermes Agent는 Discord 사용자 ID로 접근 권한을 제어합니다.  Developer Mode를 켠 뒤 사용자 아바타나 사용자 이름을 오른쪽 클릭하면 Copy User ID를 사용할 수 있습니다.

• 경로: Settings → Advanced → Developer Mode → ON

 

7. Hermes Agent 설정

지금까지는 Discord 설정이었습니다. 이제 Hermes Agent 쪽에서 Discord Bot token과 허용 사용자 정보를 등록합니다.

hermes gateway setup

 

Interactive setup에서 Discord를 선택하고 Bot token과 사용자 ID를 입력합니다. 입력한 값은 기본적으로 ~/.hermes/.env에 저장됩니다.

DISCORD_BOT_TOKEN=
DISCORD_ALLOWED_USERS=

 

공식 문서 기준으로 DISCORD_ALLOWED_USERS 또는 DISCORD_ALLOWED_ROLES를 설정하지 않으면 gateway는 사용자를 허용하지 않습니다. 여러 명을 허용하려면 사용자 ID를 쉼표로 구분합니다.

DISCORD_ALLOWED_USERS=xxxxx,xxxxxx

 

팀이나 서버 역할 기준으로 접근을 열고 싶다면 DISCORD_ALLOWED_ROLES를 사용할 수 있습니다. 이때 role 이름이 아니라 role ID를 입력해야 합니다.

DISCORD_ALLOWED_ROLES=xxxxxxx

 

8. 연결 테스트

Discord 서버 채널에서 Bot을 멘션하면 Hermes Agent가 동작합니다. DM에서는 기본적으로 멘션 없이 모든 메시지에 응답합니다.

 

참고자료

• Hermes messaging gateway
• Hermes Discord integration
• Discord Gateway