LangBot/docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md

LangBot Host 与 SDK 基础设施设计

本文档描述 LangBot 和 SDK 为插件化 AgentRunner 共同提供的基础设施。它不以 Pipeline 为中心，也不以官方 local-agent 的实现方式为前提。

1. 目标

LangBot 要转为 agent host，而不是内置 runner 容器：

• 接收 IM、WebUI、API 和未来 EventRouter 产生的事件。
• 根据事件、bot、workspace、scope 解析应该调用的 agent binding。
• 发现、校验和调用插件提供的 AgentRunner。
• 为每次 run 提供受限资源、状态、存储、上下文引用和生命周期控制。
• 接收 AgentRunner 返回的事件流，并投递到 IM、WebUI 或其他 output surface。

SDK 要提供稳定协议：

• AgentRunner 组件定义。
• runner manifest / capabilities / permissions / config schema。
• AgentRunContext 输入 envelope。
• AgentRunResult 输出事件流。
• AgentRunAPIProxy 运行期受限 API。

2. 非目标

• 不把 Pipeline 当作长期架构中心。
• 不要求所有 AgentRunner 依赖 LangBot 的上下文管理。
• 不要求官方 local-agent 的旧行为反向塑造 host 协议。
• 不在 host 中实现通用 agentic prompt assembler。
• 不强制 runner 使用 LangBot state / storage；LangBot 只提供可选、受控的寄宿能力。

3. 分层架构

目标结构：

IM / WebUI / API / EventRouter
        |
        v
Event Gateway
        |
        v
AgentBindingResolver
        |
        v
AgentRunOrchestrator
        |-- AgentRunnerRegistry
        |-- AgentResourceBuilder
        |-- AgentContextBuilder
        |-- AgentRunSessionRegistry
        |-- AgentStateStore / Storage / EventLog / ArtifactStore
        v
Plugin Runtime / AgentRunner
        |
        v
AgentRunResult stream
        |
        v
Delivery / Renderer / Platform API

当前 Pipeline 只应接入在 Event Gateway 或兼容 adapter 位置。它可以继续产生 message.received，但不应继续拥有 runner 选择、上下文裁剪和业务 agent 执行的核心语义。

4. LangBot 侧能力

4.1 Event Gateway

Event Gateway 负责把入口统一成 host event：

• IM 平台消息。
• WebUI debug chat 消息。
• API 触发。
• 后续非消息事件，例如入群、撤回、好友申请。

输出应是稳定 envelope，而不是 Pipeline Query 私有结构：

class AgentEventEnvelope(BaseModel):
    event_id: str
    event_type: str
    event_time: int | None
    source: str
    bot_id: str | None
    workspace_id: str | None
    conversation_id: str | None
    thread_id: str | None
    actor: ActorRef | None
    subject: SubjectRef | None
    input: AgentInput
    delivery: DeliveryContext
    raw_ref: RawEventRef | None

原始平台 payload 可以存为 raw event 或 artifact ref；不要把平台私有字段直接扩散到 AgentRunner 顶层协议。

4.2 Agent Binding

Agent binding 是“什么事件调用哪个 runner、带什么绑定配置”的持久配置。它替代长期依赖 Pipeline runner config 的角色。

建议模型：

class AgentBinding(BaseModel):
    binding_id: str
    scope: BindingScope
    event_types: list[str]
    runner_id: str
    runner_config: dict[str, Any]
    resource_policy: ResourcePolicy
    state_policy: StatePolicy
    delivery_policy: DeliveryPolicy
    enabled: bool

Pipeline 当前可以被迁移为一种 binding source：

• 旧 Pipeline AI runner config -> AgentBinding
• 旧 Pipeline extension preference -> resource_policy
• 旧 Pipeline output settings -> delivery_policy

但新设计不应再把这些字段命名为 Pipeline 专属概念。

4.3 AgentRunnerRegistry

Registry 负责收集 runner descriptor：

• 插件 runtime 提供的 AgentRunner。
• 可能存在的 host adapter runner。
• 开发期本地插件 runner。

Descriptor 必须包含：

class AgentRunnerDescriptor(BaseModel):
    id: str
    source: Literal["plugin", "host_adapter"]
    label: I18nObject
    description: I18nObject | None = None
    capabilities: AgentRunnerCapabilities
    permissions: AgentRunnerPermissions
    config_schema: list[DynamicFormItemSchema]
    plugin: PluginRef | None = None

plugin:author/name/runner 仍可作为稳定 id 格式。多个 binding 指向同一个 runner id 时，不创建多个插件实例。

4.4 AgentRunOrchestrator

Orchestrator 是唯一运行入口：

run(event, binding)
  -> resolve runner descriptor
  -> build resources
  -> build context
  -> register run session
  -> call plugin runtime
  -> normalize result stream
  -> update state
  -> unregister run session

它负责：

• run_id 生成和生命周期。
• timeout / deadline / cancellation。
• 插件异常隔离。
• result schema 校验和大小限制。
• state.updated 处理。
• delivery backpressure 和 telemetry。

run_from_query() 这类 API 可以保留为兼容 adapter，但内部应转换成 event + binding 后走统一 run()。

4.5 Resource Authorization

LangBot 在每次 run 前生成 ctx.resources。资源来自三层约束：

• runner manifest 声明的 permissions。
• binding/resource policy 允许的资源范围。
• 当前 event / actor / bot / workspace 的实际权限。

资源类型包括：

• models
• tools
• knowledge bases
• files / artifacts
• storage
• platform capabilities
• history / transcript access

运行期 action 必须再次通过 run_id 校验。SDK 侧本地校验只用于开发体验，host 侧校验才是安全边界。

4.6 State 与 Storage

LangBot 可以提供 host-owned state，让 AgentRunner 把状态寄宿在 LangBot：

• conversation state
• actor state
• subject state
• runner/binding state
• workspace state

但这不是强制。外部 agent runtime 可以维护自己的 session 和 memory。LangBot 只需要提供：

• 授权开关。
• scope key。
• get/set/list/delete API。
• 持久化 backend。
• 审计和清理策略。

当前进程内 state store 只能作为过渡实现，不能作为正式生产语义。

4.7 EventLog / Transcript / Artifact

LangBot 应提供事实源能力：

• EventLog: 保存原始事件、系统事件、工具调用、投递结果、错误。
• Transcript: 面向对话 UI / agent history 的消息投影。
• ArtifactStore: 保存大文件、多模态输入、工具大结果、平台附件。

AgentRunner 可以读取这些能力，但不能被迫使用 LangBot 作为唯一记忆系统。

5. SDK 侧协议

5.1 AgentRunner 组件

class AgentRunner(BaseComponent):
    __kind__ = "AgentRunner"

    @classmethod
    def get_capabilities(cls) -> AgentRunnerCapabilities:
        ...

    @classmethod
    def get_config_schema(cls) -> list[dict]:
        ...

    async def run(self, ctx: AgentRunContext) -> AsyncGenerator[AgentRunResult, None]:
        ...

5.2 Capabilities

建议能力声明：

capabilities:
  streaming: true
  tool_calling: true
  knowledge_retrieval: true
  multimodal_input: true
  event_context: true
  platform_api: false
  interrupt: true
  stateful_session: true
  self_managed_context: true
  host_state: optional

self_managed_context 表示 runner 或外部 runtime 自己管理上下文。Host 不应给它强塞历史窗口，只提供当前事件和 context handles。

5.3 Permissions

permissions:
  models: ["invoke", "stream", "rerank"]
  tools: ["detail", "call"]
  knowledge_bases: ["list", "retrieve"]
  history: ["page", "search"]
  artifacts: ["metadata", "read"]
  storage: ["plugin", "workspace", "binding"]
  platform_api: []

权限声明是 runner 需要的最大能力，实际可用资源仍由 binding 和当前运行上下文裁剪。

5.4 AgentRunContext

Context 顶层应是 event-first，而不是 Query-first：

class AgentRunContext(BaseModel):
    run_id: str
    trigger: AgentTrigger
    event: AgentEventContext
    conversation: ConversationContext | None = None
    actor: ActorContext | None = None
    subject: SubjectContext | None = None
    input: AgentInput
    resources: AgentResources
    context: ContextAccess
    state: AgentRunState
    runtime: AgentRuntimeContext
    config: dict[str, Any]

messages 可以作为兼容字段或 bootstrap 字段，但不应继续是协议核心。

5.5 AgentRunResult

输出应是事件流：

class AgentRunResult(BaseModel):
    type: Literal[
        "message.delta",
        "message.completed",
        "tool.call.started",
        "tool.call.completed",
        "state.updated",
        "artifact.created",
        "action.requested",
        "run.completed",
        "run.failed",
    ]
    data: dict[str, Any] = {}

当前消息回复只消费 message.delta / message.completed / run.failed。平台动作执行等 EBA 和 platform API 权限落地后再启用。

5.6 AgentRunAPIProxy

Proxy 是 runner 访问 host 能力的唯一入口：

• model APIs
• tool APIs
• knowledge APIs
• state / storage APIs
• history / event APIs
• artifact APIs
• platform APIs

所有请求必须带 run_id，host 侧按 active run session 验证 runner identity 和 resource ACL。

6. 当前实现与目标差距

已落地：

• AgentRunnerRegistry
• AgentRunOrchestrator
• AgentRunContextBuilder
• AgentResourceBuilder
• AgentRunSessionRegistry
• AgentRunAPIProxy 基础模型 / 工具 / 知识库授权路径

需要调整：

• 把 pipeline_config 语义抽象为 AgentBinding。
• 把 Query 输入抽象为 AgentEventEnvelope。
• 把 legacy max-round 从目标设计中移除，只作为旧配置兼容处理。
• 把 state store 改为持久 host storage backend。
• 增加 EventLog / Transcript / ArtifactStore。
• 增加 history / artifact / event 的受限拉取 API。

7. 落地顺序

1. 固化 README 路由和专题文档边界。
2. 在 Host 中抽象 AgentBinding，先由 Pipeline adapter 生成。
3. 将 AgentRunContextBuilder 改为 event-first。
4. 增加持久 transcript/event log 的最小存储模型。
5. 扩展 AgentRunAPIProxy 的 history / artifact / state API。
6. 将 Pipeline-only 字段逐步下沉到兼容 adapter。
7. 再设计官方 local-agent 插件如何消费这些基础设施。