mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-06-24 14:34:20 +00:00
refactor(agent-runner): use sandbox file model
This commit is contained in:
huanghuoguoguo
@@ -39,7 +39,7 @@ Protocol v1 **不定义**：
|
||||
`ctx.config`、`ctx.resources`、`ctx.context` 和 `ctx.delivery`。SDK 不需要知道
|
||||
Agent / binding 的持久化形态。
|
||||
|
||||
外部 harness runner（Claude Code、Codex、Kimi Code 等）也是 `AgentRunner`：它们消费 event-first `AgentRunContext`、返回 `AgentRunResult`，并通过 Host 授权的 state/storage/artifact API 保存跨轮次指针。它们内部可以继续使用自己的 session、tool loop、MCP、上下文压缩和权限模型。
|
||||
外部 harness runner（Claude Code、Codex、Kimi Code 等）也是 `AgentRunner`：它们消费 event-first `AgentRunContext`、返回 `AgentRunResult`，并通过 Host 授权的 state/storage API 保存跨轮次指针；当前运行文件和工具大结果进入 sandbox/workspace。它们内部可以继续使用自己的 session、tool loop、MCP、上下文压缩和权限模型。
|
||||
|
||||
## 3. 协议演进
|
||||
|
||||
@@ -64,17 +64,11 @@ class AgentRunnerDiscovery(BaseModel):
|
||||
plugin_author: str
|
||||
plugin_name: str
|
||||
runner_name: str
|
||||
runner_description: I18nObject | None = None
|
||||
manifest: AgentRunnerManifest
|
||||
capabilities: AgentRunnerCapabilities # compatibility alias of manifest.capabilities
|
||||
permissions: AgentRunnerPermissions # compatibility alias of manifest.permissions
|
||||
config: list[DynamicFormItemSchema] = []
|
||||
```
|
||||
|
||||
`manifest` 是 SDK typed `AgentRunnerManifest`，由 Runtime 从插件组件 manifest 解析并校验后返回。`plugin_author` / `plugin_name` / `runner_name` 保留为 transport 寻址字段；Host 以它们生成稳定 runner id，并把 `manifest.id` 校验为 `plugin:author/name/runner`。单个 runner manifest 解析失败时 Runtime/Host 记录 warning 并跳过该 runner，不影响同一插件或其它插件的 runner discovery。
|
||||
|
||||
`capabilities` / `permissions` 顶层字段是兼容旧 discovery 消费方的冗余别名；新代码必须以 `manifest.capabilities` / `manifest.permissions` 为准。
|
||||
|
||||
### 4.2 AgentRunnerManifest
|
||||
|
||||
这里的 manifest 指 Runtime 返回给 Host 的 typed runner manifest：
|
||||
@@ -116,7 +110,7 @@ class AgentRunnerCapabilities(BaseModel):
|
||||
- `streaming`: runner 可以返回 `message.delta`。
|
||||
- `tool_calling`: runner 可能调用 Host tool API。
|
||||
- `knowledge_retrieval`: runner 可能调用 Host knowledge API。
|
||||
- `multimodal_input`: runner 可以处理非纯文本 input / artifact。
|
||||
- `multimodal_input`: runner 可以处理非纯文本 input / attachment。
|
||||
- `skill_authoring`: runner 需要 Host 提供 skill facts 以及 skill authoring tools，例如 `activate` / `register_skill`。
|
||||
- `interrupt`: runner 支持取消或中断。
|
||||
- `steering`: runner 支持在 turn 边界通过 Host pull API 消费同 conversation 在途追加消息。
|
||||
@@ -132,7 +126,6 @@ class AgentRunnerPermissions(BaseModel):
|
||||
knowledge_bases: list[Literal["list", "retrieve"]] = []
|
||||
history: list[Literal["page", "search"]] = []
|
||||
events: list[Literal["get", "page"]] = []
|
||||
artifacts: list[Literal["metadata", "read"]] = []
|
||||
storage: list[Literal["plugin", "workspace"]] = []
|
||||
files: list[Literal["config", "knowledge"]] = []
|
||||
|
||||
@@ -161,7 +154,7 @@ effective_access = manifest.permissions ∩ binding.resource_policy ∩ current
|
||||
- Host 不得默认 inline 全量历史。
|
||||
- Host 只 inline 当前 event / input 和 context handles。
|
||||
- Runner 拥有 working context assembly。
|
||||
- Runner 可在授权后通过 Host history / event / artifact / state API 拉取更多上下文。
|
||||
- Runner 可在授权后通过 Host history / event / state API 拉取更多上下文，并通过授权 sandbox/workspace 工具访问当前运行文件。
|
||||
- 历史窗口策略不属于 Protocol v1 字段，也不属于 Host 通用语义。
|
||||
|
||||
context 边界的设计理由见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)。
|
||||
@@ -242,7 +235,7 @@ class AgentEventContext(BaseModel):
|
||||
|
||||
- `event_type` 使用 LangBot 稳定协议名，例如 `message.received`。稳定事件名清单见 [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md)。
|
||||
- 平台原始事件名放入 `source_event_type`。
|
||||
- 大型原始 payload 必须放入 `raw_ref` 或 artifact，不应直接塞入 `data`。
|
||||
- 大型原始 payload 必须放入 `raw_ref` 或 staged file，不应直接塞入 `data`。
|
||||
|
||||
### 5.5 Conversation / Actor / Subject
|
||||
|
||||
@@ -281,11 +274,11 @@ class SubjectContext(BaseModel):
|
||||
class AgentInput(BaseModel):
|
||||
text: str | None = None
|
||||
contents: list[ContentElement] = []
|
||||
attachments: list[ArtifactRef] = []
|
||||
attachments: list[InputAttachment] = []
|
||||
```
|
||||
|
||||
- 文本、多模态、附件都属于当前 event input。
|
||||
- 大文件、图片、音频、工具大结果应以 artifact ref 传递。
|
||||
- 大文件、图片、音频、工具大结果应进入授权 sandbox/workspace，input attachment 只携带轻量 metadata/path/url/content。
|
||||
- 平台原始消息链不属于 SDK `AgentInput`；需要诊断时放在 Host 内部 envelope 或 `ctx.adapter.extra` 的一次性兼容字段中，不作为长期 runner 合同。
|
||||
|
||||
### 5.7 DeliveryContext
|
||||
@@ -329,8 +322,6 @@ class ContextAPICapabilities(BaseModel):
|
||||
history_search: bool = False
|
||||
event_get: bool = False
|
||||
event_page: bool = False
|
||||
artifact_metadata: bool = False
|
||||
artifact_read: bool = False
|
||||
state: bool = False
|
||||
storage: bool = False
|
||||
steering_pull: bool = False
|
||||
@@ -373,14 +364,13 @@ class AgentResources(BaseModel):
|
||||
tools: list[ToolResource] = []
|
||||
knowledge_bases: list[KnowledgeBaseResource] = []
|
||||
skills: list[SkillResource] = []
|
||||
files: list[FileResource] = []
|
||||
storage: StorageResource = StorageResource()
|
||||
platform_capabilities: dict[str, Any] = {}
|
||||
```
|
||||
|
||||
`skills` 只包含本次 run 中 pipeline-visible 的 skill facts，例如 `skill_name`、`display_name` 和 `description`。Host 不把这些 facts 追加到 system prompt，也不把它们编排进工具描述；runner 可以自行决定是否放入 model prompt、转换成 MCP surface，或只在自己的策略层使用。
|
||||
|
||||
资源列表是本次 run 的授权结果。History / Event / Artifact 访问通过 `ctx.context.available_apis` 和 Host 侧 run session 校验控制，不作为可枚举 resource list 暴露。Runner 只能通过 `AgentRunAPIProxy` 访问这些能力。
|
||||
资源列表是本次 run 的授权结果。History / Event / State / Storage 访问通过 `ctx.context.available_apis` 和 Host 侧 run session 校验控制，不作为可枚举 resource list 暴露。Runner 只能通过 `AgentRunAPIProxy` 访问这些能力。当前事件的文件和工具大结果优先进入授权 sandbox/workspace，由 runner 通过 read/write/exec 类工具按需读取。
|
||||
|
||||
## 7. Result Stream
|
||||
|
||||
@@ -394,7 +384,6 @@ ResultType = Literal[
|
||||
"message.completed",
|
||||
"tool.call.started",
|
||||
"tool.call.completed",
|
||||
"artifact.created",
|
||||
"state.updated",
|
||||
"action.requested",
|
||||
"run.completed",
|
||||
@@ -432,7 +421,7 @@ class LLMTokenUsage(BaseModel):
|
||||
|
||||
Host 边界分级校验：
|
||||
|
||||
- `message.delta`、`message.completed`、`artifact.created`、`state.updated`、`action.requested`、`run.completed`、`run.failed` 属于会影响投递或 Host 副作用的严格 payload；校验失败时丢弃该 result 并记录 warning。
|
||||
- `message.delta`、`message.completed`、`state.updated`、`action.requested`、`run.completed`、`run.failed` 属于会影响投递或 Host 副作用的严格 payload；校验失败时丢弃该 result 并记录 warning。
|
||||
- `tool.call.started`、`tool.call.completed` 当前只作为 telemetry，payload 宽松兼容。
|
||||
- 未知 `type` 忽略并记录 warning。
|
||||
|
||||
@@ -444,13 +433,12 @@ Host 边界分级校验：
|
||||
| `message.completed` | `{ "message": Message }` |
|
||||
| `tool.call.started` | `{ "tool_call_id": str, "tool_name": str, "parameters": dict }` |
|
||||
| `tool.call.completed` | `{ "tool_call_id": str, "tool_name": str, "result": dict \| None, "error": str \| None }` |
|
||||
| `artifact.created` | `{ "artifact_type": str, "artifact_id"?: str, "mime_type"?: str, "name"?: str, "size_bytes"?: int, "sha256"?: str, "metadata"?: dict, "content_base64"?: str }` |
|
||||
| `state.updated` | `{ "scope": "conversation" \| "actor" \| "subject" \| "runner", "key": str, "value": JSONValue }` |
|
||||
| `action.requested` | `{ "action": str, "target": dict \| None, "payload": dict \| None }` |
|
||||
| `run.completed` | `{ "finish_reason": str, "message"?: Message }` |
|
||||
| `run.failed` | `{ "code": str, "error": str, "retryable": bool }` |
|
||||
|
||||
`artifact.created.content_base64` 是小 artifact 的 inline 通道；Host 解码后写入 ArtifactStore，当前 hard cap 是 1 MiB。大 artifact 应使用外部存储 / file key / 后续上传通道，不应塞入 result event。
|
||||
Runner 生成的大文件、工具输出和临时产物不通过 result event 回传；应写入当前 run 的授权 sandbox/workspace，再用消息文本、metadata 或 attachment reference 指向它们。
|
||||
|
||||
### 7.3 稳定 result types
|
||||
|
||||
@@ -460,7 +448,6 @@ Host 边界分级校验：
|
||||
| `message.completed` | 完整消息。 | ✅ |
|
||||
| `tool.call.started` | 工具调用开始的可观测事件。 | telemetry |
|
||||
| `tool.call.completed` | 工具调用完成的可观测事件。 | telemetry |
|
||||
| `artifact.created` | runner 生成 artifact。 | ✅ |
|
||||
| `state.updated` | runner 请求更新 host-owned state。 | ✅ |
|
||||
| `action.requested` | runner 请求 Host 执行平台动作。 | **reserved / 仅 telemetry，不执行** |
|
||||
| `run.completed` | run 正常结束。 | ✅ |
|
||||
@@ -511,7 +498,7 @@ await api.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)
|
||||
# History（返回 Transcript projection，不返回原始平台 payload）
|
||||
await api.get_prompt()
|
||||
await api.history_page(conversation_id=None, before_cursor=None, after_cursor=None,
|
||||
limit=50, direction="backward", include_artifacts=False)
|
||||
limit=50, direction="backward", include_attachments=False)
|
||||
await api.history_search(query, filters=None, top_k=10)
|
||||
|
||||
# Event（返回稳定 event envelope 或受限 raw ref，不默认返回大 payload）
|
||||
@@ -519,11 +506,6 @@ await api.event_get(event_id)
|
||||
await api.event_page(conversation_id=None, event_types=None, before_cursor=None, limit=50)
|
||||
await api.steering_pull(mode="all", limit=None)
|
||||
|
||||
# Artifact（必须支持大小限制、MIME 校验、过期时间和授权范围）
|
||||
await api.artifact_metadata(artifact_id)
|
||||
await api.artifact_read(artifact_id, offset=0, limit=None)
|
||||
await api.artifact_read_range(artifact_id, offset=0, length=65536)
|
||||
|
||||
# State / Storage
|
||||
await api.state_get(scope, key); await api.state_set(scope, key, value); await api.state_delete(scope, key)
|
||||
await api.state_list(scope, prefix=None, limit=100)
|
||||
@@ -532,8 +514,7 @@ await api.get_plugin_storage_keys()
|
||||
await api.get_workspace_storage(key); await api.set_workspace_storage(key, value); await api.delete_workspace_storage(key)
|
||||
await api.get_workspace_storage_keys()
|
||||
|
||||
# Files / Host info
|
||||
await api.get_file(file_key)
|
||||
# Host info
|
||||
await api.get_langbot_version()
|
||||
```
|
||||
|
||||
@@ -593,7 +574,7 @@ class TranscriptItem(BaseModel):
|
||||
item_type: str = "message"
|
||||
content: str | None = None
|
||||
content_json: dict[str, Any] | None = None
|
||||
artifact_refs: list[dict[str, Any]] = []
|
||||
attachment_refs: list[dict[str, Any]] = []
|
||||
seq: int | None = None
|
||||
cursor: str | None = None
|
||||
created_at: int | None = None
|
||||
@@ -653,31 +634,6 @@ class SteeringInputItem(BaseModel):
|
||||
|
||||
class SteeringPullResult(BaseModel):
|
||||
items: list[SteeringInputItem] = []
|
||||
|
||||
class ArtifactMetadata(BaseModel):
|
||||
artifact_id: str
|
||||
artifact_type: str
|
||||
mime_type: str | None = None
|
||||
name: str | None = None
|
||||
size_bytes: int | None = None
|
||||
sha256: str | None = None
|
||||
source: str
|
||||
conversation_id: str | None = None
|
||||
run_id: str | None = None
|
||||
runner_id: str | None = None
|
||||
created_at: int | None = None
|
||||
expires_at: int | None = None
|
||||
metadata: dict[str, Any] = {}
|
||||
|
||||
class ArtifactReadResult(BaseModel):
|
||||
artifact_id: str
|
||||
mime_type: str | None = None
|
||||
size_bytes: int | None = None
|
||||
offset: int = 0
|
||||
length: int | None = None
|
||||
content_base64: str | None = None
|
||||
file_key: str | None = None
|
||||
has_more: bool = False
|
||||
```
|
||||
|
||||
## 9. 错误模型
|
||||
@@ -720,11 +676,11 @@ Runner 失败使用 `run.failed`：
|
||||
|
||||
Protocol v1 的安全边界在 Host：
|
||||
|
||||
- Runner 不能直接访问未授权 model/tool/kb/history/artifact/storage。
|
||||
- Runner 不能直接访问未授权 model/tool/kb/history/storage/sandbox。
|
||||
- SDK 本地校验只提升开发体验，不能替代 Host 校验。
|
||||
- 所有 resource id 对 runner 来说都是 opaque。
|
||||
- 默认只能访问当前 conversation / thread 的 history；跨会话、workspace 级访问必须额外授权。
|
||||
- 大 payload 必须 artifact 化；`artifact.created.content_base64` 只用于小 artifact，当前 Host hard cap 是 1 MiB。
|
||||
- 大 payload 不应塞进 result event；当前 run 的文件和工具大结果应进入授权 sandbox/workspace，由 read/write/exec 类工具按需访问。
|
||||
- Host 必须记录 run_id、runner_id、action、resource、scope、result。
|
||||
|
||||
Host 不负责业务编排：不拼接全量历史、不替 runner 做 prompt assembly、不内置 agent memory / tool loop / 上下文压缩策略。这些由官方或第三方 AgentRunner 插件实现。
|
||||
@@ -764,7 +720,6 @@ entry adapter 只是迁移桥。它负责：
|
||||
## 14. 开放问题
|
||||
|
||||
- `AgentBinding` 是否需要进入 SDK 文档作为只读诊断信息，还是完全 Host 内部。
|
||||
- ArtifactStore 是否复用现有 BinaryStorage backend，还是引入独立实体。
|
||||
- State 与 Storage 的边界是否需要更强类型。
|
||||
- platform action 的审批模型如何表达。
|
||||
- Host 侧 scoped MCP / skill / workspace projection 是否需要从 runner config 上移为一等 resource projection API。
|
||||
|
||||
Reference in New Issue
Block a user