mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-31 04:45:23 +08:00
313 lines
9.6 KiB
Markdown
313 lines
9.6 KiB
Markdown
# プラグイン共通API
|
|
|
|
LangBotは、プラグインがさまざまなLangBotモジュールを操作し、メッセージコンテキストを制御するための一連のAPIを提供します。
|
|
|
|
:::info 目次
|
|
[[toc]]
|
|
:::
|
|
|
|
## リクエストAPI
|
|
|
|
現在処理中のユーザーリクエスト(メッセージ)に対する操作です。`EventListener`と`Command`コンポーネントでのみ使用可能です。アクセス方法:
|
|
|
|
- `EventListener`のイベントハンドラメソッド内: `event_context: context.EventContext`オブジェクトの内部メソッド
|
|
- `Command`のサブコマンドハンドラメソッド内: `context: ExecuteContext`オブジェクトの内部メソッド
|
|
|
|
### 直接返信メッセージ
|
|
|
|
現在のリクエストが存在するセッションにメッセージチェーンで直接返信します。
|
|
|
|
メッセージチェーンの構築方法については、[メッセージプラットフォームエンティティ](/en/plugin/dev/apis/messages)を参照してください。
|
|
|
|
```python
|
|
async def reply(
|
|
self, message_chain: platform_message.MessageChain, quote_origin: bool = False
|
|
):
|
|
"""メッセージリクエストに返信する
|
|
|
|
Args:
|
|
message_chain (platform.types.MessageChain): LangBotメッセージチェーン
|
|
quote_origin (bool): 元のメッセージを引用するかどうか
|
|
"""
|
|
|
|
# 使用例
|
|
await event_context.reply(
|
|
platform_message.MessageChain([
|
|
platform_message.Plain(text="Hello, world!"),
|
|
]),
|
|
)
|
|
```
|
|
|
|
### Bot UUIDの取得
|
|
|
|
現在のリクエストを発行したBotのUUIDを取得します。
|
|
|
|
```python
|
|
async def get_bot_uuid(self) -> str:
|
|
"""Bot UUIDを取得する"""
|
|
|
|
# 使用例
|
|
bot_uuid = await event_context.get_bot_uuid()
|
|
```
|
|
|
|
### リクエスト変数の設定
|
|
|
|
単一のリクエスト内の一部の情報は、リクエスト変数に保存されます。Difyなどの外部LLMOpsプラットフォームを使用する場合、[これらの変数はLLMOpsプラットフォームに明示的に渡されます](/en/deploy/pipelines/readme.html#request-variables)。
|
|
|
|
```python
|
|
async def set_query_var(self, key: str, value: Any):
|
|
"""クエリ変数を設定する"""
|
|
|
|
# 使用例
|
|
await event_context.set_query_var("key", "value")
|
|
```
|
|
|
|
### リクエスト変数の取得
|
|
|
|
単一のリクエスト変数を取得します。
|
|
|
|
```python
|
|
async def get_query_var(self, key: str) -> Any:
|
|
"""クエリ変数を取得する"""
|
|
|
|
# 使用例
|
|
query_var = await event_context.get_query_var("key")
|
|
```
|
|
|
|
### すべてのリクエスト変数の取得
|
|
|
|
```python
|
|
async def get_query_vars(self) -> dict[str, Any]:
|
|
"""すべてのクエリ変数を取得する"""
|
|
|
|
# 使用例
|
|
query_vars = await event_context.get_query_vars()
|
|
```
|
|
|
|
## LangBot API
|
|
|
|
これらのAPIは、任意のプラグインコンポーネントで呼び出すことができます。アクセス方法:
|
|
|
|
- プラグインルートディレクトリの`main.py`内: `self`オブジェクトの内部メソッド。これらのAPIはすべて、プラグインクラスの親クラス`BasePlugin`によって提供されます。
|
|
- 任意のプラグインコンポーネントクラス内: `self.plugin`オブジェクトの内部メソッド。
|
|
|
|
### プラグイン設定の取得
|
|
|
|
プラグイン設定フォーマットは`manifest.yaml`に記述でき、ユーザーはLangBotのプラグイン管理でプラグイン設定フォーマットに従って入力する必要があります。プラグインコードはこのAPIを呼び出してプラグイン設定情報を取得できます。
|
|
|
|
```python
|
|
def get_config(self) -> dict[str, typing.Any]:
|
|
"""プラグインの設定を取得する。"""
|
|
|
|
# 使用例
|
|
config = self.plugin.get_config()
|
|
```
|
|
|
|
### LangBotバージョンの取得
|
|
|
|
LangBotのバージョン番号を取得します。`v<major>.<minor>.<patch>`形式の文字列として返されます。
|
|
|
|
```python
|
|
async def get_langbot_version(self) -> str:
|
|
"""LangBotバージョンを取得する"""
|
|
|
|
# 使用例
|
|
langbot_version = await self.plugin.get_langbot_version()
|
|
```
|
|
|
|
### 設定済みBotリストの取得
|
|
|
|
すべてのBot UUIDのリストを返します。
|
|
|
|
```python
|
|
async def get_bots(self) -> list[str]:
|
|
"""すべてのBotを取得する"""
|
|
|
|
# 使用例
|
|
bots = await self.plugin.get_bots()
|
|
```
|
|
|
|
### Bot情報の取得
|
|
|
|
Bot情報を取得します。
|
|
|
|
```python
|
|
async def get_bot_info(self, bot_uuid: str) -> dict[str, Any]:
|
|
"""Bot情報を取得する"""
|
|
|
|
# 使用例
|
|
bot_info = await self.plugin.get_bot_info("de639861-be05-4018-859b-c2e2d3e0d603")
|
|
|
|
# 返り値の例
|
|
{
|
|
"uuid": "de639861-be05-4018-859b-c2e2d3e0d603",
|
|
"name": "aiocqhttp",
|
|
"description": "Migrated from LangBot v3",
|
|
"adapter": "aiocqhttp",
|
|
"enable": true,
|
|
"use_pipeline_name": "ChatPipeline",
|
|
"use_pipeline_uuid": "c30a1dca-e91c-452b-83ec-84d635a30028",
|
|
"created_at": "2025-05-10T13:53:08",
|
|
"updated_at": "2025-08-12T11:27:30",
|
|
"adapter_runtime_values": { # Botが現在実行中の場合に存在
|
|
"bot_account_id": 960164003 # BotアカウントID
|
|
}
|
|
}
|
|
```
|
|
|
|
### プロアクティブメッセージの送信
|
|
|
|
Bot UUIDとターゲットセッションIDを通じてプロアクティブメッセージを送信します。
|
|
|
|
メッセージチェーンの構築方法については、[メッセージプラットフォームエンティティ](/en/plugin/dev/apis/messages)を参照してください。
|
|
|
|
```python
|
|
async def send_message(
|
|
self,
|
|
bot_uuid: str,
|
|
target_type: str,
|
|
target_id: str,
|
|
message_chain: platform_message.MessageChain,
|
|
) -> None:
|
|
"""セッションにメッセージを送信する"""
|
|
|
|
# 使用例
|
|
await self.plugin.send_message(
|
|
bot_uuid="de639861-be05-4018-859b-c2e2d3e0d603",
|
|
target_type="person",
|
|
target_id="1010553892",
|
|
message_chain=platform_message.MessageChain([platform_message.Plain(text="Hello, world!")]),
|
|
)
|
|
```
|
|
|
|
### 設定済みLLMモデルリストの取得
|
|
|
|
設定されたすべてのLLMモデルのUUIDのリストを返します。
|
|
|
|
```python
|
|
async def get_llm_models(self) -> list[str]:
|
|
"""すべてのLLMモデルを取得する"""
|
|
|
|
# 使用例
|
|
llm_models = await self.plugin.get_llm_models()
|
|
```
|
|
|
|
### LLMモデルの呼び出し
|
|
|
|
LLMモデルを呼び出し、LLMメッセージを返します。非ストリーミング。
|
|
|
|
```python
|
|
async def invoke_llm(
|
|
self,
|
|
llm_model_uuid: str,
|
|
messages: list[provider_message.Message],
|
|
funcs: list[resource_tool.LLMTool] = [],
|
|
extra_args: dict[str, Any] = {},
|
|
) -> provider_message.Message:
|
|
"""LLMモデルを呼び出す"""
|
|
|
|
# 使用例
|
|
llm_message = await self.plugin.invoke_llm(
|
|
llm_model_uuid="llm_model_uuid",
|
|
messages=[provider_message.Message(role="user", content="Hello, world!")],
|
|
funcs=[],
|
|
extra_args={},
|
|
)
|
|
```
|
|
|
|
### プラグイン永続データの設定
|
|
|
|
プラグインデータを永続的に保存します。このインターフェースを通じて保存されたデータは、このプラグインのみがアクセスできます。値は手動でbytesに変換する必要があります。
|
|
|
|
```python
|
|
async def set_plugin_storage(self, key: str, value: bytes) -> None:
|
|
"""プラグインストレージ値を設定する"""
|
|
|
|
# 使用例
|
|
await self.plugin.set_plugin_storage("key", b"value")
|
|
```
|
|
|
|
### プラグイン永続データの取得
|
|
|
|
```python
|
|
async def get_plugin_storage(self, key: str) -> bytes:
|
|
"""プラグインストレージ値を取得する"""
|
|
|
|
# 使用例
|
|
plugin_storage = await self.plugin.get_plugin_storage("key")
|
|
```
|
|
|
|
### すべてのプラグイン永続データキーの取得
|
|
|
|
```python
|
|
async def get_plugin_storage_keys(self) -> list[str]:
|
|
"""すべてのプラグインストレージキーを取得する"""
|
|
|
|
# 使用例
|
|
plugin_storage_keys = await self.plugin.get_plugin_storage_keys()
|
|
```
|
|
|
|
### プラグイン永続データの削除
|
|
|
|
```python
|
|
async def delete_plugin_storage(self, key: str) -> None:
|
|
"""プラグインストレージ値を削除する"""
|
|
|
|
# 使用例
|
|
await self.plugin.delete_plugin_storage("key")
|
|
```
|
|
|
|
### ワークスペース永続データの取得
|
|
|
|
このインターフェースを通じて保存されたデータは、すべてのプラグインがアクセスできます。値は手動でbytesに変換する必要があります。
|
|
|
|
```python
|
|
async def set_workspace_storage(self, key: str, value: bytes) -> None:
|
|
"""ワークスペースストレージ値を設定する"""
|
|
|
|
# 使用例
|
|
await self.plugin.set_workspace_storage("key", b"value")
|
|
```
|
|
|
|
### ワークスペース永続データの取得
|
|
|
|
```python
|
|
async def get_workspace_storage(self, key: str) -> bytes:
|
|
"""ワークスペースストレージ値を取得する"""
|
|
|
|
# 使用例
|
|
workspace_storage = await self.plugin.get_workspace_storage("key")
|
|
```
|
|
|
|
### すべてのワークスペース永続データキーの取得
|
|
|
|
```python
|
|
async def get_workspace_storage_keys(self) -> list[str]:
|
|
"""すべてのワークスペースストレージキーを取得する"""
|
|
|
|
# 使用例
|
|
workspace_storage_keys = await self.plugin.get_workspace_storage_keys()
|
|
```
|
|
|
|
### ワークスペース永続データの削除
|
|
|
|
```python
|
|
async def delete_workspace_storage(self, key: str) -> None:
|
|
"""ワークスペースストレージ値を削除する"""
|
|
|
|
# 使用例
|
|
await self.plugin.delete_workspace_storage("key")
|
|
```
|
|
|
|
### プラグインファイル型設定フィールドデータの取得
|
|
|
|
```python
|
|
async def get_config_file(self, file_key: str) -> bytes:
|
|
"""設定ファイル値を取得する"""
|
|
|
|
# 使用例
|
|
file_bytes = await self.plugin.get_config_file("key")
|
|
```
|
|
|
|
これは[`file`または`array[file`](/en/plugin/dev/basic-info.html#type-file)型の設定フィールドと組み合わせて使用します。
|