From b7dcda8b235dc176f56a6dc5cb595b1aca102f47 Mon Sep 17 00:00:00 2001 From: Junyan Qin Date: Fri, 8 May 2026 17:51:41 +0800 Subject: [PATCH] docs: record agent runner design decisions --- docs/agent-runner-pluginization/README.md | 32 ++++++++++++++--------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/docs/agent-runner-pluginization/README.md b/docs/agent-runner-pluginization/README.md index 566f7950..2a598fa5 100644 --- a/docs/agent-runner-pluginization/README.md +++ b/docs/agent-runner-pluginization/README.md @@ -18,11 +18,11 @@ - SDK 提供稳定的 `AgentRunner` 组件接口、上下文实体、返回实体、配置 schema 和运行期 API。 - LangBot 负责 runner 发现、配置装配、权限校验、运行调度、流式结果转换、错误隔离和兼容层。 - 为未来 EBA 的非消息事件接入预留 `event`、`actor`、`subject`、`platform_capabilities` 等上下文字段。 +- 现有内置 `RequestRunner` 最终强制迁移为插件形态，由 LangBot 通过同一套插件化 runner 协议调用。 非目标： - 不在本阶段实现 EBA EventBus、EventRouter、平台多事件监听或统一平台 API。 -- 不要求所有内置 `RequestRunner` 立即改写成插件。 - 不改变现有 Pipeline 的阶段链和私聊/群聊入口。 - 不引入插件内自定义长驻调度器；Agent Runner 仍由 LangBot 显式调用。 @@ -115,6 +115,8 @@ class AgentRunner(BaseComponent): ... ``` +一个插件可以声明多个 `AgentRunner` 组件。每个 runner 使用独立的 component manifest、配置 schema、能力声明和权限声明；LangBot 侧以 `plugin:author/name/runner` 作为稳定 ID 区分。插件包可以因此同时提供多个执行策略，例如通用聊天 runner、客服 runner、工单 runner，而不需要拆成多个插件。 + `get_capabilities()` 用来告诉 LangBot 这个 runner 是否支持： - `streaming` @@ -178,7 +180,6 @@ class AgentRunResult(BaseModel): "tool.call.started", "tool.call.completed", "state.updated", - "action.requested", "run.completed", "run.failed", ] @@ -192,7 +193,7 @@ class AgentRunResult(BaseModel): - `run.completed` 且带 `message` -> `Message` - `run.failed` -> 记录错误并按当前 runner 错误策略返回 -未来 EBA 可使用 `action.requested` 表达平台动作，例如编辑消息、通过好友请求、踢人等。本阶段只保留类型，不执行平台动作。 +`action.requested` 不进入本阶段的必选协议。它表示“Agent 希望 LangBot 执行一个非文本平台动作”，例如未来 EBA 里编辑消息、通过好友请求、踢人等。当前 Agent Runner 仍作为 Pipeline 的一个 stage 执行，输出只需要覆盖消息流、工具调用状态和运行完成/失败；如果实验性 runner 返回 `action.requested`，LangBot 只记录 telemetry 并忽略执行。 ### 5.4 LangBotAPIProxy @@ -219,7 +220,11 @@ SDK 应把这些能力按 capability 分组。LangBot 在调用 runner 前根据 当前 `PipelineService.get_pipeline_metadata()` 可以继续作为 UI 入口，但应改为读取 registry，而不是直接拼插件列表。 -### 6.2 配置模型 +### 6.2 配置模型与绑定位置 + +当前阶段 runner 配置仍跟 Pipeline 绑定，并且仍然作为 Pipeline 的一个 stage 执行。也就是说，Bot 收到私聊/群聊消息后仍按现有 Pipeline 流转，只是在 AI runner stage 中选择插件化 Agent Runner。 + +后续 EBA EventRouter 落地后，同一套 `AgentRunnerDescriptor` 和 `AgentRunOrchestrator` 需要支持直接与 Bot 的事件触发器绑定。届时 Bot event handler 可以绕过完整 Pipeline，直接选择某个 Agent Runner 处理 `message.received`、`group.member_joined`、`friend.request_received` 等事件。 Pipeline AI 配置建议从： @@ -352,17 +357,18 @@ LangBot 执行前做三层裁剪： - proxy action 做二次校验。 - 增加超时、取消、错误隔离和 telemetry。 -### Phase 3：兼容和迁移 +### Phase 3：内置 runner 插件化迁移 - 兼容当前 `plugin:author/name/runner` 字符串 ID。 - 兼容 `runner.runner` 配置键。 - 提供从旧 runner 配置到 `runner.id` / `runner_config` 的迁移。 -- 将内置 `RequestRunner` 包装成 registry descriptor。 +- 将所有内置 `RequestRunner` 强制迁移为内置插件或官方插件包。 +- LangBot 只保留插件 runtime、registry、orchestrator 和兼容迁移逻辑，不再维护独立的内置 runner 执行分支。 ### Phase 4：为 EBA 接入做预留 - `AgentRunContext.event` 支持 EBA 文档定义的事件 envelope 子集。 -- `AgentRunResult.action.requested` 只记录，不执行。 +- `AgentRunResult.action.requested` 仍只记录，不执行；真正执行平台动作需要等统一平台 API 和事件触发器权限模型完成。 - 等 EBA EventRouter 落地后，由 EventRouter 直接调用 orchestrator。 ## 9. 需要修改的代码范围 @@ -385,16 +391,16 @@ SDK： ## 10. 验收标准 -- 在不修改现有内置 runner 的前提下，Pipeline 可以选择一个插件提供的 Agent Runner。 +- Pipeline 可以选择一个插件提供的 Agent Runner。 - 插件 runner 能收到结构化上下文，并能流式返回消息。 - 插件 runner 只能看到 LangBot 注入的工具、知识库、模型资源。 - 插件 runner 异常不会中断插件 runtime 或 Pipeline 主流程。 - 旧 Pipeline 配置和旧内置 runner 正常工作。 - 文档明确区分“Agent Runner 插件化”和“未来 EBA 架构”。 -## 11. 待确认问题 +## 11. 已确认决策 -- 插件 Agent Runner 是否允许一个插件声明多个 runner。当前分支注释写“一个插件只能提供一个”，但 manifest 和 UI 其实可以支持多个；建议允许多个。 -- `AgentRunResult.action.requested` 在 EBA 前是否只做 telemetry，还是允许有限的 `reply_message` 动作。 -- runner 配置是否跟 Pipeline 绑定，还是未来跟 Bot/Event handler 绑定。当前阶段建议仍跟 Pipeline 绑定。 -- 内置 runner 是否最终迁移到 SDK 插件形式。建议短期只包装，长期再拆。 +- 插件可以声明多个 `AgentRunner` 组件，每个组件独立暴露 manifest、配置 schema、能力和权限。 +- 本阶段不把 `action.requested` 作为必须实现的运行结果。它只是为未来 EBA 平台动作预留的返回类型；当前 Pipeline stage 中如收到该类型，只记录 telemetry，不执行动作。 +- 当前 runner 配置先跟 Pipeline 绑定，仍然在 Pipeline 的 AI runner stage 中执行；后续需要支持直接与 Bot 的事件触发器绑定。 +- 内置 `RequestRunner` 最终强制迁移为插件形态，避免长期保留“内置 runner 分支”和“插件 runner 分支”两套执行体系。