コンテキスト API

コンテキストには、1 回のコンポーネント呼び出しに関するデータが含まれます。コンポーネントごとに受け取るコンテキストが異なるため、まず対象コンポーネントの入口を確認してください。

コンポーネント	ハンドラーの入口	コンテキスト型
EventListener	`handler(event_context)`	`EventContext`
Command	`subcommand(context)`	`ExecuteContext`
Tool	`call(params, session, query_id)`	独立したコンテキストオブジェクトなし
Runner	`run(ctx)` または `handler(ctx)`	`RunnerContext`
KnowledgeEngine	`ingest(context)`、`retrieve(context)`	`IngestionContext`、`RetrievalContext`
KnowledgeRetriever	`retrieve(context)`	`RetrievalContext`
Parser	`parse(context)`	`ParseContext`
Page	`handle_api(request)`	`PageRequest`

このページでは、コンテキストのデータとメソッドのみを説明します。モデル、ナレッジベース、ストレージなどの LangBot 機能には self.plugin を使用します。詳細は LangBot API を参照してください。プラットフォーム操作はプラットフォーム APIに記載しています。

EventContext、ExecuteContext、Session には instance_uuid、workspace_uuid、placement_generation も含まれます。これらは現在の実行に対応するインスタンスとワークスペースを示すためのもので、プラグイン側の認可情報として使用しないでください。

EventListener

EventListener はパイプラインイベントを処理します。イベントハンドラーは EventContext を受け取ります。

event = event_context.event
sender_id = event.sender_id

コンテキストデータ

プロパティ	型	説明
`event`	`BaseEventModel`	現在のイベントオブジェクト。実際の型は登録したイベント型と一致します
`event_name`	`str`	現在のイベントクラス名
`query_id`	`int`	現在のパイプラインリクエスト ID
`query_uuid`	`str \| None`	現在のパイプラインリクエストの安定した識別子
`eid`	`int`	Plugin Runtime 内の一時的なイベント番号。永続化しないでください
`is_prevent_default`	`bool`	デフォルト処理を停止済みか。変更には `prevent_default()` を使用します
`is_prevent_postorder`	`bool`	後続プラグインを停止済みか。変更には `prevent_postorder()` を使用します

イベントのフィールドと購読可能なイベントはパイプラインイベントを参照してください。

コンテキストメソッド

メソッド	戻り値	説明
`await event_context.reply(message_chain, quote_origin=False)`	-	現在のリクエストの会話に返信
`await event_context.get_bot_uuid()`	`str`	送信元 Bot の UUID を取得
`await event_context.set_query_var(key, value)`	-	現在のリクエストに変数を設定
`await event_context.get_query_var(key)`	`Any`	リクエスト変数を 1 つ取得
`await event_context.get_query_vars()`	`dict[str, Any]`	すべてのリクエスト変数を取得
`await event_context.create_new_conversation()`	`dict[str, Any]`	現在のパイプライン会話をクリアし、後続リクエストで新しい会話を作成
`await event_context.list_pipeline_knowledge_bases()`	`list[dict[str, Any]]`	現在のパイプラインの Local Agent に設定されたナレッジベースを取得
`await event_context.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)`	`list[dict[str, Any]]`	現在のパイプラインに設定されたナレッジベースを検索
`event_context.prevent_default()`	-	現在のイベントのデフォルト処理を停止
`event_context.prevent_postorder()`	-	後続プラグインによる現在のイベント処理を停止

reply() は MessageChain を受け取ります。リクエスト変数、返信、パイプラインのナレッジベース API には、関連付けられたパイプラインリクエストが必要です。retrieve_knowledge() の kb_id は list_pipeline_knowledge_bases() の結果から指定します。

prevent_default() はデフォルトフローを停止できるイベントにのみ作用します。詳細はパイプラインイベントを参照してください。

Command

Command のサブコマンドハンドラーは ExecuteContext を受け取ります。

query = " ".join(context.crt_params)
session = context.session

コンテキストデータ

プロパティ	型	説明
`session`	`Session`	現在のメッセージが属するセッション
`command_text`	`str`	コマンド接頭辞を除いた完全なコマンド文字列
`full_command_text`	`str`	接頭辞を含む完全なコマンド文字列
`command`	`str`	ルートコマンド名
`crt_command`	`str`	現在実行中のサブコマンド名
`params`	`list[str]`	ルートコマンド以降のすべての引数
`crt_params`	`list[str]`	現在のサブコマンドで未処理の引数
`privilege`	`int`	現在のユーザーのコマンド権限レベル
`query_id`	`int`	現在のパイプラインリクエスト ID
`query_uuid`	`str \| None`	現在のパイプラインリクエストの安定した識別子

SDK は現在のサブコマンドに入る前に context.shift() を呼び出します。コンポーネントから直接呼び出す必要はありません。

コンテキストメソッド

メソッド	戻り値	説明
`await context.reply(message_chain, quote_origin=False)`	-	現在のリクエストの会話に返信
`await context.get_bot_uuid()`	`str`	送信元 Bot の UUID を取得
`await context.set_query_var(key, value)`	-	現在のリクエストに変数を設定
`await context.get_query_var(key)`	`Any`	リクエスト変数を 1 つ取得
`await context.get_query_vars()`	`dict[str, Any]`	すべてのリクエスト変数を取得
`await context.create_new_conversation()`	`dict[str, Any]`	現在のパイプライン会話をクリアし、後続リクエストで新しい会話を作成
`await context.list_pipeline_knowledge_bases()`	`list[dict[str, Any]]`	現在のパイプラインの Local Agent に設定されたナレッジベースを取得
`await context.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)`	`list[dict[str, Any]]`	現在のパイプラインに設定されたナレッジベースを検索

これらのリクエストメソッドは EventListener と同じ動作です。登録方法と戻り値は Command コンポーネントを参照してください。

Tool

Tool には独立したコンテキストオブジェクトがありません。call() の引数として呼び出し情報を受け取ります。

conversation_type = session.launcher_type.value
conversation_id = session.launcher_id
sender_id = session.sender_id

引数	説明
`params`	ツールの JSON Schema に基づいてモデルまたは呼び出し元が生成した引数
`session`	現在のセッションデータ
`query_id`	現在のパイプラインリクエスト ID。リクエストコンテキストが必要な LangBot API にそのまま渡します

Session の主なプロパティは次のとおりです。

プロパティ	説明
`launcher_type`	会話種別：`person` または `group`
`launcher_id`	個人チャットのユーザー ID またはグループ ID
`sender_id`	現在のメッセージ送信者 ID
`bot_uuid`	現在の Bot UUID
`using_conversation`	現在のパイプライン会話
`conversations`	この Session に保存されたパイプライン会話
`use_prompt_name`	使用中のプロンプト名
`create_time`、`update_time`	Session の作成時刻と更新時刻

session はデータオブジェクトであり、reply() などのコンテキストメソッドはありません。ツールの戻り値は呼び出し元へ返され、チャットプラットフォームには自動送信されません。LangBot とプラットフォームの機能には self.plugin を使用します。API が session と query_id を要求する場合は、現在の呼び出しで受け取った値を渡してください。

Runner

独自の run(ctx) と Runner のイベントハンドラーは、どちらも RunnerContext を受け取ります。このコンテキストは現在の実行中だけ有効です。

text = ctx.input.to_text()
event_type = ctx.event.event_type

コンテキストデータ

プロパティ	型	説明
`run_id`	`str`	現在の実行 ID
`trigger`	`AgentTrigger`	トリガーの種類、発生元、時刻
`event`	`AgentEventContext`	イベント ID、種類、発生元、時刻、元データを含む標準イベントエンベロープ
`platform_event`	プラットフォームイベント型	イベント型に応じて解析されたプラットフォームイベント
`conversation`	`ConversationContext \| None`	現在の会話、スレッド、Bot、ワークスペースの識別子
`actor`	`ActorContext \| None`	イベントを発生させた主体
`subject`	`SubjectContext \| None`	イベントの対象となるメッセージやグループなど
`input`	`AgentInput`	現在のテキスト、構造化コンテンツ、添付ファイル
`delivery`	`DeliveryContext`	出力先とストリーミング、編集、リアクションの対応状況
`resources`	`AgentResources`	今回の実行で許可されたモデル、ツール、ナレッジベース、スキル、ストレージ
`context`	`ContextAccess`	会話カーソル、インライン方針、利用可能なコンテキスト API
`state`	`AgentRunState`	実行開始時に読み込まれたスコープ別状態のスナップショット
`runtime`	`AgentRuntimeContext`	LangBot バージョン、トレース ID、期限
`config`	`dict[str, Any]`	現在の Agent またはプラグインプロセッサーの設定
`adapter`	`AdapterContext \| None`	エントリーアダプターの追加データ
`variables`	`dict[str, Any]`	Runner テンプレートで使える公開リクエスト変数
`metadata`	`dict[str, Any]`	ホストが提供するその他のメタデータ

上表の安定したプロパティを優先してください。event.data と adapter.extra には、安定したフィールドに含まれない追加データが入ります。

返信とログ

メソッド	戻り値	説明
`await ctx.get_bot_uuid()`	`str`	送信元 Bot UUID を取得。関連する Bot がなければエラー
`await ctx.reply(message_chain, quote_origin=False)`	`Any`	文字列または `MessageChain` で現在のイベントに返信
`ctx.reply_stream()`	非同期コンテキストマネージャー	1 件の返信を完全なテキストで逐次更新
`await ctx.log(text, level="info")`	-	今回の実行ログへ記録。レベルは `debug`、`info`、`warning`、`error`

reply_stream().update(text) には、その時点の完全なテキストを渡します。プラットフォームがストリーミングに対応しない場合、終了時に完全なメッセージを 1 件送信します。デバッグモードでは送信をシミュレートします。

利用可能なツール

メソッド	戻り値	説明
`await ctx.get_available_tools()`	`list[dict[str, Any]]`	今回呼び出せるコンテキスト操作、プラットフォーム API、プラグインツール、MCP ツールを取得
`await ctx.call_tool(tool_name, parameters=None)`	`dict[str, Any]`	上記一覧のツールを呼び出す

get_available_tools() の各項目には name、description、parameters、type、operations が含まれます。結果は現在の Agent またはプラグインプロセッサーの設定とイベント機能で絞り込まれています。一覧にないツールは ctx.call_tool() で呼び出せません。

Box と添付ファイル

Box の有効化、取得、再利用方針は Runner が決めます。リソースの取得には LangBot API、実行中の操作には以下を使います。

メソッド	戻り値	説明
`await ctx.bind_box(box_id)`	`BoxBinding`	Box を現在の実行にバインドし、`box_id`、`outbox` を返す。同じ実行内では変更不可
`await ctx.import_box_attachments(attachment_ids=None)`	`list[BoxFile]`	入力の `ref` を指定してインポート。省略時は全件。サンドボックスの `path` を返す
`await ctx.export_box_files()`	`list[BoxFile]`	現在の実行の outbox をファイルハンドルとしてエクスポート。メッセージは送信しない
`await ctx.reply_files(file_ids)`	`Any`	エクスポートした ID で返信。返信ツールの権限制限が適用される

BoxFile は id、name、type、size、任意の path を含みます。入力の元 URL と内容は保持され、明示的にインポートして初めてファイルパスが生成されます。ハンドルは今回の実行でのみ有効で、重複送信できません。

ネイティブツールやファイル操作の前に Box をバインドします。Box を共有しても添付ディレクトリは実行ごとに分かれます。ctx.variables の公開リクエスト変数で再利用キーを計算できます。

Pipeline では ctx.delivery.automatic_reply が True になり、RunnerResult.message_completed(ctx.run_id, message, file_ids=[...]) で添付を返せます。Agent とプラグインプロセッサーは ctx.reply_files() で明示的に送信します。

外部ランナーも AgentRunExternalTools で同じ手順を使用できます：langbot_get_box_status、langbot_list_boxes、langbot_acquire_box、langbot_bind_box、langbot_import_box_attachments、langbot_export_box_files。イベントへの返信権限がある場合は langbot_reply_files も利用できます。すべての呼び出しに現在の実行の権限が適用されます。

プロンプト、履歴、イベント

メソッド	戻り値	利用可否フィールド
`await ctx.get_prompt()`	`list[dict[str, Any]]`	`prompt_get`
`await ctx.history_page(conversation_id=None, before_cursor=None, after_cursor=None, limit=50, direction="backward", include_attachments=False)`	`HistoryPage`	`history_page`
`await ctx.history_search(query, filters=None, top_k=10)`	`HistorySearchResult`	`history_search`
`await ctx.event_get(event_id)`	`AgentEventRecord`	`event_get`
`await ctx.event_page(conversation_id=None, event_types=None, before_cursor=None, limit=50)`	`EventPage`	`event_page`
`await ctx.steering_pull(mode="all", limit=None)`	`SteeringPullResult`	`steering_pull`

状態

メソッド	戻り値	説明
`await ctx.state_get(scope, key)`	`dict[str, Any]`	状態値を取得
`await ctx.state_set(scope, key, value)`	`dict[str, Any]`	JSON シリアライズ可能な状態値を保存
`await ctx.state_delete(scope, key)`	`dict[str, Any]`	状態値を削除
`await ctx.state_list(scope, prefix=None, limit=100)`	`dict[str, Any]`	指定スコープの状態キーを一覧表示

scope は conversation、actor、subject、runner のいずれかです。これらのメソッドには ctx.context.available_apis.state が true である必要があります。

実行記録

メソッド	戻り値	利用可否フィールド
`await ctx.run_get(run_id=None)`	`AgentRun`	`run_get`
`await ctx.run_list(conversation_id=None, statuses=None, before_cursor=None, limit=50)`	`RunPage`	`run_list`
`await ctx.run_events_page(run_id=None, before_cursor=None, after_cursor=None, limit=50, direction="forward")`	`RunEventPage`	`run_events_page`
`await ctx.run_cancel(run_id=None, reason=None)`	`AgentRun`	`run_cancel`
`await ctx.run_append_result(result)`	`AgentRunEvent`	`run_append_result`
`await ctx.run_finalize(run_id=None, status=None, reason=None)`	`AgentRun`	`run_finalize`

run_id=None は現在の実行を指します。通常のイベントハンドラーは SDK が自動的に完了します。独自の run(ctx) が RunnerResult を yield する場合、同じ結果を run_append_result() で重複登録しないでください。

利用可否と権限

プロンプト、履歴、イベント、状態、実行記録の API が利用可能かどうかは ctx.context.available_apis で確認します。許可されたモデル、ツール、ナレッジベースはそれぞれ ctx.resources.models、ctx.resources.tools、ctx.resources.knowledge_bases にあります。

Runner の実行中に self.plugin から呼び出すモデル、ツール、ナレッジベース、ストレージ、プラットフォーム API は、自動的に現在の実行へ関連付けられ、ctx.resources に基づいて再検証されます。run_id を渡す必要はありません。ハンドラー終了後にバックグラウンドタスクからこのコンテキストや実行に紐づく呼び出しを使用しないでください。

ctx.api は低レベルの実行スコーププロキシです。通常のコンポーネントコードでは、このページに記載した ctx メソッドと、LangBot API 用の self.plugin を使用してください。

データ専用コンテキスト

以下のコンポーネントが受け取るものはタスク入力であり、EventListener や Runner の実行コンテキストメソッドはありません。フィールド、戻り値、完全な例は各コンポーネントガイドに記載しています。

コンポーネントの入口	主なデータ	コンポーネントガイド
`KnowledgeEngine.ingest(context: IngestionContext)`	ファイル、対象ナレッジベース、作成設定、解析結果	KnowledgeEngine
`KnowledgeEngine.retrieve(context: RetrievalContext)`	クエリ、対象ナレッジベース、検索設定、フィルター	KnowledgeEngine
`KnowledgeRetriever.retrieve(context: RetrievalContext)`	クエリと外部ナレッジベース設定	KnowledgeRetriever
`Parser.parse(context: ParseContext)`	ファイル内容、ファイル名、MIME タイプ、メタデータ	Parser
`Page.handle_api(request: PageRequest)`	エンドポイント、HTTP メソッド、本文、ヘッダー	Page

コンテキスト API

On this page