Yuanbao

Hermes를 Tencent의 enterprise messaging platform인 Yuanbao에 연결합니다. adapter는 realtime message delivery를 위해 WebSocket gateway를 사용하며 direct(C2C) conversation과 group conversation을 모두 지원합니다.

정보

Yuanbao는 Tencent 및 enterprise environment에서 주로 사용되는 enterprise messaging platform입니다. WebSocket 기반 realtime communication, HMAC-based authentication, image/file/voice message 같은 rich media를 지원합니다.

prerequisites

• bot creation permission이 있는 Yuanbao account
• platform admin에서 받은 Yuanbao APP_ID와 APP_SECRET
• Python package: websockets, httpx
• media support용: aiofiles

필요한 dependency 설치:

pip install websockets httpx aiofiles

setup

1. Yuanbao에서 bot 만들기

1. https://yuanbao.tencent.com/에서 Yuanbao app을 download합니다.
2. app에서 PAI → My Bot으로 이동해 새 bot을 만듭니다.
3. bot 생성 후 APP_ID와 APP_SECRET을 copy합니다.

2. setup wizard 실행

Yuanbao를 설정하는 가장 쉬운 방법은 interactive setup입니다.

hermes gateway setup

prompt가 나오면 Yuanbao를 선택합니다. wizard는 다음을 수행합니다.

1. APP_ID 입력 요청
2. APP_SECRET 입력 요청
3. configuration 자동 저장

팁

WebSocket URL과 API Domain은 합리적인 default가 내장되어 있습니다. 시작하려면 APP_ID와 APP_SECRET만 제공하면 됩니다.

3. environment variable 확인

초기 setup 후 ~/.hermes/.env에서 다음 variable을 확인합니다.

# Required
YUANBAO_APP_ID=your-app-id
YUANBAO_APP_SECRET=your-app-secret
YUANBAO_WS_URL=wss://api.yuanbao.example.com/ws
YUANBAO_API_DOMAIN=https://api.yuanbao.example.com

# Optional: bot account ID (normally obtained automatically from sign-token)
# YUANBAO_BOT_ID=your-bot-id

# Optional: internal routing environment (e.g. test/staging/production)
# YUANBAO_ROUTE_ENV=production

# Optional: home channel for cron/notifications (format: direct:<account> or group:<group_code>)
YUANBAO_HOME_CHANNEL=direct:bot_account_id
YUANBAO_HOME_CHANNEL_NAME="Bot Notifications"

# Optional: restrict access (legacy, see Access Control below for fine-grained policies)
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

4. gateway 시작

hermes gateway

adapter가 Yuanbao WebSocket gateway에 연결하고 HMAC signature로 authenticate한 뒤 message processing을 시작합니다.

features

• WebSocket gateway - realtime bidirectional communication
• HMAC authentication - APP_ID/APP_SECRET을 사용한 secure request signing
• C2C messaging - direct user-to-bot conversation
• Group messaging - group chat conversation
• Media support - COS(Cloud Object Storage)를 통한 image, file, voice message
• Markdown formatting - Yuanbao size limit에 맞춰 message 자동 chunking
• Message deduplication - 같은 message의 duplicate processing 방지
• Heartbeat/keep-alive - WebSocket connection stability 유지
• Typing indicators - agent 처리 중 "typing…" status 표시
• Automatic reconnection - WebSocket disconnection을 exponential backoff로 처리
• Group information queries - group detail과 member list 조회
• Sticker/Emoji support - conversation에 TIMFaceElem sticker와 emoji 전송
• Auto-sethome - bot에게 처음 message를 보낸 user가 home channel owner로 자동 설정됨
• Slow-response notification - agent가 예상보다 오래 걸릴 때 waiting message 전송

configuration options

chat ID formats

Yuanbao는 conversation type에 따라 prefixed identifier를 사용합니다.

Chat Type	Format	Example
Direct message(C2C)	direct:<account>	direct:user123
Group message	group:<group_code>	group:grp456

media uploads

Yuanbao adapter는 COS(Tencent Cloud Object Storage)를 통한 media upload를 자동 처리합니다.

• Images: JPEG, PNG, GIF, WebP 지원
• Files: 일반적인 document type 지원
• Voice: WAV, MP3, OGG 지원

SSRF attack을 방지하기 위해 media URL은 upload 전에 자동으로 validate 및 download됩니다.

home channel

Yuanbao chat(DM 또는 group)에서 /sethome command를 사용해 해당 chat을 home channel로 지정합니다. scheduled task(cron job)의 결과는 이 channel로 전달됩니다.

Auto-sethome

home channel이 설정되어 있지 않으면 bot에게 처음 message를 보낸 user가 자동으로 home channel owner로 설정됩니다. 현재 home channel이 group chat이면 첫 DM이 이를 direct channel로 upgrade합니다.

~/.hermes/.env에 수동으로 설정할 수도 있습니다.

YUANBAO_HOME_CHANNEL=direct:user_account_id
# or for a group:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

예제: home channel 설정

1. Yuanbao에서 bot과 conversation을 시작합니다.
2. command를 보냅니다: /sethome
3. bot이 응답합니다: "Home channel set to [chat_name] with ID [chat_id]. Cron jobs will deliver to this location."
4. 이후 cron job과 notification이 이 channel로 전송됩니다.

예제: cron job delivery

cron job 생성:

/cron "0 9 * * *" Check server status

scheduled output은 매일 오전 9시에 Yuanbao home channel로 전달됩니다.

usage tips

conversation 시작

Yuanbao에서 bot에게 아무 message나 보냅니다.

hello

bot은 같은 conversation thread에서 응답합니다.

available commands

모든 standard Hermes command는 Yuanbao에서 동작합니다.

Command	Description
/new	새 conversation 시작
/model [provider:model]	model 표시 또는 변경
/sethome	현재 chat을 home channel로 설정
/status	session info 표시
/help	사용 가능한 command 표시

file 보내기

bot에게 file을 보내려면 Yuanbao chat에 바로 attachment로 추가하면 됩니다. bot은 file attachment를 자동 download하고 처리합니다.

attachment와 함께 message를 넣을 수도 있습니다.

Please analyze this document

file 받기

bot에게 file 생성 또는 export를 요청하면 bot이 Yuanbao chat으로 file을 직접 보냅니다.

troubleshooting

bot은 online이지만 message에 응답하지 않음

Cause: WebSocket handshake 중 authentication 실패.

Fix:

1. APP_ID와 APP_SECRET이 올바른지 확인합니다.
2. WebSocket URL에 접근 가능한지 확인합니다.
3. bot account에 적절한 permission이 있는지 확인합니다.
4. gateway log를 검토합니다: tail -f ~/.hermes/logs/gateway.log

"Connection refused" error

Cause: WebSocket URL에 접근할 수 없거나 URL이 잘못됨.

Fix:

1. WebSocket URL format을 확인합니다. wss://로 시작해야 합니다.
2. Yuanbao API domain으로 network connectivity를 확인합니다.
3. firewall이 WebSocket connection을 허용하는지 확인합니다.
4. 다음으로 URL을 test합니다: curl -I https://[YUANBAO_API_DOMAIN]

media upload 실패

Cause: COS credential이 invalid이거나 media server에 접근할 수 없음.

Fix:

1. API_DOMAIN이 올바른지 확인합니다.
2. bot에 media upload permission이 enabled되어 있는지 확인합니다.
3. media file에 접근 가능하고 손상되지 않았는지 확인합니다.
4. platform admin과 COS bucket configuration을 확인합니다.

home channel로 message가 전달되지 않음

Cause: home channel ID format이 잘못되었거나 cron job이 아직 trigger되지 않음.

Fix:

1. YUANBAO_HOME_CHANNEL이 올바른 format인지 확인합니다.
2. /sethome command로 올바른 format을 자동 감지합니다.
3. /status로 cron job schedule을 확인합니다.
4. bot이 target chat에 send permission을 갖고 있는지 확인합니다.

잦은 disconnection

Cause: WebSocket connection이 unstable하거나 network가 unreliable함.

Fix:

1. gateway log에서 error pattern을 확인합니다.
2. connection setting에서 heartbeat timeout을 늘립니다.
3. Yuanbao API로 가는 network connection이 안정적인지 확인합니다.
4. verbose logging을 고려합니다: HERMES_LOG_LEVEL=debug

access control

Yuanbao는 DM과 group conversation 모두에 대해 fine-grained access control을 지원합니다.

# DM policy: open (default) | allowlist | disabled
YUANBAO_DM_POLICY=open
# Comma-separated user IDs allowed to DM the bot (only used when DM_POLICY=allowlist)
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2

# Group policy: open (default) | allowlist | disabled
YUANBAO_GROUP_POLICY=open
# Comma-separated group codes allowed (only used when GROUP_POLICY=allowlist)
YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2

config.yaml에서도 설정할 수 있습니다.

platforms:
  yuanbao:
    extra:
      dm_policy: allowlist
      dm_allow_from: "user1,user2"
      group_policy: open
      group_allow_from: ""

advanced configuration

message chunking

Yuanbao에는 maximum message size가 있습니다. Hermes는 Markdown-aware splitting으로 큰 response를 자동 chunk합니다. code fence, table, paragraph boundary를 존중합니다.

connection parameters

다음 connection parameter는 adapter에 sensible default로 내장되어 있습니다.

Parameter	Default Value	Description
WebSocket connect timeout	15 seconds	WS handshake 대기 시간
Heartbeat interval	30 seconds	connection 유지용 ping frequency
Max reconnect attempts	100	최대 reconnection 시도 수
Reconnect backoff	1s → 60s(exponential)	reconnect attempt 사이 대기 시간
Reply heartbeat interval	2 seconds	RUNNING status send frequency
Send timeout	30 seconds	outbound WS message timeout

노트

이 값들은 현재 environment variable로 configure할 수 없습니다. 일반적인 Yuanbao deployment에 맞게 optimize되어 있습니다.

verbose logging

connection issue를 troubleshoot하려면 debug logging을 활성화합니다.

HERMES_LOG_LEVEL=debug hermes gateway

다른 기능과의 통합

cron jobs

Yuanbao에서 실행되는 scheduled task:

/cron "0 */4 * * *" Report system health

결과는 home channel로 전달됩니다.

background tasks

conversation을 block하지 않고 긴 operation을 실행합니다.

/background Analyze all files in the archive

cross-platform messages

CLI에서 Yuanbao로 message를 보냅니다.

hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"

related documentation

• Messaging Gateway Overview
• Slash Commands Reference
• Cron Jobs
• Background Sessions