Fusion Agent

本页说明 Studio 里的 Fusion Agent 是怎么从“只在界面里填字段”演进为“以显式 contract 驱动运行”的。

如果你只想知道当前怎么配置，可以直接看下面的 基本操作流程。如果你想理解这次演进解决了什么问题，可以先看这一段：

以前：输入、输出、提示词和运行约束分散在不同配置里，作者主要是在“调页面”
现在：Studio 把这些内容收敛为 live Fusion draft，再通过 Version 固化成不可变 snapshot
结果：每次运行都对应明确的输入契约、输出契约和 profile / prompt 配置，文档抽取、多模态分析和结构化输出更容易保持一致

Fusion 是基于 LangGraph 运行时的Agent 内嵌式定义驱动执行模式。与传统 Agent 不同，它通过显式声明输入/输出字段契约来约束每一次运行，适合需要结构化输入输出的文档处理、信息抽取、多模态分析等场景。

核心概念

概念	说明
Fusion Agent	顶层控制面实体。字段配置、发布、运行入口都直接挂在 Agent 上
Version（版本）	Fusion Agent 的不可变快照，包含输入契约、输出契约、提示词配置和能力绑定
Published version（已发布版本）	被标记为“当前生效”的版本，运行时会使用这个版本执行
Run（运行记录）	一次具体的执行，绑定到某个已发布 `AgentVersion` 快照，记录输入输出和执行状态

基本操作流程

第一步：创建 Fusion Agent

在 Agent 列表中创建一个 agent_type="fusion" 的 Agent。

创建后会直接进入该 Agent 的 Fusion 工作区。此时 Agent 还没有任何已发布字段配置。

第二步：配置字段（编辑 Draft）

进入 Agent 详情页的 Fusion 页签，在这里直接配置当前 Agent 的 live Fusion draft。

配置页分为两部分：Input slots（输入字段） 和 Output slots（输出字段）。页面右上角还提供：

Import JSON：粘贴一份 Fusion 导出的 JSON 文档，直接回填到当前草稿表单
Export Draft JSON：把当前手动编辑但尚未创建版本的草稿一键导出为 JSON

输入字段（Input slots）

每个 Input slot 对应一个调用时需要传入的输入项。点击右侧 > 展开箭头可查看高级选项。

主要字段

字段	说明
`slot_key`	API 调用时使用的字段名，必须是 snake_case（如 `document`、`user_query`），提交后不可修改
`label`	界面展示用的可读名称（如 `上传文档`、`用户提问`）
`input_kind`	输入类型，决定运行时如何处理该字段（见下方类型说明）
`required`	开关，开启后调用时必须提供该字段；关闭则为可选

input_kind 类型说明

类型	用途
`text`	纯文本输入；支持最小/最大字符长度限制
`json`	结构化 JSON 对象；运行时会将其序列化为文本传给模型
`image`	图片文件；调用时传入 base64 编码数据，运行时构建多模态 `image_url` 消息块
`file`	任意文件；`text/csv`、`text/plain`、`application/json` 等文本 MIME 类型会自动解码为文本内联，二进制文件（如 PDF）以占位符描述传给模型

展开后的高级字段（点击 > 展开）

字段	适用类型	说明
`collection_mode`	所有类型	`single`：该字段只接受一个值；`multiple`：接受多个值（数组）
`min_items`	multiple 模式	最少需要提供几个值，默认 0
`max_items`	multiple 模式	最多允许几个值，留空表示不限制
`min_text_length`	`text` 类型	文本最小字符数
`max_text_length`	`text` 类型	文本最大字符数，留空表示不限制
`accepted_mime_types`	`file`、`image` 类型	允许的 MIME 类型列表（如 `image/jpeg`、`application/pdf`），留空表示不限制
`accepted_extensions`	`file`、`image` 类型	允许的文件扩展名列表（如 `.pdf`、`.png`），留空表示不限制
`description`	所有类型	该字段的说明文字，帮助调用方了解填什么内容

输出字段（Output slots）

每个 Output slot 对应模型运行后需要返回的一个输出项。

主要字段

字段	说明
`slot_key`	输出结果中该字段的 key 名，snake_case
`label`	界面展示用的可读名称
`output_kind`	输出类型（见下方类型说明）
`required`	开启后，模型输出中必须包含该字段，缺少时 Run 会以 `output_validation_failed` 失败

output_kind 类型说明

类型	用途
`text`	纯文本回复
`structured_json`	结构化 JSON；需额外声明 schema 字段（字段名、类型、是否必填），运行时强制校验模型输出格式
`image`	图片产物（如图像生成场景）
`file`	文件产物

展开后的高级字段（点击 > 展开）

字段	适用类型	说明
`collection_mode`	所有类型	`single` / `multiple`，同输入字段
`min_items`	multiple 模式	最少返回几个值
`max_items`	multiple 模式	最多返回几个值
`accepted_mime_types`	`image`、`file` 类型	允许的输出文件 MIME 类型
`description`	所有类型	该输出字段的说明文字
`structured_output_schema`	`structured_json` 类型	authoritative nested schema；Studio simple/advanced 编辑器最终都写到这里
`structured_output_profile`	`structured_json` 类型	可选 profile；第一版支持 `document_field_set`，用于单证字段结果的 canonical JSON
`output_instruction_fragment`	`structured_json` 类型	slot 级显式输出提示片段；runtime 直接拼接这个可见配置

structured_json 的 Schema 编辑器

当 output_kind 选择 structured_json 时，Studio 现在同时提供：

Schema fields：浅层 top-level key 的便捷编辑器
structured_output_schema：authoritative nested schema JSON 编辑器
output_instruction_fragment：当前槽显式可见、会直接进入 runtime 的输出提示片段

schema_fields 不再是第二套可编辑真相源。它只是 structured_output_schema 的浅层派生视图；当 schema 超出浅层能力边界时，Schema fields 会退化成只读摘要。

如果某个槽先应用了 document_field_set，后续再切回 none，Studio 现在会：

只移除 structured_output_profile 语义
保留一份当前 materialized structured_output_schema 和 output_instruction_fragment 的参考快照
将可编辑 schema 重置为 shallow starter，让 Schema fields 立刻恢复可编辑
在 inline 提示里提供参考快照、Edit JSON、以及 Reset To Simple Schema 的动作入口

字段	说明
`field_name`	JSON 输出中该字段的 key 名（如 `document_type`、`summary`）
`field_type`	值类型：`string`、`number`、`boolean`、`object`、`array`
`required`	是否为必填字段；必填字段缺失时 Run 会失败
`description`	该字段含义说明，帮助模型理解需要输出什么内容

示例： 如果需要模型分析一份合同并输出摘要和当事方，可以直接在 structured_output_schema 中声明 nested object/array；Studio 会把 Schema Fields 作为派生摘要同步展示复杂结构，但只有浅层 key 仍然适合直接在表格里编辑。

document_field_set Profile

现在 Studio 输出槽编辑器已经直接暴露 structured_output_profile 选择器。对某个 structured_json 输出槽选择 document_field_set 后，Studio 会把该 preset 显式写入当前槽的 structured_output_schema 与 output_instruction_fragment，Fusion runtime 只消费这份持久化后的显式配置。

这个 profile 的几个要点：

不会新增新的 output kind，canonical persisted output 仍然是 output_item_list[].json_value
document_field_set 保留为语义 profile 和附加 validator，而不是 richer schema 的唯一入口
选择该 profile 时，若当前槽已有手工 schema 或 fragment，Studio 会先提示覆盖确认；取消后不会改动当前内容
切回 none 时，Studio 只移除 profile 语义，不会自动清空当前已经 materialize 的 schema / fragment
runtime 不会再根据 profile 水下追加隐藏 schema 或隐藏 prompt

当前默认 preset 不再是硬编码的 fields / tables 示例，而是直接从 Fusion domain 内部 schema catalog 的 ai_service/fusion/domain/output_profile_schemas/booking_confirmation_schema.json materialize：

{
  "booking_number": {
    "value": "BK-001",
    "page_number": 1,
    "bbox": [0.12, 0.08, 0.28, 0.03]
  },
  "from_port": {
    "value": "Shanghai, CN",
    "page_number": 1,
    "bbox": [0.11, 0.15, 0.21, 0.03]
  },
  "to_port": {
    "value": "Los Angeles, US",
    "page_number": 1,
    "bbox": [0.42, 0.15, 0.25, 0.03]
  },
  "routing": [
    {
      "from_location": {
        "value": "Shanghai",
        "page_number": 1,
        "bbox": [0.12, 0.31, 0.16, 0.03]
      },
      "to_location": {
        "value": "Singapore",
        "page_number": 1,
        "bbox": [0.34, 0.31, 0.18, 0.03]
      },
      "mode": {
        "value": "SEA",
        "page_number": 1,
        "bbox": [0.57, 0.31, 0.08, 0.03]
      }
    }
  ]
}

当前默认 preset 的行为约束：

顶层 schema 与 required 字段由 booking_confirmation_schema.json 决定
叶子字段统一使用 { value, page_number, bbox }
bbox 约定为归一化相对页坐标 [x, y, width, height]
数组与嵌套 object 必须保持 schema 中声明的结构
根节点 additional_properties 为 false，默认 preset 不接受未声明字段
document_field_set 的附加 validator 仍会在作者手工采用 canonical fields / tables 形状时检查这些键的基础结构，但它不再决定默认 preset 的字段集合

document_field_set 输出 Profile

后端现在支持在 structured_json 输出槽上声明 structured_output_profile: "document_field_set"，用于单证识别、票据抽取、字段定位等 document-style 场景。

这个 profile 的目标不是替代现有 document_extraction Agent 的完整审核工作流，而是让 Fusion 的 structured_json 输出槽能够稳定表达一类带定位信息的文档抽取 JSON。当前默认 schema 资源位于 ai_service/fusion/domain/output_profile_schemas/booking_confirmation_schema.json。

推荐的顶层 JSON 形状：

{
  "booking_number": {
    "value": "BK-001",
    "page_number": 1,
    "bbox": [0.12, 0.08, 0.28, 0.03]
  },
  "estimated_departure_date": {
    "value": "2026-04-20",
    "page_number": 1,
    "bbox": [0.25, 0.22, 0.14, 0.03]
  },
  "routing": [
    {
      "from_location": {
        "value": "Shanghai",
        "page_number": 1,
        "bbox": [0.12, 0.31, 0.16, 0.03]
      },
      "to_location": {
        "value": "Singapore",
        "page_number": 1,
        "bbox": [0.34, 0.31, 0.18, 0.03]
      }
    }
  ]
}

运行时当前会对该 profile 做两层校验：

generic nested-schema validator 按 materialized structured_output_schema 校验 booking schema
profile-aware validator 仍会对可选的 fields / tables 结构做附加检查；如果 payload 没有这些 key，就不会强制要求它们存在

当前边界：

这是后端 contract / runtime 能力，不是新的 output kind
仍然通过现有 structured_json 槽返回 json_value
Studio 现在已经提供 structured_output_profile 可视化开关，作者可以直接在输出槽表单里选择 document_field_set
JSON 导入导出与已发布 snapshot 导出会保留该字段

第三步：发布 Version

当前工作流是先编辑 Agent 上的 live draft，再点击右上角 Publish Snapshot 生成并发布一个不可变 AgentVersion。

发布后： - Fusion Agent 进入可运行状态 - 新的 Run 将使用这次发布生成的 snapshot 契约执行 - 历史 snapshot 仍会保留在版本列表里，供导出、回放和排障使用

Response Format 设置

Fusion Workspace 现在提供 Response Format 开关：

Enable JSON object response format 会把 enable_json_object_response_format: true 写入该版本的 prompting_config
如果当前模型 provider 不支持 native JSON object response format，Run 会在 governance_context.warnings 里记录降级提示，并继续走 prompt-only structured JSON mode
Convert PDF file inputs to page images 会把 enable_pdf_file_image_conversion: true 写入该版本的 prompting_config
Render DPI 会把 pdf_file_image_conversion_dpi 写入该版本的 prompting_config，默认 150
该设置只对包含至少一个 structured_json 输出槽的版本有效
如果当前草稿没有 structured_json 输出槽，Studio 会给出 inline 提示并阻止创建版本
导出 Draft JSON、导入 JSON、以及版本列表都会保留并展示该字段

这是一个 best-effort 能力。开启后，运行时会优先尝试 LangChain with_structured_output()；但这一步当前只适用于纯 structured_json 输出合约。如果当前 model handle 不支持、调用失败，或者版本同时包含 text/file/image 等非结构化输出槽，系统会继续尝试 provider-native response_format={"type":"json_object"}；如果仍不可用，则回退到原有 prompt-only 路径，不会因此阻塞运行。若 fallback 返回的是合法 JSON object 文本，运行时仍会继续解析并映射到 structured_json 输出槽。

如果 Run 仍然失败，Studio 的 Fusion Run Detail 会显示：

error_code 和 error_message
字段级 validation_error_detail.field_errors
governance_context.warnings
prompt_messages
model_raw_response
normalized_outputs

PDF 图像化开关独立于 JSON object 输出。开启后，Fusion 运行时会把 application/pdf 文件输入渲染为逐页图片并作为 multimodal content blocks 注入模型；关闭时，PDF 仍走原有 generic file 路径，不会被视觉解析。

第四步：触发运行

目前运行通过 API 触发，也可以通过集成的外部系统传入输入后提交到 /agents/{agent_id}/fusion-runs。

第五步：配置 Public Access 与 API Key

Fusion Agent 现在支持三种 public access mode：

模式	行为
`admin_only`	仅允许后台受保护 `/agents/{agent_id}/fusion-runs*` 路径访问
`public_anonymous`	允许匿名访问 `/public/agents/{agent_id}/fusion-runtime` 与 `/public/agents/{agent_id}/fusion-runs*`
`public_api_key`	不出现在匿名 `/public/agents` 目录中；调用 public Fusion route 时必须携带 `x-agent-api-key`

几个关键约束：

public_api_key 只适用于 fusion Agent
public Fusion metadata 总是来自当前 published AgentVersion，不会读取 live draft
public run 不允许借 agent_version_id 执行任意历史 snapshot
public run 的 list/get/download 只会暴露当前 published snapshot 的 run
单个 Agent 可以并存多个活跃 API key，便于轮换

管理员管理 key 的方式：

POST /agents/{agent_id}/public-api-keys 创建新 key
GET /agents/{agent_id}/public-api-keys 查看元数据列表
POST /agents/{agent_id}/public-api-keys/{key_id}/revoke 撤销 key

注意：

明文 key 只会在创建响应中返回一次
服务端只保存 hash，不保存可逆明文
key 认证成功的 public Fusion run 会记录 authenticated_agent_api_key_id

JSON 导入导出

Fusion 现在支持把版本配置作为标准 JSON 交换格式使用。

导出

在 Configure fields 页签中点击 Export Draft JSON，可导出当前草稿
在版本列表中点击 Export JSON，可导出任意已创建版本
在版本详情弹窗中也可直接点击 Export JSON

导入

点击 Import JSON 后，可粘贴以下任一格式：

完整导出文档
仅包含 input_contract、output_contract 等字段的原始 version payload

导入成功后，字段会回填到当前草稿表单，你仍然可以继续手工调整，再点击 Save Draft 或 Publish Snapshot。

支持的能力绑定

版本的 capability_bindings 可配置以下能力：

model — 指定运行所用的 LLM 提供商和模型（支持 OpenAI、Anthropic、DashScope 等）
rag — 绑定知识库，RAG 检索结果会注入到提示词中
mcp — 绑定 MCP 工具服务器，允许模型调用工具
storage — 文件输入/输出的对象存储绑定
image_generation — 图像生成能力绑定

版本是不可变的

版本一旦创建，字段契约就无法修改。如果需要调整字段，请创建新版本，然后发布新版本。这样可以保证历史 Run 记录始终能追溯到当时生效的字段定义。

状态说明

Fusion 内部仍可能保留 hidden definition 兼容行，但那是运行时实现细节，不是产品层需要操作的实体。日常只需要关心 Agent draft、published snapshot 和 run 状态。

Snapshot 状态

状态	含义
`draft`	当前列表项不是 `published_agent_version_id` 指向的生效 snapshot
`published`	当前生效的 snapshot

Run 状态

状态	含义
`pending`	已创建，等待执行
`running`	正在执行
`completed`	执行成功，有输出结果
`failed`	执行失败，可查看 `error_code` 和 `error_message`；校验类失败会在 `error_message` 里直接附带字段级摘要

常见问题

创建了 Fusion Agent 但不知道怎么设置字段

进入 Agent 详情页的 Fusion 页签，然后直接添加 Input slots 和 Output slots。

发布了版本但 Run 一直是 failed

查看 Run 的 error_code： - invalid_definition_contract — 版本契约格式有问题，需要重新创建版本 - invalid_run_input — 传入的输入不满足契约（如缺少必填字段、类型不匹配、数量不足） - output_validation_failed — 模型输出不满足输出契约（如缺少 required 字段）

如果 error_code 是 output_validation_failed，当前 Run 详情里会同时提供两层信息： - 顶层 error_message：直接拼出可读摘要，例如哪个 slot_key、哪个字段缺失或类型不符 - governance_context.validation_error_detail.field_errors：完整字段级明细，适合调试更复杂的 schema / profile 校验失败

想修改字段定义

版本不可修改，需要创建一个新版本重新配置，然后发布新版本。旧版本的 Run 记录不受影响。

输入了图片但模型没有"看到"

确认传入了 file_bytes_base64 字段，且 input_kind 是 image。无 base64 数据的 image slot 会退化为文本占位符。