Discord — AI in Your Server | Easy Understand Hermes Agent

Discord — 서버에 AI를 들이다

Hermes Agent를 Discord 서버에 넣고 싶으신가요? 좋은 선택입니다. 이 가이드에서는 Hermes가 초대된 후 어떻게 동작하는지부터 전체 설정 과정, 그리고 중요한 새 헬스 체크 기능까지 알아야 할 모든 것을 안내합니다.

재미있는 부분부터 시작해 볼까요? Discord에서 Hermes와 실제로 대화하는 느낌이 어떤지 말이죠.

서버에서 Hermes는 어떻게 동작하나요?

Hermes는 모든 메시지에 무작정 반응하는 단순한 봇이 아닙니다. 언제, 어디서 말할지를 똑똑하게 판단합니다. 정리하면 다음과 같습니다.

상황	동작 방식
다이렉트 메시지	모든 메시지에 응답합니다. `@멘션`이 필요 없어요. 각 DM은 고유한 비공개 세션을 갖습니다.
서버 채널	기본적으로 `@멘션`으로 호출할 때만 응답합니다. 그 외에는 조용히 있습니다.
자유 응답 채널	태그 없이 사람들이 그냥 대화할 수 있는 채널을 원하시나요? `DISCORD_FREE_RESPONSE_CHANNELS`에 추가하면 Hermes가 모든 메시지에 인라인으로 응답합니다.
스레드	Hermes는 같은 스레드 내에서 응답합니다. 스레드나 상위 채널이 자유 응답 채널이 아니라면 멘션 규칙이 그대로 적용됩니다.
공유 채널	기본적으로 Hermes는 같은 채널에서도 사용자별 대화 기록을 분리합니다. `#research` 채널에서 앨리스와 밥이 대화해도 각자 독립된 세션을 갖게 됩니다.
다른 사람을 멘션한 메시지	누군가 Hermes가 아닌 다른 사용자를 @멘션하면, 봇은 기본적으로 침묵을 유지합니다. 자신을 겨냥하지 않은 대화에 끼어들지 않아요.

프로 팁: 사람들이 그냥 입력만 하면 답을 얻을 수 있는 전용 봇 도움말 채널을 만들고 싶으신가요? 그 채널을 DISCORD_FREE_RESPONSE_CHANNELS에 추가하기만 하면 끝입니다.

게이트웨이 모델: 단순한 웹훅 그 이상

여기서 중요한 점이 하나 있습니다. Discord의 Hermes는 정해진 답변을 날리는 단순한 웹훅이 아닙니다. 모든 메시지는 전체 파이프라인을 거칩니다.

권한 확인 (DISCORD_ALLOWED_USERS)
멘션 / 자유 응답 확인
세션 조회
세션 대화 기록 로드
전체 에이전트 실행 — 도구, 메모리, 슬래시 명령어
Discord로 응답 전송

즉, 모든 응답은 단순한 스크립트가 아닌 Hermes의 전체 지능이 뒷받침됩니다.

세션: 누가 무엇을 공유하나요?

기본적으로 Hermes는 대화를 분리합니다.

각 DM은 고유한 세션을 갖습니다.
각 스레드는 고유한 세션 네임스페이스를 갖습니다.
공유 채널에서 각 사용자는 고유한 세션을 갖습니다.

이 설정은 config.yaml에서 제어합니다.

group_sessions_per_user: true

방 전체가 하나의 공유 대화를 원한다면(협업 공간에 유용), false로 설정하세요.

group_sessions_per_user: false

하지만 주의하세요: 공유 세션은 컨텍스트와 토큰 비용도 공유한다는 뜻입니다. 한 사람의 길고 도구 사용이 많은 작업이 모든 사람의 컨텍스트를 부풀릴 수 있습니다. 그리고 실행 중간에 누군가 방해하면 방 전체가 혼란에 빠질 수 있습니다.

인터럽트와 동시성

사용자별 세션(기본값)에서는 앨리스가 자신의 요청을 중단시켜도 같은 채널에서 밥의 대화에는 영향을 주지 않습니다. 밥은 자신의 기록을 유지하고, 앨리스도 자신의 기록을 유지하며, 서로 발을 밟지 않습니다.

공유 세션에서는 방 전체가 하나의 “실행 중인 에이전트” 슬롯을 공유합니다. 서로 다른 사람의 후속 메시지가 서로를 중단시키거나 대기열에 쌓일 수 있습니다. 협업에는 재미있지만, 혼란스러울 가능성도 있습니다.

새로운 기능: 게이트웨이 WebSocket 헬스 체크

최근에 개선된 기능 중 알아두면 좋은 것이 있습니다. Discord에는 REST와 게이트웨이 WebSocket이라는 두 가지 별도의 전송 채널이 있습니다. REST 호출이 성공했다고 해서 봇이 실시간 이벤트를 여전히 수신할 수 있다는 뜻은 아닙니다.

이제 Hermes는 다음을 확인하여 게이트웨이 상태를 모니터링합니다.

준비 상태
클라이언트/소켓 종료 상태
소켓 개방 여부
하트비트 ACK 수신 경과 시간
하트비트 지연 시간

설정된 횟수만큼 비정상 샘플이 감지되면 어댑터는 재시도 가능한 치명적 이벤트를 발생시키고 깔끔하게 재연결합니다. 무한 재연결 루프는 없습니다.

임계값은 config.yaml에서 설정합니다.

discord:
  websocket_liveness_interval_seconds: 15
  websocket_liveness_failure_threshold: 2
  websocket_heartbeat_ack_max_age_seconds: 60
  websocket_max_latency_seconds: 30

참고: 기존 liveness_interval_seconds 및 liveness_failure_threshold 이름은 호환성 별칭으로 계속 작동하지만, 더 이상 REST 프로빙을 의미하지는 않습니다.

1단계: Discord 애플리케이션 만들기

Discord 개발자 포털로 이동하여 로그인합니다.
오른쪽 상단의 New Application을 클릭합니다.
애플리케이션 이름을 지정하고(예: “Hermes Agent”) 개발자 서비스 약관에 동의합니다.
Create를 클릭합니다.

General Information 페이지로 이동하게 됩니다. Application ID를 기록해 두세요. 초대 URL을 만드는 데 필요합니다.

2단계: 봇 만들기

왼쪽 사이드바에서 Bot을 클릭합니다.
Discord가 애플리케이션용 봇 사용자를 자동으로 생성합니다. 원하면 사용자 이름을 변경하세요.
Authorization Flow에서 Public Bot을 ON으로 설정합니다. Discord 제공 초대 링크에 필요합니다.

이것으로 기본 준비가 끝났습니다. 이제부터 봇 토큰을 가져오고, 환경 변수를 설정하고, Hermes를 서버에 초대하면 됩니다. 어느새 여러분의 AI 어시스턴트가 Discord 안에 있을 거예요 — 실시간으로 대화하고, 도구를 사용하고, 컨텍스트를 기억하면서 말이죠.