LightVela 문서

요약

앱은 진입점일 뿐이므로 하나의 에이전트가 여러 메시징 앱에 나타날 수 있습니다. 실제 작업 주체는 에이전트입니다. 메시지 게이트웨이는 세 가지 역할을 합니다. Telegram, WhatsApp, Discord, Slack, WeChat 등 구조가 서로 다른 메시지를 하나의 요청 형식으로 정규화하고, 플랫폼마다 페르소나와 메모리를 복제하는 대신 연결 구성에 따라 각 요청을 동일한 에이전트로 라우팅하며, 실행이 끝나면 결과를 요청이 들어온 대화로 정확히 돌려보냅니다. 정체성(SOUL.md), 메모리(USER.md, MEMORY.md), 스킬(skills/), 자동 작업은 모두 채널 레이어 외부에 있으므로 Telegram에서 말한 내용은 WhatsApp에서 후속 작업을 할 때도 유지됩니다. 그러나 통합이 무제한을 의미하지는 않습니다. 각 채널에는 고유한 인증 흐름, 메시지 형식, 전달 제한이 있고 지원 채널은 글로벌 지역과 중국 지역에서 서로 다릅니다. 새 채널을 연결한 뒤에는 테스트 메시지를 보내 응답이 예상한 대화로 돌아오는지 확인해야 합니다.

메시지 게이트웨이가 해결하는 문제

하루 동안 에이전트를 사용하는 모습을 떠올려 보세요. Telegram에서 프로젝트 진행 상황을 요약해 달라고 요청한 뒤, 정오에 외출하면서 WhatsApp으로 "아까 언급한 두 번째 선택지의 위험은 무엇이었지?"라고 이어서 묻습니다. 저녁에는 팀 Slack 또는 Discord 채널에 결론을 게시해 달라고 요청합니다.

이 세 번의 대화가 서로 무관한 봇 세 개와 나눈 것처럼 처리된다면, 여러 플랫폼을 연결한 의미가 없습니다. 매번 맥락을 처음부터 설명해야 하기 때문입니다. 필요한 구조는 진입점은 세 개지만 비서는 하나인 형태입니다.

이 문제를 단순히 "API 몇 개를 더 연동하는 일"로 보기 쉽지만, API 연동은 표면에 불과합니다. 핵심은 각 플랫폼의 규칙을 지키면서도 모든 진입점이 같은 정체성과 맥락에 연결되게 하는 것입니다. 메시지 게이트웨이는 이 두 요구를 함께 해결하는 레이어입니다.

1. 먼저 짚고 갈 점: 채널은 에이전트가 아닙니다

이 구분을 이해해야 나머지 구조도 정확히 파악할 수 있습니다.

사람들은 본능적으로 "내 Telegram 봇"을 독립형 개체로 취급하며, 이는 자연스럽게 "내 WhatsApp 봇은 다른 봇인가요?"라는 질문을 제기합니다. 채널이 주제가 아닌 진입점으로 이해되면 질문이 해소됩니다.

전체 경로는 다음과 같습니다.

Messaging apps (multiple entry points)
    ↓  platform-native messages
Message gateway (normalise / route / deliver)
    ↓  unified request
The same Hermes Agent
    ↓
model inference + tool execution + memory recall + skill loading
    ↓  execution result
Message gateway
    ↓  delivered in platform format
Original conversation on the original channel

마지막 단계는 원본 채널의 원래 대화입니다. 그것은 각주가 아닙니다. 이는 아래에서 다루는 게이트웨이가 정확히 맞아야 하는 핵심 문제 중 하나입니다.

2. 게이트웨이 역할 1: 수신과 정규화

플랫폼은 거의 모든 측면에서 다릅니다.

• 다른 사용자 식별자 — 숫자 ID, 전화번호 또는 플랫폼 내부 사용자 이름.
• 다른 대화 식별자 — 직접 메시지, 그룹, 채널 및 스레드는 각각 다르게 표시됩니다.
• 다양한 메시지 구조 — 텍스트, 이미지, 음성, 파일, 인용된 답변 및 반응은 모두 고유한 필드 디자인을 가지고 있습니다.
• 다른 이벤트 모델 — 일부는 웹후크를 통해 푸시되고 일부는 지속적인 연결 또는 폴링이 필요합니다.

에이전트가 이러한 차이점에 직접 직면했다면 플랫폼별 분기는 코어를 통해 확산될 것이며 모든 새로운 플랫폼은 코어 로직을 건드리는 것을 의미할 것입니다. 정규화는 이러한 차이를 게이트웨이로 제한합니다. 플랫폼 기반 메시지는 하나의 균일한 요청이 되므로 에이전트는 ​​단일 입력 형태만 이해하면 됩니다.

실질적인 보상: 채널을 추가하는 데 ID, 메모리 또는 스킬 논리를 변경할 필요가 없습니다. 에이전트는 어떤 앱의 필드 레이아웃이 이를 전달하는지가 아니라 질문된 내용에 관심을 갖습니다.

3. 게이트웨이 역할 2: 동일한 에이전트로 라우팅

이 단계 덕분에 여러 플랫폼에서 하나의 페르소나와 맥락을 이어 갈 수 있습니다.

요청이 정규화되면 게이트웨이는 연결 구성을 사용하여 해당 요청이 속한 에이전트를 확인한 다음 해당 에이전트에 요청을 전달합니다. 새로 연결된 플랫폼에서 메시지가 도착했다고 해서 새로운 개성이나 메모리 매장이 생기지는 않습니다.

이는 장기 자산을 공유할지 또는 조각화할지 결정하기 때문에 중요합니다.

이들 모두는 채널 레이어 외부에 있기 때문에 "내가 Telegram에서 언급한 프로젝트 이름을 여전히 알고 있습니다"는 누군가가 구축해야 했던 동기화 기능이 아닙니다. 복사본이 하나만 있기 때문에 자연스러운 결과입니다.

이는 "모델을 전환해도 메모리가 손실되지 않는다"는 설명과 같은 분리 원리입니다. 변동이 잦은 액세스 레이어를 안정적인 자산 레이어와 분리합니다. 이 논리를 모델 관점에서 설명한 내용은 "Hermes Agent의 두뇌를 교체할 수 있습니까? 모델 레이어 대 에이전트 레이어"를 참조하세요.

4. 게이트웨이 역할 3: 원래 대화로 응답 전달

에이전트가 작업을 마치면 게이트웨이는 결과를 원래 대화로 돌려보냅니다. 이 전달 과정은 세 가지 대상을 동시에 정확히 식별해야 하므로 생각보다 까다롭습니다.

1. 어떤 플랫폼인가 — Telegram에서 온 메시지는 WhatsApp이 아니라 Telegram으로 돌아가야 합니다.
2. 어떤 대화 — 하나의 플랫폼에서 직접 메시지와 여러 그룹 및 채널을 가질 수 있습니다. 잘못된 대화에 답하는 것은 단순히 어색한 일이 아닙니다. 그룹 상황에서는 정보가 유출될 수 있습니다.
3. 어떤 형식 — 플랫폼은 메시지 길이 제한, 마크다운 지원, 이미지 및 파일 전송 방법, 인용된 답변 존재 여부가 다릅니다. 동일한 콘텐츠라도 플랫폼별로 다른 표현이 필요합니다.

두 번째 점은 강조할 가치가 있습니다. 잘못된 전달 대상은 다중 채널 설정에서 가장 심각도가 높은 문제 클래스입니다: 비공개 콘텐츠가 그룹에 게시되거나 한 팀의 결론이 다른 팀의 채널로 전송됩니다. 이것이 바로 새로 연결된 모든 채널을 먼저 안전한 대화에서 테스트 메시지로 확인해야 하는 이유입니다.

5. 통합에도 채널별 경계가 있습니다

"하나의 에이전트, 여러 진입점"이라는 구조가 모든 플랫폼이 똑같이 동작한다는 뜻은 아닙니다. 각 채널에는 고유한 제약이 있으며, 에이전트를 공유해도 그 제약은 사라지지 않습니다.

5.1 권한의 차이

각 플랫폼에는 고유한 연결 흐름과 자격 증명 형태가 있습니다. 일부는 개발자 포털에서 봇을 생성하고 토큰을 복사해야 하고, 일부는 QR 코드를 스캔해야 하고, 일부는 AppID 및 AppSecret이 필요합니다. 즉, 각 채널을 연결하는 것은 독립적인 인증 단계입니다. 한 번의 설정으로 모든 것을 다룰 수는 없습니다.

5.2 지원 채널은 지역마다 다릅니다

문서를 읽을 때 놓치기 쉬운 부분입니다. LightVela의 글로벌 지역과 중국 지역은 지원하는 채널이 서로 다릅니다. 글로벌 채널의 우선순위는 Telegram, WhatsApp, Discord, Slack, WeChat, QQ, WeCom, Lark이며, 중국 지역은 WeChat, QQ, WeCom, Lark, DingTalk를 지원합니다.

따라서 "Telegram이 지원됩니다"와 같은 주장이 표시되면 그것이 전달된다고 가정하기보다는 적용되는 지역을 확인하십시오.

5.3 그룹 대화와 다이렉트 메시지는 다릅니다

다이렉트 메시지에서는 에이전트가 한 사람을 상대하지만 그룹에서는 여러 사람을 상대합니다. 따라서 언제 답하고 언제 침묵할지, 공개 대화에서 다루면 안 되는 내용은 무엇인지, 누가 민감한 작업을 승인할 수 있는지를 추가로 정해야 합니다. 이는 행동 규칙과 권한 설계의 영역이며 게이트웨이가 자동으로 결정할 수 없습니다.

5.4 채널마다 전달 기능이 다릅니다

메시지 길이 제한, 서식 지원, 파일 전송, 특정 메시지 인용 기능에 따라 출력 방식이 달라집니다. Discord에서는 잘 표시되는 긴 답변도 다른 채널에서는 나누거나 단순화해야 할 수 있습니다.

6. 새로운 채널 연결을 위한 실제 순서

위 원칙을 실제 연결 절차로 옮기면 다음 순서로 대부분의 문제를 미리 막을 수 있습니다.

1. 지역별 지원 확인 — 해당 지역에서 채널을 사용할 수 있는지 확인하여 다른 문서에 대해 작성된 문서를 따르지 마십시오.
2. 플랫폼 측 전체 인증 — 채널 가이드에 따라 봇을 생성하거나 액세스 권한을 부여하고 자격 증명을 얻습니다. 자격 증명은 민감합니다. 장기 컨텍스트 파일에 기록하거나 채팅에 붙여넣지 마십시오.
3. 제품 측에서 연결 — 자격 증명을 입력하고 저장한 후 상태가 연결됨으로 표시되는지 확인합니다.
4. 테스트 메시지 보내기 — 안전한 대화(직접 메시지 또는 테스트 그룹)를 사용하고 에이전트 응답을 확인합니다.
5. 전송 대상 확인 — 특히 다른 대화가 아닌 메시지를 보낸 동일한 대화에 답장이 도착했는지 확인하세요.
6. 공유된 메모리 확인 — 다른 채널에서 말한 내용에 대해 물어보세요. 정답은 이 채널이 실제로 동일한 에이전트로 라우팅된다는 것을 증명합니다.
7. 그런 다음에만 그룹 액세스를 추가하세요 — 다이렉트 메시지를 확인한 후 그룹에 가입하고 그룹 내 응답 경계가 예상대로 작동하는지 확인하세요.

6단계는 대부분의 사람들이 건너뛰는 단계이며 가장 큰 가치를 지닌 단계입니다. 이는 채널이 에이전트를 실제로 공유하는지 확인하는 가장 직접적인 방법입니다.

7. 일반적인 증상과 진단 방법

세 번째 행은 주의를 기울일 가치가 있습니다. 여기에서 "나를 모른다"는 것은 모델 전환 후의 의미와 다른 의미입니다. 모델 전환 후에는 일반적으로 스타일의 차이입니다. 새로 연결된 채널에서는 이 채널이 사용자가 가정한 에이전트를 가리키지 않음을 의미할 가능성이 높습니다. 진단 방법은 동일합니다. 확실히 알아야 할 한 가지 사실에 대해 물어보세요.

8. LightVela의 접근 방식: 플러그형 진입점으로서의 채널

Hermes는 시스템 구조에서 채널과 에이전트를 분리하지만, 각 플랫폼을 연결하려면 여전히 자격 증명, 콜백, 런타임을 직접 관리해야 합니다. LightVela는 이 채널 레이어를 제품 안에서 연결할 수 있는 진입점으로 제공하는 방향을 취합니다.

• 채널은 설정입니다. 플랫폼별로 별도의 에이전트를 만들 필요 없이 하나의 에이전트에서 연결하거나 연결을 끊습니다.
• 자산은 기본적으로 공유됩니다 — 하나의 성격, 메모리, 스킬 세트 및 자동 작업 세트; 새로운 채널은 ​​마이그레이션할 필요 없이 즉시 재사용합니다.
• 연결 상태 표시 — 콘솔에 채널이 연결되었는지 여부가 표시되므로 "성공적으로 연결되지 않음"과 "연결되었지만 응답하지 않음"을 쉽게 구별할 수 있습니다.
• 지역적 차이는 명백합니다 - 글로벌 및 중국 지역은 각각 자체적으로 지원되는 채널을 나열하여 지역 간 실수를 방지합니다.
• 문제는 추적 가능 - 진단의 최근 로그는 승인 문제와 전달 문제, 작업 문제를 구분하는 데 도움이 됩니다.

핵심 요약

• 채널은 메시지가 드나드는 진입점이고, 실제 작업 주체는 에이전트입니다. 여러 채널이 플랫폼별로 별도 봇을 두는 대신 하나의 에이전트를 공유할 수 있습니다.
• 게이트웨이는 세 가지 작업을 수행합니다. 플랫폼 차이를 정규화하고, 동일한 에이전트로 라우팅하며, 원래 대화로 다시 전달합니다.
• ID, 메모리, 스킬 및 자동 작업은 채널 레이어 외부에 있으므로 채널 간 연속성은 추가된 동기화 기능이 아니라 아키텍처상의 결과입니다.
• 통합이 무제한을 뜻하지는 않습니다. 인증 방식, 지역별 지원 범위, 그룹 대화 규칙, 전달 제한은 채널마다 다릅니다.
• 채널을 연결한 후 두 가지를 확인하세요. 즉, 응답이 예상되는 대화에 들어가는지, 그리고 실제로 동일한 메모리를 공유하는지 확인하세요.