LightVelaドキュメント

概要

**1つのエージェントは、アプリは単なる入り口に過ぎないため、複数のメッセージングアプリで表示されることがあります — 実際に機能するのはエージェントです。メッセージゲートウェイの役割は3つあります：Telegram、WhatsApp、Discord、Slack、WeChatなどからの構造的に異なるメッセージを1つのリクエスト形式に正規化すること；接続設定に基づいて各リクエストを同じエージェントにルーティングすること（プラットフォームごとに人格や記憶を複製するのではなく）；そして実行後、結果を元の会話に正確に届けることです。なぜなら、アイデンティティ（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. ゲートウェイの第一の仕事：受信と正規化

プラットフォームはほぼあらゆる側面で異なります：

• 異なるユーザー識別子 — 数値ID、電話番号、またはプラットフォーム内のユーザー名。
• 異なる会話識別子 — ダイレクトメッセージ、グループ、チャネル、スレッドはそれぞれ異なる方法で表されます。
• 異なるメッセージ構造 — テキスト、画像、音声、ファイル、引用返信、リアクションにはそれぞれ独自のフィールド設計があります。
• 異なるイベントモデル — 一部はウェブフックを通じてプッシュされ、他は永続的な接続やポーリングが必要です。

エージェントがこれらの違いに直接直面すると、プラットフォーム固有の分岐がコア全体に広がり、新しいプラットフォームごとにコアロジックに手を加える必要があります。正規化によってこれらの差異がゲートウェイに封じ込められるため、プラットフォームネイティブのメッセージは1つの統一されたリクエストとなり、エージェントは単一の入力形式だけを理解すればよくなります。

実際的な利点: チャネルを追加しても、ID、メモリ、スキルのロジックを変更する必要はありません。 エージェントが関心を持つのは、どのアプリのフィールド配置で伝えられたかではなく、何が要求されたかです。

3. ゲートウェイの仕事その二: 同じエージェントにルーティングする

これは「プラットフォーム間で一つの人格」を可能にするステップです。

リクエストが正規化されると、ゲートウェイはあなたの接続設定を使ってどのエージェントに属するかを決定し、リクエストをそのエージェントに渡します。新しいプラットフォームからメッセージが届いたからといって、新しい人格やメモリストアを立ち上げることはありません。

これは、長期資産が共有されるか分散されるかを決定するため重要です：

これらはすべてチャネル層の外にあるため、"Telegramで私が言及したプロジェクト名をまだ知っている"というのは、誰かが構築しなければならない同期機能ではなく、唯一のコピーしか存在しないことの自然な結果です。

これは、"モデルを切り替えても記憶を失わない"という論理と同じ切り離しの概念です：揮発性アクセス層を安定したアセット層から分離する。 モデル側のこの議論のバージョンについては、"Hermes Agentのブレインは置き換え可能か？モデル層 vs エージェント層"を参照してください。

4. ゲートウェイの仕事3：正しい場所に返す

エージェントが作業を終えると、ゲートウェイは結果を送り返します。「送り返す」というのは意外と難しく、次の3つの質問に同時に正しく答える必要があります：

1. どのプラットフォームか — TelegramからのメッセージはTelegramに戻る必要があり、WhatsAppには戻りません。
2. どの会話か — 1つのプラットフォーム上で、ダイレクトメッセージや複数のグループ、チャンネルを持つことがあります。間違った会話に返信すると、単に気まずいだけでなく、グループの文脈では情報漏洩につながる可能性があります。
3. フォーマット — プラットフォームによってメッセージの長さ制限、Markdownのサポート、画像やファイルの送信方法、引用返信の有無が異なります。同じコンテンツでも、プラットフォームごとに異なる表示が必要です。

第2のポイントは強調に値します。誤った送信先はマルチチャネル環境における最も重大な問題のクラスです：グループに投稿されたプライベートコンテンツや、あるチームの結論が別のチームのチャンネルに送信される場合などです。だからこそ、新しく接続されたチャンネルは、まず安全な会話でテストメッセージを使って確認する必要があります。

5. 統合されたからといって無制限を意味するわけではありません

「1つのエージェント、複数のエントリーポイント」という表現は、簡単に「すべてのプラットフォームは同じように動作する」と過剰に解釈されがちです。実際には各チャネルは独自の制約を保持しており、エージェントを共有してもそれらはなくなりません。

5.1 承認の違い

各プラットフォームには独自の接続フローと資格情報形式があります：あるものは開発者ポータルでボットを作成してトークンをコピーすることを要求し、あるものはQRコードのスキャンを必要とし、あるものはAppIDとAppSecretを必要とします。言い換えれば、各チャネルの接続は独立した承認手順であり、1つの設定で全てをカバーすることはできません。

5.2 サポートされるチャネルは地域によって異なる

これはドキュメントを読む際の簡単な落とし穴です：LightVelaのグローバルおよび中国地域では、同じチャネルセットがサポートされていません。グローバルのチャネル順序はTelegram、WhatsApp、Discord、Slack、WeChat、QQ、WeCom、Larkです。中国地域ではWeChat、QQ、WeCom、Lark、DingTalkがサポートされています。

したがって、「Telegramがサポートされている」という主張を見たときには、適用される地域を確認し、それが共通であると仮定しないようにしてください。

5.3 グループコンテキストはダイレクトメッセージとは異なります

ダイレクトメッセージでは、エージェントは1人の相手に対応します。グループでは、多くの相手に対応します。グループでは質問が追加されます：いつ応答すべきか、いつ沈黙すべきか、公開するのに不適切な内容は何か、誰が敏感な操作を起動できるか。これらは行動規範や許可設計に属するものであり、ゲートウェイが自動的に決定することはできません。

5.4 配信能力は異なる

メッセージの長さ制限、リッチテキストのサポート、ファイル送信、特定のメッセージを引用する能力は、すべて出力に影響します。Discordで正常に表示される長い返信でも、他の場所では分割や簡略化が必要になることがあります。

6. 新しいチャンネルを接続するための実用的な手順

上記の原則を手順に変換すると、この手順でほとんどの問題を回避できます。

1. 地域のサポートを確認する — チャンネルが自分の地域で利用可能か確認し、他の地域向けに書かれたドキュメントに従わないようにします。
2. プラットフォーム側の認証を完了する — そのチャンネルのガイドに従い、ボットを作成するかアクセス権を付与し、認証情報を取得します。認証情報は機密情報です：長期的なコンテキストファイルに書き込んだり、チャットに貼り付けたりしないでください。
3. 製品側で接続 — 資格情報を入力し、保存して、ステータスが接続済みになっていることを確認します。
4. テストメッセージを送信 — 安全な会話（ダイレクトメッセージやテストグループ）を使用し、エージェントが返信することを確認します。
5. 配信先を確認 — 返信が自分がメッセージを送信したのと同じ会話に届いているか、他の会話ではないかを特に確認します。
6. 共有メモリを確認 — 別のチャンネルで伝えたことについて質問します。正しい答えが返ってくれば、このチャンネルが本当に同じエージェントにルーティングされていることを証明します。
7. その後にのみグループアクセスを追加 — ダイレクトメッセージを確認した後、グループに参加し、グループ内の応答範囲が期待通りに機能することを確認してください。

ステップ6はほとんどの人がスキップしますが、最も価値があります：チャネルが実際に1つのエージェントを共有していることを確認する最も直接的な方法です。

7. 一般的な症状とその読み方

3行目に注意が必要です：「私のことを知らない」は、モデルを切り替えた後の場合とは意味が異なります。 モデルを切り替えた後は通常スタイルの違いですが、新しく接続されたチャネルの場合は、このチャネルがあなたが想定したエージェントを指していない可能性が高いです。診断方法は同じで、確実に知っているはずの事実について質問します。

8. LightVela のアプローチ：チャネルをプラグ可能なエントリーポイントとして扱う

Hermes はメカニズムレベルでチャネルをエージェントから分離していますが、それぞれのプラットフォームを接続するには、依然として認証情報、コールバック、ランタイムを自分で扱う必要があります。LightVela の方向性は、その層を製品化されたプラグ可能なエントリーポイントにすることです：

• チャネルは設定です — 1 つのエージェントの下で接続または切断でき、プラットフォームごとに別のエージェントを作成する必要はありません。
• アセットはデフォルトで共有されます — 1 つのパーソナリティ、メモリ、スキルセット、オートメーションセット；新しいチャネルは即座にそれらを再利用でき、移行するものは何もありません。
• 接続状態が確認可能 — コンソールではチャネルが接続されているかどうかが表示されるため、「一度も正常に接続されなかった」のか「接続はされたが応答していない」のかを簡単に区別できます。
• 地域差が明示 — グローバルおよび中国の各地域はそれぞれサポートされているチャネルを一覧表示し、地域を超えた誤操作を防ぎます。
• 問題の追跡が可能 — 診断の最近のログにより、認証の問題、配信の問題、タスクの問題を区別できます。

主なポイント

• チャネルは入口であり、エージェントが主体です。多くのチャネルは1つのエージェントを共有しており、プラットフォームごとにボットが存在するわけではありません。
• ゲートウェイは三つのことを行います：プラットフォームの違いを標準化し、同じエージェントへルーティングし、元の会話に配信します。
• ID、メモリ、スキル、および自動化はチャネル層の外に存在するため、チャネル間の連続性はアーキテクチャ上の結果であり、追加の同期機能ではありません。
• 統一されているからといって無制限ではありません：認可、地域サポート、グループコンテキスト、および配信制限はチャネルごとに異なります。
• チャネルを接続した後、次の二点を確認してください：返信が期待される会話に届くこと、そして本当に同じメモリを共有していることです。