ワークスペース API

ワークスペース API を使うと、プラグインは自分がインストールされているワークスペースを操作できます。Agent やパイプラインの一覧取得と編集、ボットの参照、モデルやナレッジベースの管理、モニタリングデータの読み取りなどです。公開されている操作は LangBot の HTTP API、MCP サーバー、ワークスペースアシスタントとまったく同じなので、メンバーがそれらで行えることは、メンバーが許可した範囲内でプラグインからも自動化できます。

各操作には pipeline.list や knowledge.base.retrieve のような固定の ID があります。プラグインが呼び出せるのは、マニフェストで宣言し、かつメンバーがそのインストールに許可した操作だけです。

操作を呼び出す

どのコンポーネントからも self.plugin.workspace を使います。各操作には ID に対応した型付きメソッドがあります。

from langbot_plugin.api.definition.components.tool.tool import Tool


class WorkspaceSummary(Tool):
    async def call(self, params, session, query_id):
        result = await self.plugin.workspace.pipeline.list()
        if not result["ok"]:
            return f"パイプラインを取得できませんでした: {result['error']['message']}"

        names = [pipeline["name"] for pipeline in result["result"]]
        return "パイプライン: " + "、".join(names)

メソッドは操作の入力スキーマに対応するキーワード引数を受け取り、エディターでは型と説明が表示されます。一部の名前は Python として有効になるよう調整されます。Python のキーワードと重なる部分には末尾にアンダースコアが付き（例：import_）、その他の無効な文字はアンダースコアに置き換えられます。送信時には元の引数名が使われます。

呼び出す操作を実行時に決めたい場合は、ID を指定して呼び出せます。型付きメソッドとまったく同じように動作します。

result = await self.plugin.workspace.call("knowledge.base.retrieve", kb_uuid=kb_uuid, query="返金ポリシー")

await self.plugin.workspace.list() は、インストールに許可された操作とその入力スキーマを domains ごとにまとめて返します。ツール一覧を動的に組み立てたり、機能を提供する前に許可の有無を確かめたりするのに便利です。

Runner の中で使う

Runner では、実行に紐づいたプロキシを ctx.api.workspace として受け取ります。メソッドも、認可に使われるインストールの許可も同じです。違いは、LangBot が各呼び出しを現在の実行に記録する点です。

実行を開始した Agent やパイプラインが、モデルに見せるワークスペース操作を絞り込んでいる場合があります。その選択は ctx.resources.workspace_operations で渡されます。ワークスペース操作をツールとしてモデルに提供する Runner は、この中の操作だけを提供し、リストが空なら何も提供しないでください。LangBot 組み込みの LocalAgent もそのように動作します。

戻り値とエラー

ワークスペースの呼び出しは、業務上のエラーで例外を送出しません。常に辞書を返します。

# 成功
{"ok": True, "result": ..., "operation": {"id": "pipeline.list", ...}}

# 失敗
{"ok": False, "error": {"code": "permission_denied", "message": "...", "details": {...}}}

result を読む前に ok を確認してください。主なエラーコード：

メンバーは宣言された権限の一部だけを許可することもあるため、権限不足は想定内の結果です。コマンドや実行全体を失敗させるのではなく、何が足りないかを説明してください。

宣言する操作の選び方

各操作にはリスクレベルがあり、メンバーは確認時にそれを目にします。

• 読み取り：データを返すだけの操作。例：pipeline.list、stats.basic。
• 書き込み：ワークスペースの設定を変更する操作。例：pipeline.update、knowledge.file.store。
• 高リスク：リソースの削除、LangBot 外部への影響、大量のリソース消費を伴う操作。例：bot.delete、pipeline.chat.broadcast。確認ダイアログで強調表示されます。

操作を許可するメンバーは、その操作が要求する権限（下の表の最後の列）を自分で持っている必要があります。必要な操作だけを申請してください。高リスクの操作を多数申請すると、拒否されたり削られたりする可能性が高くなります。

knowledge.* のようなワイルドカードで、あるプレフィックス配下の操作をまとめて申請できますが、すべてのプレフィックスで使えるわけではありません。ワイルドカードを参照してください。

操作一覧

現在の LangBot でプラグインが申請できるすべての操作を、ドメインごとに示します。メソッドは workspace.… と表記しています。コンポーネントでは self.plugin.workspace、Runner では ctx.api.workspace です。SDK の型付きメソッドはこのカタログから生成されているため、表のすべての操作がメソッドとして利用できます。

Adapter (adapter)

Agent (agent)

Bot (bot)

Extension (extension)

Knowledge Base (knowledge)

MCP (mcp)

Model (model)

Monitoring (monitoring)

Pipeline (pipeline)

Plugin (plugin)

Model Provider (provider)

Requester (requester)

Skill (skill)

Statistics (stats)

Tool (tool)