プラットフォーム API

ボット UUID を指定してプラットフォームアダプターの API を呼び出します。メッセージチェーンの送信は self.plugin.send_message()、グループやユーザーの取得などは以下を使用します。

メッセージ送信、返信、スレッド

標準の send_message API は MessageResult を返します。プラットフォームがメッセージ ID を提供する場合、message_id は送信したメッセージを識別します。self.plugin.send_message() はシリアライズされた辞書を返すため、オブジェクト属性ではなく result["message_id"] を参照します。プラットフォームが ID を返さない場合、この値は None または空文字列になります。

メッセージチェーン内の返信やスレッド参照には、標準の Quote コンポーネントを使います。Quote.id は参照先メッセージまたはスレッドのルートメッセージの ID、origin は引用元のメッセージチェーンで、空でも構いません。対応状況と返信／スレッドの動作はアダプターによって異なります。たとえば Slack はメッセージの ts を message_id として返し、Quote(id=ts) を含むチェーンをそのスレッドに送信します。受信したチャンネルのスレッド返信には、末尾に Quote(id=thread_ts) が追加されます。これは Slack 固有のアクションではなく、標準メッセージ API を使います。

from langbot_plugin.api.entities.builtin.platform.message import MessageChain, Plain, Quote

result = await self.plugin.send_message(
    bot_uuid=bot_uuid,
    target_type="group",
    target_id=group_id,
    message_chain=MessageChain([Plain(text="Support request")]),
)
message_id = result.get("message_id") if result else None
if message_id is not None and message_id != "":
    await self.plugin.send_message(
        bot_uuid=bot_uuid,
        target_type="group",
        target_id=group_id,
        message_chain=MessageChain([
            Plain(text="Follow-up"),
            Quote(id=message_id, origin=MessageChain([])),
        ]),
    )

同じボット、同じ会話のメッセージ ID を使ってください。Quote はシリアライズ時に参照メタデータを保持しますが、str(message_chain) にはテキストを追加しないため、コマンドやキーワードの照合に影響しません。

プラットフォーム API の呼び出し

async def call_platform_api(
    self,
    bot_uuid: str,
    action: str,
    params: dict[str, Any] | None = None,
) -> Any:
    ...

Command、EventListener、Tool などのコンポーネントでは self.plugin から呼び出します。戻り値は操作に応じた辞書、リスト、スカラー、None で、プラットフォーム SDK のオブジェクトではありません。

group = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="get_group_info",
    params={"group_id": "123456"},
)

bot_uuid は await self.plugin.get_bots()、またはパイプラインイベントの await event_context.get_bot_uuid() で取得できます。プラットフォーム ID には実際のイベントや設定の値を使用します。

主な操作

対応する操作はプラットフォームごとに異なり、ボットの管理者権限が必要な場合があります。duration は秒数で、0 の意味はプラットフォームに依存します。共通の永久ミュート値ではありません。取得結果がキャッシュに依存することもあります。ボットが未起動、未対応の操作、引数不正の場合は例外になります。

プラットフォーム固有の API

外側の action を call_platform_api にし、params にプラットフォームの操作と引数を指定します。OneBot Omni でボットのアカウント情報を取得する例です：

account = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="call_platform_api",
    params={"action": "get_login_info", "params": {}},
)

アダプターが宣言した操作のみ呼び出せます。すべてのプラットフォーム API を任意に転送できるわけではありません。プラグインはランタイム経由でホストを呼び出し、ctx.query.adapter や adapter.bot には直接アクセスしません。

Runner

Runner の実行中、self.plugin によるモデル、ツール、ナレッジベース、ストレージ、プラットフォーム呼び出しは現在の実行と権限に自動的に関連付けられます。run_id の指定は不要です。同時実行は互いに分離されます。ハンドラー終了後に実行に紐づく API を呼び続けないでください。

現在のボットは await ctx.get_bot_uuid() で取得します。プラットフォーム呼び出しは今回のツール権限に従い、イベント対象だけが許可されている場合は別の対象を指定できません。プラットフォーム固有の操作を含む未許可の操作は拒否されます。デバッグではこれらの呼び出しも Mock を使用します。

tools = await ctx.get_available_tools()
if any(tool["name"] == "event_get_actor" for tool in tools):
    actor = await ctx.call_tool("event_get_actor")
    await ctx.log(str(actor))