跳转至

Fusion Runtime

定位

Fusion Runtime 是平台里的正式运行时，不是聊天编排器的别名，也不是只存在于 Studio 里的配置页面。

当前仓库里的 Fusion 已经收敛到一个明确模型：

  • live draft 保存在 agents
  • live public access policy 保存在 agents.public_access_mode
  • publish 会把当前 draft 物化为一个 immutable agent_version
  • publish 会同时把 public_access_mode 物化进 immutable agent_version
  • fusion_runs 始终绑定 agent_version_id
  • run / input / output / governance context 会被持久化，作为审计与排障依据
  • agent_api_keys 以 hash-only 形式持久化 Fusion public credential inventory
  • capability binding，而不是聊天会话状态，是 Fusion 的主要执行入口

如果用当前实现来描述，Fusion 更接近“Agent 持有 draft 与 snapshot 的受控任务运行时”。

与 Agent、Orchestrator 的关系

Agent 仍然是统一控制面实体

Fusion 没有替代 Agent。

当前实现里：

  • Agent 承载 live Fusion runtime draft
  • AgentVersion 承载 immutable Fusion runtime snapshot
  • FusionRun 记录一次真实执行
  • published_agent_version_id 指向当前默认运行时快照

也就是说，Agent 负责被管理，Fusion Runtime 负责被执行，而 AgentVersion 是两者之间的 immutable 边界。

Orchestrator 不是 Fusion 的上位概念

当前代码对 orchestrator 的定义仍然是：

  • 它是 chat 运行时内部的二级选择
  • agent_type 才是更粗粒度的顶层运行时分流

因此：

  • chat runtime 继续按 orchestrator_key 细分
  • fusion runtime 不依赖 chat orchestrator registry 才能成立
  • POST /agents/{agent_id}/fusion-runs 仍支持 JSON input_item_list 与 multipart form-data；上传文件时，表单字段名直接对应 input slot key

当前核心模型

flowchart LR
  Agent[Agent<br/>live Fusion draft]
  Ver[AgentVersion<br/>immutable Fusion snapshot]
  Run[Fusion Run<br/>one execution]
  Gov[Governance Context<br/>persisted snapshot]

  Agent -->|publish| Ver
  Agent -->|default pointer| Ver
  Ver -->|1:N| Run
  Agent -->|inherit defaults| Gov
  Gov -->|persisted on run| Run

关键结论：

  • Fusion Runtime 的主执行单位是 run
  • 默认执行目标不是 live draft，而是 published agent_version
  • run 会持久化治理快照，避免后续 Agent 挂载变化污染历史解释

当前执行链路

flowchart LR
  Load[load agent snapshot] --> ValidateContract[validate snapshot contract]
  ValidateContract --> ValidateInputs[validate run inputs]
  ValidateInputs --> PersistInputs[persist validated inputs]
  PersistInputs --> ResolveBindings[resolve capability bindings]
  ResolveBindings --> PrepareArtifacts[prepare file artifacts]
  PrepareArtifacts --> Retrieve[retrieve context]
  Retrieve --> Prompt[build prompt]
  Prompt --> Plan[plan tool usage]
  Plan --> Tools[invoke tools]
  Tools --> Model[invoke model]
  Model --> Normalize[normalize outputs]
  Normalize --> ValidateOutputs[validate outputs]
  ValidateOutputs --> PersistOutputs[persist outputs]
  PersistOutputs --> Finalize[finalize run]

这些阶段当前都有对应实现，不是设计占位：

  • ai_service/fusion/infrastructure/runtime/graph.py
  • ai_service/fusion/infrastructure/runtime/nodes.py
  • ai_service/fusion/infrastructure/runtime/runner.py
  • ai_service/fusion/domain/validation.py
  • ai_service/fusion/infrastructure/runtime/output_mapper.py
  • ai_service/fusion/infrastructure/runtime/prompt_builder.py

对于 structured_json 输出，当前 runtime 会按以下优先级尝试：

  1. LangChain with_structured_output()，前提是当前 model handle 暴露该能力，且 output contract 是纯 structured_json 合约
  2. provider-native response_format={"type":"json_object"}，前提是当前 provider 被标记为支持
  3. prompt-only structured JSON 路径，再由 output_mapper + validator 做最终收敛与校验

如果某一步不可用或失败，runtime 不会中断该 run，而是把原因写入 governance_context.warnings，然后继续走后备路径。

当前能力绑定

Fusion runtime 不直接假设“只靠一个模型说话”，而是先把 snapshot 里的 binding 解析为可执行能力。

当前至少包括：

  • model
  • rag
  • mcp
  • storage
  • image_generation

对应代码位于：

  • ai_service/fusion/infrastructure/adapters/model_binding.py
  • ai_service/fusion/infrastructure/adapters/rag_binding.py
  • ai_service/fusion/infrastructure/adapters/mcp_binding.py
  • ai_service/fusion/infrastructure/adapters/storage_binding.py
  • ai_service/fusion/infrastructure/adapters/image_generation_binding.py

当前继承行为

如果 Fusion snapshot 中的 binding 没有显式指定 agent_id，runtime 会默认落到当前 run 的 owning agent_id 上，而不是推断另一套外部主体。

典型行为包括：

  • rag.agent_id 未显式指定时，默认继承当前 Agent
  • mcp.agent_id 未显式指定时，默认继承当前 Agent
  • snapshot 显式指定时，以 snapshot 配置为准

所以 Fusion 不是脱离主平台的孤立沙盒，而是一个可继承平台治理上下文的运行时。

当前持久化与 API 面

Fusion 当前的核心持久化对象包括：

  • agents 上的 live Fusion draft 字段
  • agents.public_access_mode
  • agent_versions 上的 immutable Fusion snapshot 字段
  • agent_versions.public_access_mode
  • agent_api_keys
  • fusion_runs
  • fusion_run_inputs
  • fusion_run_outputs

当前主控制面 API 包括：

  • PATCH /agents/{agent_id} 保存 live Fusion draft
  • GET /agents/{agent_id}/versions
  • POST /agents/{agent_id}/publish
  • POST /agents/{agent_id}/rollback

当前运行时 API 包括：

  • POST /agents/{agent_id}/fusion-runs
  • GET /agents/{agent_id}/fusion-runs
  • GET /agents/{agent_id}/fusion-runs/{run_id}
  • GET /public/agents/{agent_id}/fusion-runtime
  • POST /public/agents/{agent_id}/fusion-runs
  • GET /public/agents/{agent_id}/fusion-runs
  • GET /public/agents/{agent_id}/fusion-runs/{run_id}

当前公开访问策略包括：

  • public_access_mode=admin_only：Fusion 只允许受保护控制面访问
  • public_access_mode=public_anonymous：匿名可访问 /public/agents/{agent_id}/fusion-runtime 与 /fusion-runs*
  • public_access_mode=public_api_key：必须携带 x-agent-api-key 才能访问 public Fusion route
  • public Fusion metadata 始终来自 published_agent_version_id 指向的 immutable snapshot，而不是 live draft
  • public Fusion 的 list/get/download 只暴露绑定到当前 published_agent_version_id 的 run，不公开历史 snapshot run
  • public API key 只在创建成功响应里回传一次明文；服务端后续只保存 hash、prefix 和元数据

这说明 Fusion 已经是平台 API 与存储模型中的一等运行时对象，但它的 draft 与 snapshot 边界已经并入通用 Agent 体系。

当前边界

Fusion Runtime 适合回答这类问题：

  • 需要显式输入 / 输出契约吗
  • 需要把 live draft 与 published snapshot 分层吗
  • 需要把一次执行完整持久化吗
  • 需要把模型、RAG、MCP、文件处理组合为一个受控 run 吗

它不等同于：

  • 长期多轮聊天 session runtime
  • chat orchestrator 的一个皮肤
  • 单纯的 Studio 配置页面

对命名修复的启发

如果从当前实现反推命名，最稳妥的结论是：

  • chat、etl、document_extraction、fusion 实际承担的是顶层运行时分流
  • orchestrator_key 只是 chat runtime 内部的细分选择

因此后续如果要修复概念漂移，更合理的方向是把 agent_type 逐步收敛为更接近运行时语义的名字，例如：

  • runtime_kind
  • agent_runtime_type

但在真正改代码之前，文档需要先统一表达：Fusion 是正式 runtime，而 AgentVersion 才是它的 immutable snapshot 边界。

相关阅读