xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-10-29 11:56:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: explain runner sandbox APIs and custom select presets

Browse Source
This commit is contained in:
RockChinQ
2026-09-17 23:04:53 +08:00
parent 6dcbcf6eac
commit a5c1fb43e0
9 changed files with 112 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
en/plugin/dev/apis/agent-run.mdx
+20
View File
@@ -161,6 +161,7 @@ event_type = ctx.event.event_type
| `runtime` | `AgentRuntimeContext` | LangBot version, trace ID, and deadline |
| `config` | `dict[str, Any]` | Current Agent or plugin-processor configuration |
| `adapter` | `AdapterContext \| None` | Additional entry-adapter data |
| `variables` | `dict[str, Any]` | Public request variables for Runner templates |
| `metadata` | `dict[str, Any]` | Other metadata supplied by the Host |
Prefer the stable properties in this table. `event.data` and `adapter.extra` carry additional data that has not been promoted to stable fields.
@@ -185,6 +186,25 @@ Each `reply_stream().update(text)` call supplies the complete current text. If t
Each item returned by `get_available_tools()` contains `name`, `description`, `parameters`, `type`, and `operations`. The result is already filtered by the current Agent or plugin-processor configuration and the event's capabilities. `ctx.call_tool()` cannot call a tool absent from this list.
### Box and attachments
The Runner owns enablement, acquisition, and reuse policy. Use the [LangBot Box APIs](/en/plugin/dev/apis/common#box-sandbox) for resources and these context methods for the current run.
| Method | Returns | Behavior |
| --- | --- | --- |
| `await ctx.bind_box(box_id)` | `BoxBinding` | Bind a Workspace Box; returns `box_id`, `outbox`. A run cannot switch Boxes |
| `await ctx.import_box_attachments(attachment_ids=None)` | `list[BoxFile]` | Import selected input `ref` values, or all inputs; returns sandbox paths |
| `await ctx.export_box_files()` | `list[BoxFile]` | Export this run's outbox as file handles; sends no message |
| `await ctx.reply_files(file_ids)` | `Any` | Reply with exported IDs, subject to event reply authorization |
`BoxFile` contains `id`, `name`, `type`, `size`, and optional `path`. Original attachment URLs and content remain available. Files are staged only on explicit import. Output handles belong to this run and cannot be sent twice.
Bind before native sandbox tools or file operations. Runs sharing a Box still have separate attachment directories. `ctx.variables` contains public request variables for computing reuse keys.
`ctx.delivery.automatic_reply` is `True` for Pipeline execution: return files using `RunnerResult.message_completed(ctx.run_id, message, file_ids=[...])`. Agents and plugin processors explicitly call `ctx.reply_files()`.
External runners use the same flow through `AgentRunExternalTools`: `langbot_get_box_status`, `langbot_list_boxes`, `langbot_acquire_box`, `langbot_bind_box`, `langbot_import_box_attachments`, and `langbot_export_box_files`. `langbot_reply_files` is available when the run has event reply permission. All calls retain the current run authorization.
### Prompt, history, and events
| Method | Return value | Availability field |
en/plugin/dev/apis/common.mdx
+14
View File
@@ -693,3 +693,17 @@ commands = await self.plugin.list_commands()
```
Both methods take no arguments and return the Host-provided plugin manifest list and command list respectively.
### Box sandbox
These methods use `self.plugin` and the current Workspace. Runner calls automatically retain invocation authorization.
| Method | Returns | Behavior |
| --- | --- | --- |
| `await self.plugin.get_box_status()` | `BoxStatus` | `enabled`, `available`, capacity `limit`, `used`, `remaining`, optional managed `required_reuse_key`, and unavailable `reason` |
| `await self.plugin.list_boxes()` | `list[BoxSession]` | Box `id` and `status` snapshot (`idle`, `running`, `closing`) |
| `await self.plugin.acquire_box(reuse_key, options=None)` | `BoxSession` | Reuse the same key or create within capacity; `options` supports `image` |
Unknown capacity fields are `None`. Zero remaining capacity still permits reuse; Runtime checks creation capacity atomically. The Runner computes reuse keys. When `required_reuse_key` is supplied, use it. Equal keys in different Workspaces never share a Box.
Use the [Runner context](/en/plugin/dev/apis/agent-run#runner) to bind the Box before importing attachments or executing tools.
en/plugin/dev/basic-info.mdx
+3
View File
@@ -159,6 +159,7 @@ Dropdown menu. Requires configuring `options`, which represents the dropdown men
```yaml
- name: mode
type: select
allow_custom: true
options: # Dropdown options, supports multilingual.
- name: mode1 # Value, displayed as secondary text in the dropdown.
label: # Display name, supports multilingual.
@@ -171,6 +172,8 @@ Dropdown menu. Requires configuring `options`, which represents the dropdown men
...
```
Set `allow_custom: true` to add a Custom option alongside the presets. A text input appears only when Custom is selected. The saved value is the selected `name` or the custom string, never a Custom marker. This also applies to a runner’s `spec.config`.
### type: prompt-editor
Prompt editor. Displays a prompt editor from the pipeline configuration page, with the final result represented in OpenAI's `messages` format.
ja/plugin/dev/apis/agent-run.mdx
+20
View File
@@ -161,6 +161,7 @@ event_type = ctx.event.event_type
| `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` には、安定したフィールドに含まれない追加データが入ります。
@@ -185,6 +186,25 @@ event_type = ctx.event.event_type
`get_available_tools()` の各項目には `name`、`description`、`parameters`、`type`、`operations` が含まれます。結果は現在の Agent またはプラグインプロセッサーの設定とイベント機能で絞り込まれています。一覧にないツールは `ctx.call_tool()` で呼び出せません。
### Box と添付ファイル
Box の有効化、取得、再利用方針は Runner が決めます。リソースの取得には [LangBot API](/ja/plugin/dev/apis/common#box-サンドボックス)、実行中の操作には以下を使います。
| メソッド | 戻り値 | 説明 |
| --- | --- | --- |
| `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` も利用できます。すべての呼び出しに現在の実行の権限が適用されます。
### プロンプト、履歴、イベント
| メソッド | 戻り値 | 利用可否フィールド |
ja/plugin/dev/apis/common.mdx
+14
View File
@@ -693,3 +693,17 @@ commands = await self.plugin.list_commands()
```
いずれも引数なしで、ホストが提供するプラグインのマニフェスト一覧とコマンド一覧を返します。
### Box サンドボックス
`self.plugin` から現在のワークスペースに対して呼び出します。Runner 内では実行権限が自動的に引き継がれます。
| メソッド | 戻り値 | 説明 |
| --- | --- | --- |
| `await self.plugin.get_box_status()` | `BoxStatus` | `enabled`、`available`、上限 `limit`、使用数 `used`、残数 `remaining`、任意の `required_reuse_key`、利用不可理由 `reason` |
| `await self.plugin.list_boxes()` | `list[BoxSession]` | `id` と状態 `status`（`idle`、`running`、`closing`）のスナップショット |
| `await self.plugin.acquire_box(reuse_key, options=None)` | `BoxSession` | 同一キーで再利用、または上限内で作成。`options` は `image` をサポート |
不明な数量は `None` です。残数がゼロでも既存 Box の再利用は可能です。新規作成時の上限は Runtime が原子的に確認します。キーは Runner が計算しますが、`required_reuse_key` が返された場合はその値を使います。異なるワークスペース間では同じキーでも共有されません。
取得後は[Runner コンテキスト](/ja/plugin/dev/apis/agent-run#runner)でバインドしてから、添付のインポートやツール実行を行います。
ja/plugin/dev/basic-info.mdx
+3
View File
@@ -159,6 +159,7 @@ spec:
```yaml
- name: mode
type: select
allow_custom: true
options: # ドロップダウンオプション、多言語サポート。
- name: mode1 # 値、ドロップダウンで小さなテキストとして表示。
label: # 表示名、多言語サポート。
@@ -171,6 +172,8 @@ spec:
...
```
`allow_custom: true` を設定すると、プリセットに「カスタム」が追加され、その選択時だけ入力欄が表示されます。保存される値は選択した `name` または入力した文字列であり、「カスタム」というマーカーではありません。ランナーの `spec.config` にも使用できます。
### type: prompt-editor
プロンプトエディター。パイプライン設定ページからプロンプトエディターを表示し、最終結果はOpenAIの`messages`形式で表されます。
zh/plugin/dev/apis/agent-run.mdx
+20
View File
@@ -163,6 +163,7 @@ event_type = ctx.event.event_type
| `runtime` | `AgentRuntimeContext` | LangBot 版本、追踪 ID 和截止时间 |
| `config` | `dict[str, Any]` | 当前 Agent 或插件处理器配置 |
| `adapter` | `AdapterContext \| None` | 入口适配器附加数据 |
| `variables` | `dict[str, Any]` | 公开的请求变量，可用于运行器插值模板 |
| `metadata` | `dict[str, Any]` | 宿主提供的其他元数据 |
优先使用上表中的稳定字段。`event.data` 和 `adapter.extra` 用于承载尚未进入稳定字段的附加信息。
@@ -187,6 +188,25 @@ event_type = ctx.event.event_type
`get_available_tools()` 的每一项包含 `name`、`description`、`parameters`、`type` 和 `operations`。返回结果已经按当前 Agent 或插件处理器的配置和事件能力过滤；不在列表中的工具不能通过 `ctx.call_tool()` 调用。
### Box 与附件
Box 是否启用、何时创建以及如何复用，由运行器决定。获取状态和申请 Box 使用 [LangBot API](/zh/plugin/dev/apis/common#box-沙箱)；当前运行的绑定和附件操作使用下列方法。
| 方法 | 返回值 | 说明 |
| --- | --- | --- |
| `await ctx.bind_box(box_id)` | `BoxBinding` | 绑定当前工作区中的 Box，返回 `box_id`、`outbox`；同次运行不能切换 Box |
| `await ctx.import_box_attachments(attachment_ids=None)` | `list[BoxFile]` | 导入 `ctx.input.attachments` 的 `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`、`content` 等原始信息仍保留，只有显式导入才产生沙箱文件路径。文件句柄仅在本次运行有效，不能重复发送。
先绑定 Box，再使用原生执行、文件工具和附件方法。复用同一 Box 时，各次运行的附件目录仍独立。`ctx.variables` 提供公开的请求变量，运行器可据此计算复用键。
通过流水线运行时，`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`；这些调用均携带当前运行的授权。
### 提示词、历史与事件
| 方法 | 返回值 | 可用性字段 |
zh/plugin/dev/apis/common.mdx
+14
View File
@@ -693,3 +693,17 @@ commands = await self.plugin.list_commands()
```
两个方法均不需要参数，分别返回宿主提供的插件清单列表和命令列表。
### Box 沙箱
这些方法通过 `self.plugin` 调用，作用于当前工作区。在运行器内调用时会自动携带本次运行的授权。
| 方法 | 返回值 | 说明 |
| --- | --- | --- |
| `await self.plugin.get_box_status()` | `BoxStatus` | `enabled`、`available`、数量上限 `limit`、已用 `used`、剩余 `remaining`、托管环境要求的 `required_reuse_key` 和不可用原因 `reason` |
| `await self.plugin.list_boxes()` | `list[BoxSession]` | 可用 Box 的 `id` 和状态快照 `status`（`idle`、`running`、`closing`） |
| `await self.plugin.acquire_box(reuse_key, options=None)` | `BoxSession` | 同一键复用已有 Box，否则在数量限制内创建；`options` 支持 `image` |
数量未知时对应字段为 `None`。`remaining=0` 仍可以复用已有 Box；创建时由 Runtime 原子检查额度。运行器自行计算复用键，Host 不解释聊天模板；托管环境给出 `required_reuse_key` 时须使用该值。不同工作区的相同键不会共用 Box。
获取 Box 后，通过[运行器上下文](/zh/plugin/dev/apis/agent-run#runner)绑定到本次运行，再导入附件和执行工具。
zh/plugin/dev/basic-info.mdx
+4 -1
View File
@@ -159,6 +159,7 @@ spec:
```yaml
- name: mode
type: select
allow_custom: true
options: # 下拉框选项，支持多语言。
- name: mode1 # 值，在下拉框中以小字显示。
label: # 显示名称，支持多语言。
@@ -171,6 +172,8 @@ spec:
...
```
设置 `allow_custom: true` 可在预设之外提供“自定义”选项，仅选择该项时显示输入框。最终保存的是所选 `name` 或自定义字符串，不会保存“自定义”标记。此选项也适用于运行器的 `spec.config`。
### type: prompt-editor
提示词编辑器。会展示一个流水线配置页面的提示词编辑器，最终结果表示为 OpenAI 的 `messages` 格式。
@@ -305,4 +308,4 @@ for tool_name in selected_tools:
该教程将指引您逐步完善插件功能。
- 添加组件：插件组件是插件的核心功能单元，您可以根据需求[添加组件](/zh/plugin/dev/components/add)。
- 添加组件：插件组件是插件的核心功能单元，您可以根据需求[添加组件](/zh/plugin/dev/components/add)。