跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

核心导入器

编译器的仓库自行构建十个导入器插件,每种源格式一个,并随每个编译器版本一同发布:

Plugin服务对象读取内容
importer/langflowimport:langflow从 Langflow 导出的 flow,格式为 JSON
importer/flowiseimport:flowise从 Flowise 导出的 chatflow 或 agentflow,格式为 JSON
importer/n8nimport:n8n从 n8n 导出的 workflow,格式为 JSON
importer/mcpimport:mcpMCP 客户端的配置——.mcp.json、claude_desktop_config.json、.vscode/mcp.json 或 .cursor/mcp.json——或 MCP 注册表的服务器描述 server.json,格式为 JSON
importer/composeimport:composeCompose 应用——compose.yaml、docker-compose.yml 及其覆盖文件——格式为 YAML
importer/difyimport:dify以 Dify DSL 从 Dify 导出的应用,格式为 YAML
importer/crewaiimport:crewaiCrewAI 项目声明的 agent 和 task——config/agents.yaml 和 config/tasks.yaml,格式为 YAML;或 crew.jsonc 和 agents/<name>.jsonc,或其严格 JSON 写法 crew.json 和 agents/<name>.json,格式为带注释的 JSON
importer/langgraphimport:langgraphLangGraph 应用的配置 langgraph.json,格式为 JSON;以及该配置指定的环境文件中仅变量名,前提是该文件通过 with.sources 交给导入
importer/google-adkimport:google-adk基于 Google ADK 构建的应用在其 Agent Config 文件中声明的 agent——root_agent.yaml 及其子 agent 指定的配置——格式为 YAML
importer/agent-frameworkimport:agent-frameworkMicrosoft Agent Framework 声明式 agent,即任意名称、类型为 Prompt 的文档,格式为 YAML

每个导入器都由编译器自身的源码构建,并标记编译器的版本,因此随 X.Y.Z 版编译器发布的导入器报告版本 X.Y.Z,其 Plugin 实体也记录该版本。与嵌入式插件中列出的插件不同,它们都不编译进二进制文件。二进制文件携带每个导入器的 Plugin 实体,以及它为该实体接受的唯一模块的摘要,因此每个导入器都在所有工作区中服务其格式,无需在目录中添加条目。

这十个导入器都基于 Go 工具包的 importer 包 github.com/aggrega-ai/aggrega-pdk/go/pkg/importer 构建。对于 Langflow、Flowise 和 n8n 导入器,导入器无论格式如何都要做的一切——将工作区目录中的 Components 与每个节点进行评分匹配、决定引用已有的还是起草新的、排布草稿、携带其中的凭据值或按设置要求将其写为空值、写出草稿以及读取下文的设置——都由该包完成,只有读取格式以及了解其 flow 所运行的平台是各导入器特有的。MCP 导入器为每个服务器起草一个 Component 的实例,因此不做任何评分;它与该包共享所读设置的读取方式、对凭据值的判断,以及草稿命名和描述所遵循的约定,详见 MCP 导入器。Compose 导入器通过同一个包,以 flow 导入器判断节点的方式判断它匹配的每个服务,以相同方式渲染草稿,并像 MCP 导入器一样共享其余部分,详见 Compose 导入器。Dify 导入器通过同一个包的平台草稿(采用适用于整体安装型平台的形式),起草标准库组装的 Dify 安装并携带该应用,详见 Dify 导入器。CrewAI 导入器为项目声明的每个 agent 起草一个标准库 CrewAI agent 的实例,连接到其指定的模型,并像 MCP 导入器一样共享其余部分,详见 CrewAI 导入器。LangGraph 导入器为应用配置声明的每个 graph 起草一个标准库 LangGraph agent 的实例,连接到其 checkpointer 保存状态的数据存储,并像 MCP 导入器一样共享其余部分,详见 LangGraph 导入器。Google ADK 导入器为应用配置声明的每棵 agent 树起草一个标准库 ADK agent 的实例,在 ADK 将请求发送到 Gemini API 的情况下连接到该树指定的模型,并像 MCP 导入器一样共享其余部分,详见 Google ADK 导入器。Agent Framework 导入器为每个声明式 agent 起草一个标准库 Agent Framework agent 的实例,连接到其指定的 OpenAI 模型——它指定的每个 MCP 服务器都写在注释中,因为模型的提供方以托管工具的形式访问它——并像 MCP 导入器一样共享其余部分,详见 Agent Framework 导入器。导入器插槽的工作方式及其接收的内容,见导入器插槽。

本页是每个导入器读取什么、起草什么的参考。要导入你自己的项目并构建结果,请从 导入 开始,它按格式逐一讲解如何将项目从源文件一路带到构建。

导入如何获取核心导入器

aggrega import、编辑器会话的 aggrega/import 方法和助手的 import 工具以相同方式获取核心导入器。如果本机已持有其模块(位于工作区的内容缓存中),导入会从那里读取,无需为此访问网络。如果本机没有,第一次需要它的导入会按编译器的版本从工作区的默认注册表获取它,并且:

  • 将其与二进制文件携带的摘要进行比对,因此只有编译器的 Release 所发布的模块 才会运行;
  • 像拉取操作验证其获取的插件那样验证它:依据该注册表的信任 策略验证其签名,并依据其 Plugin 实体记录的宿主函数验证它所使用的宿主函数;
  • 将其保存在工作区的内容缓存中,这是为它写入的唯一内容:没有锁文件,也没有受信任插件的记录,因为导入不固定任何导入器。

之后的每次导入都从内容缓存中读取它。未通过验证的模块会被拒绝,并且 不保存任何内容。在没有工作区标记的文件夹中,没有可用于保存它的内容缓存,因此获取 会在那里被拒绝,并指出该文件夹以及如何指定工作区或将该文件夹设为工作区。该模块 绝不会从目录文件夹中另一版本的同名 Plugin 实体旁读取: 那个模块属于另一个实体。

无法获取该模块时,导入会在 A plugin’s .wasm is not on this machine(插件的 .wasm 不在此机器上) 下停止,指明该导入器及其版本,并说明如何将其模块放到本机上:

  • 在网络可用时运行一次导入,适用于工作区处于离线状态或其注册表 无法访问的情况。该次运行会获取它,之后的每次运行都可离线进行。
  • 将其模块放在目录文件夹中该导入器该版本的 Plugin 实体旁边,使用消息给出的名称,例如 Langflow 导入器为 importer--langflow.wasm。与核心导入器同名同版本的目录实体会代替它运行,其模块从它旁边读取;旁边没有模块的此类实体则不会代替它运行,核心导入器仍按上述方式获取。如果注册表中没有该模块,或者工作区未指定默认注册表,这就是消息给出的唯一补救措施。

与你自己的导入器并存时运行哪一个

核心导入器与你的工作区目录中的导入器一同作为候选,按照选择所有导入器的规则进行选择,这些规则见哪个导入器将源转换为草稿:

  • 在同一名称内,运行最高版本,或运行 plugins.importer 条目指定的版本。
  • 如果你的目录中有另一名称的导入器用于 langflow、flowise、n8n、mcp、compose、dify、crewai、langgraph、google-adk 或 agent-framework,则有两个导入器 声明该格式,未附加其中任何一个的导入会被拒绝并列出两者,错误为 A parse or import format is advertised by more than one plugin(某个解析或导入格式由多个插件声明)。 用一个 plugins.importer 条目指定你想要的那个即可解决。
  • 你的目录中与某个核心导入器名称和版本都相同、且模块位于其实体旁的导入器,就是实际运行的那个,从那里读取。
  • 名称与某个核心导入器相同、但在其目录文件夹中旁边没有模块的 Plugin 实体——例如某个目录的检出,其中记录了某次版本发布所发布的导入器——是任何导入都无法运行的实体,因为其模块不会从其他任何地方读取;因此它不是运行候选,尽管它记录的签名仍参与源的识别。在编译器自身的版本下,核心导入器代替它运行。在其他任何版本下,无论更旧还是更新,它都会被跳过,并在可以运行的导入器之间进行选择——除非某个 plugins.importer 条目恰好指定该版本,或者该名称下没有可以运行的导入器声明所请求的格式,例如该实体记录了编译器自身导入器未记录的格式。这时它仍按上述规则作为候选,选择它的导入会停止,并指出其模块应放入的文件夹。

无论选中的是你目录中自己的哪个导入器,其模块都从它自己的实体旁、按它自己的版本读取:放在另一版本同名实体旁的模块属于那个实体。

如何识别来源

未使用 --format 指明格式的导入,按各导入器声明的签名进行识别:

  • Langflow —— 可解析为 JSON,且在 data.nodes 处带有数组的来源。
  • Flowise —— 可解析为 JSON,在 nodes 和 edges 处带有数组,且 在 data.nodes 处没有任何内容的来源。
  • n8n —— 可解析为 JSON,在 nodes 处带有数组、在 connections 处带有对象,且在 edges 和 data.nodes 处都没有任何内容的来源。
  • MCP —— 可解析为 JSON、名为 .mcp.json、claude_desktop_config.json 或 .cursor/mcp.json,且在 mcpServers 处带有对象的来源;可按 Visual Studio Code 的读取方式解析为带注释的 JSON、 名为 .vscode/mcp.json,且在 servers 处带有对象的来源;或任意名称、可解析为 JSON,且其 $schema 是以 https://static.modelcontextprotocol.io/schemas/ 开头的文本的来源,即注册表服务器描述。名称与 导入所接收路径的末尾进行匹配,因此 project/.vscode/mcp.json 能被识别,而 从 .vscode 内部传入的 mcp.json,或任何其他名称的客户端文件,需通过 指定 --format mcp 导入。
  • Compose —— 可解析为 YAML,名称为 Compose 默认读取的 Compose 文件或其覆盖 文件名称 —— compose.yaml、compose.yml、docker-compose.yml、docker-compose.yaml、 compose.override.yml、compose.override.yaml、docker-compose.override.yml 或 docker-compose.override.yaml —— 且在 services 处带有对象的来源。任何其他 名称的 Compose 文件需通过指定 --format compose 导入。
  • Dify —— 任意名称、可解析为 YAML、在 kind 处带有文本 app,且 在 app.mode 和 version 处都带有内容的来源,Dify 导出的每个应用都是如此。
  • CrewAI —— 名为 config/agents.yaml 或 config/tasks.yaml 且可解析为 YAML 的来源; 名为 crew.jsonc 或 crew.json、可解析为带注释的 JSON 且在 agents 处带有列表的来源;或名为 agents/<name>.jsonc 或 agents/<name>.json、可解析为带 注释的 JSON 且在 role 处带有内容的来源。经典项目以其作者自选的名称作为其 agent 和任务的键,因此其 两个文件仅凭名称区分。
  • LangGraph —— 名为 langgraph.json、可解析为 JSON 且在 graphs 处带有对象的来源; 或任意名称、可解析为 JSON、在 graphs 处带有对象,且其 $schema 为 文本 https://langgra.ph/schema.json(LangGraph 为其配置发布的 schema)的来源。 其他名称且未指明 schema 的配置需通过指定 --format langgraph 导入。没有任何 导入器的签名指定环境文件,因此识别目录时不会打开任何环境文件。
  • Google ADK —— 名为 root_agent.yaml、可解析为 YAML,且像 LlmAgent 的配置那样在 name 和 instruction 处带有内容,或像其他任何 agent 的配置那样在 agent_class 处带有文本并在 name 处带有内容的来源。其他名称的配置需通过指定 --format google-adk 导入。没有签名指定子 agent 的配置,其名称可以任意, 因此识别目录时除 root_agent.yaml 外不会打开任何 YAML 文件。
  • Agent Framework —— 任意名称、可解析为 YAML,且像指明其模型的声明式 agent 那样在 kind 处带有文本 Prompt 并在 model 处带有对象的来源;Agent Framework 从其应用指定的任意文件加载 声明式 agent,因此该签名不指定文件。未指明模型,或以其他大小写或以 Agent 书写其 kind 的声明式 agent, 需通过指定 --format agent-framework 导入。

与其中两个同时匹配的来源会被拒绝并指出这两种格式,通过 --format 指明其中一个即可导入。Langflow、Flowise、n8n 和 LangGraph 导入器通过提供 parse:json 的解析器读取其来源;MCP 导入器将在 servers 下列出其服务器的配置通过提供 parse:jsonc 的解析器读取,其他所有来源则通过提供 parse:json 的解析器读取;Compose、Dify、Google ADK 和 Agent Framework 导入器通过提供 parse:yaml 的解析器读取;CrewAI 导入器将经典项目的文件通过提供 parse:yaml 的解析器读取,其他文件通过提供 parse:jsonc 的解析器读取:即你的工作区目录所提供的解析器(若有提供),否则为编译器自身针对该语法携带的解析器(参见 Embedded plugins)。因此通过其中任何一个导入都不需要你的目录中有解析器,也不会为此获取任何内容。你的目录确实提供的解析器即为所用的解析器,编译器自带的解析器不起作用。Langflow、Flowise、n8n、Dify 和 Agent Framework 导入器不声明文件模式,因此每个只读取一个文件,通过它们中任何一个导入目录都会被拒绝;MCP 导入器声明了四个客户端文件名,因此目录通过其中包含的客户端配置读取;Compose 导入器声明了八个 Compose 文件名,因此目录通过其中包含的 Compose 文件读取;CrewAI 导入器声明了项目声明的六个名称,因此项目目录仅通过其声明读取,不读取其他任何内容;LangGraph 导入器声明了 langgraph.json,因此应用目录仅通过其配置读取,绝不会读取其代码或环境文件;Google ADK 导入器声明了 root_agent.yaml,因此应用目录仅通过其根配置读取 —— 其子 agent 所指定的配置只有在其挂载的 with.sources 下才会到达导入器 —— 绝不会读取其代码或环境文件。不指定文件的签名 —— Langflow、Flowise 和 n8n 导入器的签名、MCP 导入器针对注册表服务器描述的签名、LangGraph 导入器针对指明其 schema 的配置的签名、Dify 导入器和 Agent Framework 导入器的签名 —— 适用于每个单独导入的文件:未指明格式的导入会将此类文件分别按 JSON 和 YAML 读取以进行尝试,无论它面向哪个导入器,都通过上述相同的解析器 —— 编译器两者都携带,因此两者都无需获取任何内容。包含注释或尾随逗号的文件无法解析为 JSON,因此任何读取 JSON 的签名都不会识别它;CrewAI 导入器针对 crew.jsonc、agents/<name>.jsonc 及其 .json 写法的签名,以及 MCP 导入器针对 .vscode/mcp.json 的签名,读取带注释的 JSON,在你的目录未提供解析器时通过编译器针对该语法携带的解析器读取。

被其解析器拒绝的来源 —— 对 Langflow、Flowise、n8n 和 LangGraph 导入器而言是非 JSON 的来源,对 MCP 导入器而言是非带注释 JSON 的来源,或者(除非其在 servers 下列出服务器)非 JSON 的来源,对 Compose、Dify 和 Agent Framework 导入器而言是 非 YAML 的来源,对 CrewAI 导入器而言是非 YAML 或非带注释 JSON 的声明,对 Google ADK 导入器而言是非 YAML 的配置 —— 会以 parse-failed 终止导入,其消息包含解析器自身给出的原因。指明格式不会改变这一点: 导入器请求来源的树,而解析器的拒绝就是它得到的答复。

草稿如何命名

每个导入器都把它起草的 Aggregate,以及它在起草 Release 时与之并列的 Release,命名为 <target_namespace>/<name>。第一部分是 target_namespace 设置,除非你另行设置,否则为 imported。<name> 取以下各项中第一个非空的值:

  • 源为自身指定的名称,取自其格式声明该名称的字段:

    导入器读取的名称
    importer/langflow流程的 name
    importer/flowise无:导出文件不带有自己的名称
    importer/n8n工作流的 name
    importer/mcp注册表服务器描述的 name;客户端的配置不带有名称
    importer/compose项目的顶层 name;按照 Compose 合并文件的方式,覆盖文件中的名称取代其所覆盖文件中的名称
    importer/dify应用程序的 name,位于 app 之下
    importer/crewaicrew.jsonc 或 crew.json 中 crew 的 name;config/agents.yaml 和 config/tasks.yaml 不带有名称,因为经典项目在其程序中为 crew 命名
    importer/langgraph配置所声明的图的 id,因为配置不带有自己的名称
    importer/google-adk根智能体的 name
    importer/agent-framework智能体的 name;不读取其 displayName
  • 交给导入的目录的完整名称——my.project 保留其句点,写作 my-project——正如 Compose 以包含项目的目录为项目命名;aggrega import . 指的是它运行所在的目录;

  • 单独交给导入的文件的名称,不含扩展名;

  • flow。

由多个源生成的草稿——多个 Compose 项目、配置、智能体树或服务器,或声明多个图的一个配置——只有在每个源都为自身命名且所有名称写法相同时才采用它们的名称;否则采用下一项。名称以小写书写,除 ASCII 字母和数字以外的每一串连续字符写作一个连字符,并去掉两端的连字符:Basic Prompting 写作 basic-prompting,SupportAgent 写作 supportagent。同一个源在每次导入时都以相同方式命名。导入为某个目标起草的 Manifest 采用 Release 的名称,若未起草 Release 则采用 Aggregate 的名称,如 目标添加了什么 所述。

Langflow 导入器读取的内容

  • 流程顶层 data 对象下的节点和边,即 data.nodes 和 data.edges。
  • 对每个节点,从节点的 data.type 读取其类型,并从 data.node.template 中值为带有 type 的对象的条目读取其字段。模板的其他条目 不是字段。
  • 对象带有 password: true 的字段被起草为凭据槽,其他每个 字段被起草为值字段。字段的名称不起作用,将节点起草为 Component 时不读取 任何字段的值。
  • 固定在画布上的注释,即类型为 noteNode 的节点,不会被导入;指向未被导入的节点的边 会被丢弃。
  • 起草承载该流程的平台时,还会从流程中读取:其顶层 id;每个标记为 password: true 的字段的 值;MCP Tools 节点的 mcp_server 字段——它指定的 MCP 服务器及该服务器的配置——或者它改为存放服务器的那些字段;Langflow 标记为非凭据、但可以承载凭据的每个输入, 如 流程持有的凭据值 所列;节点指定其模型的字段,以及它所运行的模型提供方;以及节点用来访问某个部件的地址和密钥、并会将其改写的那些字段。 它们起草的内容 说明了每一项的去向。

Flowise 导入器读取的内容

  • 流程顶层的节点和边,即 nodes 和 edges。
  • 对每个节点,从节点的 data.name 读取其类型;从 data.inputParams 中 type 为 credential 的条目读取其凭据槽,按其 name 区分;从 data.inputs 的键读取其值字段,但不包括 data.inputAnchors 所列的键(即另一个节点接入之处,由两者之间的边记录), 也不包括凭据。
  • 将节点起草为 Component 时不读取任何字段的值,凭据的名称也不影响它是否被视为凭据。
  • 固定在画布上的注释,即类型为 stickyNote 的节点,不会被导入;连接到未导入节点的边会被 丢弃。
  • 起草承载该 chatflow 的平台时,还会从中读取:其顶层 id(当它是 UUID 时);节点保存在 data.credential 中的凭据;其 inputParams 声明为 password 类型的每个输入的值;节点输入中的 FLOWISE_CREDENTIAL_ID,以及这些输入任意深度的配置对象中的 credential 或 FLOWISE_CREDENTIAL_ID;节点 mcpServerConfig 输入中的服务器 配置;Flowise 标记为非凭据但可能承载凭据的每个输入(如 流程持有的凭据值 所列),以及 agentflow 配置中指明其所选模型或工具的成员;节点的 modelName 输入;以及 OpenAI 节点的 Base Path,即其 basepath 输入。 它们起草的内容 说明了每一项的去向。

n8n 导入器读取的内容

  • 工作流的 nodes 及其 connections,位于导出内容的顶层。
  • 对每个节点,读取标识它的 name(n8n 的连接按名称指明所连接的节点,且一个工作流中的节点名称唯一),以及完整写出、带有其包名的 type:例如 @n8n/n8n-nodes-langchain.lmChatOpenAi 或 n8n-nodes-base.httpRequest。没有名称的节点 以其 id 标识。
  • 工作流列出的每个连接都是一条边,从它离开的节点指向它进入的节点, 无论其类型如何:main 连接将数据从一个节点传给下一个节点,而 AI 连接 (ai_languageModel、ai_tool、ai_vectorStore、ai_embedding、ai_memory 等) 则把它离开的节点所代表的模型、工具、存储或记忆交给它进入的节点。无论哪种情况, 连接进入的节点都消费它离开的节点。
  • 节点的 credentials 指明的每个凭据类型,以及 n8n 标记为密码的每个顶层参数, 都被起草为一个凭据槽;节点的其他每个顶层参数都是一个值 字段。将 节点起草为 Component 时不读取任何字段的值。
  • 固定在画布上的便签,即类型为 n8n-nodes-base.stickyNote 的节点,不会被导入;指向 未导入节点的连接会被丢弃。
  • 起草承载该工作流的平台时,还会从中读取:其顶层 id;节点选择的每个 凭据;n8n 标记为密码的每个参数;MCP 客户端节点调用的地址;节点随工作流组装的请求一同发送的请求头和查询参数,如 流程持有的凭据值所列;以及 模型节点指明其模型所用的参数。它们起草的内容说明了每一项的 去向。

它们起草的内容

每个节点只与工作区自身目录中的 Components 进行比较,不与其他任何内容比较,如导入器插槽所述;每个导入器都带有一张简短的表,将其格式中常见的节点类型——聊天模型和嵌入模型、检索、HTTP 请求,以及在 Langflow 上映射到 core/ai-tool/mcp 的 MCP Tools 节点 MCPTools——映射到标准库 Components。Langflow 的表还将其 Language Model 组件 LanguageModelComponent,即其入门流程调用的聊天模型,映射到 core/ai-model/openai,即 Langflow 平台的模型连接所服务的模型:该节点运行在其 provider 字段指定的模型提供方上,默认为 OpenAI,而指定其他提供方的节点永远不会接入该连接,如哪些节点成为组成部分所述。n8n 导入器的表映射 n8n 的聊天模型和嵌入模型、映射到 core/ai-tool/mcp 的 MCP 客户端工具、HTTP 请求工具、SerpApi 工具、Qdrant、PGVector、Chroma、Milvus 和 Weaviate 向量存储,以及 Postgres 和 Redis 聊天记忆。n8n 在工作流内部运行的节点——智能体、链、触发器、工作流在自身进程中保存的记忆、代码工具——属于工作流自身,没有任何行映射它。该表中的一行只有在工作区目录包含其所指的 Component 时才计入匹配。该命令为每个已映射的节点报告一行,说明它选择了什么、匹配层级以及最佳候选的得分;对于未赋予其自身 Component 的节点,报告一行 made no choice for <node id> (<node type>)。引用目录 Component 而非起草的节点没有自己的文件:草稿 Aggregate 会指明该 Component。

草稿的布局由 layout 设置决定。默认值 platform 起草运行该流程的平台,按导出时的原样承载流程,并且只为平台的某个插槽所接受的流程部件赋予其自身的 Component——在标准库的平台上,即模型、MCP 服务器或其他通过 HTTP 访问的工具,以及向量存储。nodes 将每个节点都起草为其自身的 Component。

承载流程的平台

默认情况下,一次导入会写入:

  • aggregate.yaml——一个以流程命名的草稿 Aggregate,如 草稿如何命名 所述。它包含运行该流程的平台的一个实例——对 Langflow 流程为键 langflow 下的 core/ai-agent/langflow,对 Flowise 流程为键 flowise 下的 core/ai-agent/flowise,对 n8n 工作流为键 n8n 下的 core/ai-agent/n8n——引用同名的目录 Component。该实例在 values.flow_definition 中承载流程,并在其标识符值中指明该流程:在 Langflow 上为 flow_id,在 Flowise 上为 chatflow_id,在 n8n 上为 workflow_id。流程的每个部件都是与之并列的独立条目,通过该实例的 uses 连接到平台。
  • release.yaml——同名的草稿 Release,指定该 Aggregate,为平台和每个部分各设一个条目,携带平台的镜像,并以引用方式附加草稿所需的每个密钥,如 草稿留给 Release 的内容 所述。
  • 对它起草而非引用的每个部件,在 components/ 下写入一个文件,写法与逐节点布局写入已起草节点的方式相同。

给定目标时,导入会在它们旁边起草 manifest.yaml,如 目标会添加什么 所述。

每个不是部件的节点都保留在平台承载的流程中,不成为任何 Component。它的决策记录与之比较过的候选,但不作任何选择,其理由为 kept in the flow <platform> carries, with no Component of its own:,后接原因——例如没有映射行指明其类型,且其最接近的候选得分仅为多少。流程保留节点之间的边;草稿不另写任何边。

Flowise 的 Multiple Documents QnA chatflow,导出为 Multiple Documents QnA.json,在不带任何设置、不指定目标的情况下导入,所用目录包含标准库的 Flowise 平台及其模型和检索工具 Components,会被起草为如下 Aggregate(此处省略了流程的大部分内容,以 ... 标出):

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/multiple-documents-qna
version: 0.1.0
description: Draft Aggregate imported from a source in the flowise format.
spec:
components:
flowise:
type: core/ai-agent/flowise
# For the compose target only, uncomment the lines below, which declare owner_password on flowise: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# owner_password:
# type: core/secret-value
# values:
# key: OWNER_PASSWORD
values:
# chatflow_id is derived from the exported flow, which gives no identifier of its own.
chatflow_id: '96da3b80-86d0-5f23-b4e7-2573ea1f76ad'
flow_definition: |
{
"description": "Tool agent that can retrieve answers from multiple sources using relevant Retriever Tools",
...
"embeddings": "{{"{{"}}openAIEmbeddings_0.data.instance}}",
...
}
uses:
model:
chatopenai-0:
target: chatopenai-0
# For the compose target only, uncomment the lines below, which declare credential on chatopenai-0: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# swap to core/ai-model/azure-openai (score 0.4000) by setting type: core/ai-model/azure-openai
chatopenai-0:
type: core/ai-model/openai
values:
model: |-
gpt-3.5-turbo

其聊天模型是唯一连接的部件;其两个嵌入模型留在流程中,因为模型插槽只接受单个连接;其检索工具也留在流程中,因为平台没有接受它们的插槽。导入会逐一报告。

流程的标识符是导出为其给出的标识符——Langflow 流程的顶层 id、Flowise chatflow 的顶层 id(当其为 UUID 时),以及 n8n 工作流的顶层 id——前提是它由 1 到 128 个字母、数字、.、-、_ 或 : 组成,并以字母或数字开头。若导出未给出标识符,或给出的标识符包含其他字符,草稿会写入一个基于名称的 UUID,由格式名称和所承载的流程派生,因此同一流程始终得到同一标识符,并在该值上方添加注释说明它是派生的。从 Flowise 编辑器导出的 chatflow 不带 id,因此会被赋予派生的标识符。

若工作区目录中没有与平台同名的 Component,草稿仍会指明该平台,但不将任何部件连接到它:每个本应成为部件的节点都留在流程中并被报告,且导入会警告目录中没有这样的 Component。

哪些节点成为部件,以及各自连接到何处

当导入器映射表中的某一行或某个 mapping_overrides 条目映射了节点的类型,或其最佳候选至少为中等层级匹配时,该节点即为流程的部件。Langflow MCP Tools 节点无论得分如何都是部件:它指明所调用的 MCP 服务器,而该服务器就是部件。部件会成为其自身的 Component,完全按 reuse_mode 的决定进行引用或起草,并连接到平台的第一个插槽(按平台目录条目声明插槽的顺序),该插槽的标签选择器须由部件的 Component 满足:即其所引用 Component 的标签,或者对于起草的部件,在其最佳候选至少为中等层级匹配时,取该候选的标签。若部件的 Component 不满足任何插槽的选择器,或没有可读取标签的 Component,该部件留在流程中,导入会报告它。

这些规则对此加以限定:

  • 指定其他提供方的 Langflow 模型不获得模型连接。 LanguageModelComponent 或 EmbeddingModel 节点运行在其 provider 字段指定的模型提供方上,若该字段为空,则运行在其 model 字段所选模型的提供方上。平台为兼容 OpenAI 的客户端提供其模型连接,因此指定 OpenAI 以外任何提供方的节点——无论映射行或覆盖将其映射到什么——都永远不会接入 model 插槽:它会接入其 Component 满足的下一个插槽,或者留在流中,其决策不作任何选择,也不为其起草任何 Component,导入会报告该节点并指明它所运行的提供方。未选择提供方、通过全局变量指定提供方,或从另一节点获取模型的节点,与其他任何组成部分一样接入。
  • 只接受单个连接的插槽由一个部件占据。 在每个平台上,model 插槽都只接受一个连接,平台的 Recipes 将其交付为一个 OPENAI_BASE_URL 和一个 OPENAI_API_KEY。若有多个部件被放入其中,则由第一个其 Component 带有 model.aggrega.ai/capability: generative 的部件占据(若都没有,则为第一个部件),其余部件都留在流程中,并在报告中注明占据该连接的部件,以及按其节点的写法流程如何访问它。
  • Langflow 只能通过指明 tools 连接的 MCP Tools 节点访问该连接。 平台将 tools 连接的地址写入其 mcp_server 字段指明该连接的 MCP Tools 节点的服务器配置,因此模板中不带 mcp_server 字段的节点——无论其类型如何,也无论映射行或覆盖将其映射到什么——都永远不会连接到 tools 插槽:它会连接到其 Component 满足的下一个插槽,或留在流程中并被报告。未指明服务器的 MCP Tools 节点不连接到任何插槽,并被报告。服务器配置会自行启动服务器的节点(带有 command,或设置了 Stdio 模式)同样如此,其报告会说明需要移除什么,因为当节点指明的服务器没有任何 tools 连接响应时,平台的构建会中止。
  • MCP 服务器按流程赋予它的名称连接。 同一流程中指明同一服务器的节点,通过同一连接访问同一个只起草一次的部件。若连接别名可以采用服务器名称(字母、数字、连字符和下划线),且该插槽没有其他连接以相同的变量名交付(变量名为别名转大写、其余每个字符写为下划线),则连接别名即为服务器名称。否则,连接采用从部件键派生的别名,草稿所承载流程中该节点的服务器会被重命名为该别名,部件的决策也会说明这一点。

已连接部件的决策会说明它连接到平台的哪个插槽、通过哪个连接,并指明它被跳过的每个插槽及原因。

所承载的流程如何访问每个部件

在格式允许的情况下,平台所承载的流程通过各个已接线部件的连接来访问该部件,草稿会在流程中写入实现这一点所需的内容——变量的名称、被清空的地址,或被清空的、节点原本会发送以替代连接所提供内容的值,而绝不写入值本身。这是接线,而不是移除凭据值:无论 empty_credentials 设置如何,草稿都会写入这些内容,因为保留在那里的值会覆盖连接所提供的内容。

  • Langflow MCP Tools 节点。 平台将其连接提供的地址写入该节点的服务器配置;当连接携带凭据时,还会在该工具公布的请求头下写入保存该凭据的变量名称。草稿将导出内容在该处保存的地址写为空,使流程不保留其副本,并将服务器的地址——该部件的 infra.endpoint——留给 Release。Langflow 会用节点自身的 headers 字段覆盖其服务器配置中的请求头,因此草稿将该字段的整个值写为空并保留其类型——对象写为 {},列表写为 [],文本写为空字符串——因为值被清空但仍保留的请求头依然会被发送,而空对象或空列表不会覆盖任何内容。

  • Langflow 模型或向量存储节点。 平台将模型连接提供为 OPENAI_BASE_URL 和 OPENAI_API_KEY,将向量存储连接提供为以其别名命名的变量,Langflow 通过指定全局变量的字段读取这些变量:对象中带有 load_from_db: true 的字段以变量名称作为其值,Langflow 读取该名称的全局变量,若未存储该全局变量,则读取该名称的环境变量。草稿将以下每个字段写为对应的变量名称并带上 load_from_db: true:

    • OpenAIModel 节点的 openai_api_base 写为 OPENAI_BASE_URL,其 api_key 写为 OPENAI_API_KEY;
    • OpenAIEmbeddings 节点的 openai_api_base 写为 OPENAI_BASE_URL,其 openai_api_key 写为 OPENAI_API_KEY;
    • LanguageModelComponent 节点的 api_key 写为 OPENAI_API_KEY;
    • EmbeddingModel 节点的 api_base 写为 OPENAI_BASE_URL,其 api_key 写为 OPENAI_API_KEY;
    • pgvector 节点的 pg_server_url 写为 AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING,其中 <ALIAS> 是连接的别名转为大写,并将字母和数字以外的每个字符写为下划线。

    LanguageModelComponent 或 EmbeddingModel 节点运行在多个模型提供方之一上——即其 provider 字段指定的提供方,若该字段为空,则为其 model 字段所选模型的提供方——并将其密钥交给该提供方。平台为兼容 OpenAI 的客户端提供模型连接,因此只有当此类节点运行在 OpenAI 上时才会写入这些变量。运行在其他提供方上的节点永远不会接入,如上所述;未选择提供方、通过全局变量指定提供方,或从另一节点获取模型的节点都不会写入任何变量,因此草稿绝不会让其他提供方指向该连接的密钥。当此类节点没有字段给出其 API 地址时——LanguageModelComponent 节点对 OpenAI 不保存地址,而 EmbeddingModel 节点的 api_base 可能缺失,或在无法指定变量时为空——它所运行的 OpenAI 客户端会从环境中读取 OPENAI_BASE_URL,因此该节点同样能访问平台提供的地址。

    OpenAIEmbeddings 节点的客户端会用其 default_headers 覆盖它根据密钥构建的请求头,并将其 default_query 合并到所调用地址的查询之上,因此在草稿接线的此类节点上,这两者的整个值都会被写为空并保留其类型,与 MCP Tools 节点的 headers 相同。

    导出内容中写入时不同时带有这两个成员的字段不会被重新写入——其中的凭据字段按原样承载,或在设置要求时写为空,见下文。当该字段承载部件的地址时——且对于 LanguageModelComponent 或 EmbeddingModel 节点,该字段给出了地址——当此类节点不运行在 OpenAI 上时,或当节点为任何其他类型时,导入会报告该部件通过流程或其组件默认值给出的地址访问。

  • Flowise OpenAI 节点。 Flowise 运行 chatOpenAI 或 openAIEmbeddings 节点所用的 OpenAI 客户端,在节点的 Base Path 为空且未选择凭据时,会从环境中读取 OPENAI_BASE_URL 和 OPENAI_API_KEY,因此草稿将导出内容保存的 Base Path 写为空,并将节点在 data.credential 处选择的凭据也写为空。该客户端会用节点的默认请求头,即其 baseOptions,覆盖它根据密钥构建的请求头,因此草稿将其整个值写为空并保留其类型。任何其他类型的模型节点都会被报告为通过 chatflow 或其自身默认值给出的地址访问。

  • Flowise 工具或向量存储。 chatflow 只能通过同名的 Runtime 变量读取平台为其提供的地址——AGGREGA_TOOL_<ALIAS>_URL 或 AGGREGA_VECTOR_STORE_<ALIAS>_URL——而启动时没有任何东西会创建该变量。草稿不为此写入任何内容,导入会报告让 chatflow 读取它的步骤:在 Flowise 的 Variables 页面创建该 Runtime 变量,并在节点中以 $vars.<name> 读取它。

  • 任意 n8n 节点。 平台将模型连接提供为 OPENAI_BASE_URL 和 OPENAI_API_KEY,将工具或向量存储连接提供为 AGGREGA_TOOL_<ALIAS>_URL 或 AGGREGA_VECTOR_STORE_<ALIAS>_URL,而 n8n 节点通过其所选的已存储凭据给出的地址或其自身参数保存的地址访问模型、存储或服务,工作流只能通过读取 $env 的表达式读取环境变量,除非 Aggregate 将 values.allow_env_access_in_nodes 设为 true,否则平台会拒绝该表达式。草稿将该值保留为默认值 false,因为设置它会让每个工作流以及每个能编辑工作流的用户读取平台环境中的所有变量,包括所提供的凭据。因此草稿不为连接向工作流写入任何内容,每个已接线部件都会被报告为不通过连接访问。MCP 客户端节点通过工作流保存的地址访问其服务器——按导出时的原样,或在 empty_credentials 设置将其写为空时则没有地址,见下文——而服务器自身的地址——该部件的 infra.endpoint——留给 Release。

在承载流程时,每个已接线部件都会附带以下哪种情况成立的报告: part-reads-connection 表示流程通过其连接访问该部件, part-address-in-flow 表示流程不通过其连接访问该部件——而是通过流程保存的地址,或其组件默认值给出的地址。该部件的决策也会说明同样的内容。

草稿未接线到任何 socket 的节点,按其写法仍可能被草稿确实接线的某个连接访问:没有自身地址和密钥的 OpenAI 客户端会从其环境中读取平台为模型连接提供的 OPENAI_BASE_URL 和 OPENAI_API_KEY。出现这种情况时,草稿会像对待已接线节点一样写入该节点,使其保存的任何内容都不会替代连接提供的内容被发送,并以 part-reads-connection 报告它:

  • Langflow OpenAIEmbeddings 节点,其地址字段指定平台提供的变量 OPENAI_BASE_URL,并作为全局变量读取,同时有部件接线到模型 socket:其 default_headers 和 default_query;
  • Flowise chatOpenAI 或 openAIEmbeddings 节点,其 Base Path 为空且未选择凭据,以及 agentflow 节点在其输入中保存的此类模型配置,同时有部件接线到模型 socket:其 baseOptions。

在其他任何节点上,这些值都不属于连线:它们按原样携带,或在设置要求时写为空,如下一节所述。

流程中持有的凭据值

在携带流程之前,导入会在下列位置找出流程中每个可能携带凭据的值,每个值属于以下三类之一:格式标记为凭据的值;MCP 服务器配置的成员(无论格式将其保存在何处);以及格式标记为非凭据但仍可能携带凭据的输入——请求头、查询参数、以命令行形式写出的完整请求、以凭据名称持有凭据的输入。

默认情况下,导入不会将其中任何值写为空:流程按导出时的原样携带,每个持有内容(既不是空字符串,也不是 null)的已定位值都会在 credential-carried 警告中列出,按其节点和字段命名(请求头或查询参数按其名称),绝不按其值或值的任何部分命名,并附上可将其写为空的 empty_credentials 设置值。该设置用于开启移除:marked 将格式标记为凭据的值以及 MCP 服务器配置的每个成员写为空;all 还会将标记为非凭据的输入写为空。每个被写为空的值都以 credential-emptied 报告,按其节点和字段命名,绝不按其值命名;已经为空或为 null 的值保持原样,不予报告。设置不接受的值会使导入停止,不生成任何草稿,而不是被视为 none。

仅由一个变量引用构成、别无他物的已定位值不持有自身的值:变量的裸名称、${NAME}(包括 ${workspaceFolder} 或 ${userHome} 等预定义变量),或 MCP 客户端定义的形式之一 ${env:NAME} 和 ${input:id}。无论设置如何,无论流程采用哪种格式,它都按原样携带,不在任何警告中列出,与 MCP 导入器的写法一致。格式以文本形式保存的值中仅为一个引用的成员也是如此,例如以 JSON 文本写出的 Flowise mcpServerConfig,或在 Flowise 和 n8n 上以文本中的 JSON 对象保存的请求头和查询参数:写为空时,文本会按原样保留该成员。

在运算符之后带有文本的引用持有该文本,而该文本可能是密钥,无论运算符前是否有冒号:默认值 ${NAME:-value} 或 ${NAME-value};替代值 ${NAME:+value} 或 ${NAME+value};消息 ${NAME:?message} 或 ${NAME?message};赋值 ${NAME:=value} 或 ${NAME=value}。它与其他值一样被定位——默认携带并在 credential-carried 警告中列出,在设置要求其类别时写为空——${…} 中的其他任何文本(例如 ${config:name})以及引用旁的文本(例如 --key=${NAME})也是如此。

草稿为使节点到达其连接而写入的内容——写为空的地址、变量名称、写为空的所选凭据或默认请求头,如携带的流程如何到达每个部件所述——属于连线:无论设置如何都会写入,按节点到达其连接的方式报告,绝不作为凭据值报告。下列所有位置之外的内容由作者审查,如本节末尾所述。

格式标记为凭据的值——在 marked 和 all 下写为空:

  • Langflow——每个标记为 password: true 的模板字段的值,包括持有全局变量名称的字段,除非草稿已用平台提供的变量名称写入该字段,如上所述。
  • Flowise——节点在 data.credential 处保存的、由其凭据参数选择的凭据;其 inputParams 声明为 password 类型的每个输入的值;以及节点输入中的 FLOWISE_CREDENTIAL_ID,和其中任意深度的配置对象内的 credential 或 FLOWISE_CREDENTIAL_ID,例如 agentflow 保存模型或工具配置的方式。
  • n8n——节点所选每个已存储凭据的 id,位于 credentials.<type>.id。n8n 导出以引用形式保存凭据,绝不保存其值,且引用的 name 不被定位:n8n 在另一个实例上导入工作流时,会按类型和名称解析其未持有 id 的凭据。较旧导出仅按名称选择的凭据只是指名一个凭据而不持有凭据,因此不被定位。此外还有 n8n 在其基础节点定义中标记为密码的每个参数的值——例如 Crypto 节点的 secret,或创建用户的节点的 password——无论它位于节点参数中的何处;用作代理工具的节点按其本身的节点类型读取。

MCP 服务器的配置——在 marked 和 all 下写为空:

  • Langflow MCP Tools 节点的 mcp_server 配置,以及 Flowise 节点以 JSON 文本或对象形式写出的 mcpServerConfig:每个请求头值(无论请求头是对象、键值行还是整体合并的对象,任何其他类型的项整体定位);每个环境变量值;服务器地址;命令;以及每个参数。两种格式都不会将地址、命令或参数标记为凭据,而它们都可能携带密钥——地址可在其用户部分、路径或查询中携带——因此在两种格式上这三者也都会被定位。写为空时,命令和每个参数保留其成员,因此自行启动服务器的配置仍被视为此类配置。当 Langflow MCP Tools 节点连线到工具连接时,其地址属于连线,如上所述,绝不作为凭据值报告。无法解析为 JSON 对象的 Flowise 文本配置会被整体定位,因为其中的内容无法单独定位。
  • 不带 mcp_server 字段的 Langflow MCP Tools 节点改为在自身字段中保存其服务器——地址在 sse_url,请求头在 headers_input,环境在 env,完整命令行(包括其参数)在 command——Langflow 同样未将其中任何一项标记为凭据,因此每个请求头值、env 的每个条目、地址和命令行都会被定位,写为空时保留其字段和条目。当 env 是列表时,每个条目按其位置报告,因为变量名称及其值共享同一段文本。此类节点不指名 MCP 服务器,因此绝不会连线到工具连接。
  • Langflow MCP Tools 节点自身的 headers 字段(Langflow 会将其覆盖在配置的请求头之上发送给服务器),在草稿未连线的节点上:其整个值,与在已连线节点上一样写为空并保留其类型,并以 headers 报告一次。
  • Langflow 的 MCP Tools (SSE) 和 MCP Tools (stdio) 组件(Langflow 已将其标记为弃用)各自在一个字段中保存其服务器——MCPSse 节点的地址在 url,MCPStdio 节点的完整命令行(包括其参数)在 command——均整体定位。两者都不指名 MCP 服务器,因此都不会连线到工具连接。
  • n8n MCP 客户端节点——代理调用的 MCP Client Tool、MCP Client 节点,或 n8n 注册表所列服务器的客户端——在其 endpointUrl 参数(第一版中为 sseEndpoint)中保存服务器地址,请求头则仅以其所选凭据的形式保存;无论是否连线,地址都会被整体定位。

格式标记为非凭据的输入——仅在 all 下写为空:

  • 请求头 — 在 Langflow 上,是 APIRequest、URLComponent、 CloudflareWorkersAIEmbeddings 或 ConfluentKafkaProducer 节点的 headers,以及 DoclingRemote 节点的 api_headers;在 Flowise 上,是 httpAgentflow、getApiChain、 postApiChain、openApiChain、apiLoader、openAPIToolkit 或 searXNG 节点的 headers, Requests 工具的 requestsGetHeaders、requestsPostHeaders、requestsPutHeaders 和 requestsDeleteHeaders, 以及 azureChatOpenAI、azureOpenAIEmbeddings、chatCerebras、chatOpenAICustom、 openAIEmbeddingsCustom、chatOpenRouter、chatSambanova 或 openAI 节点的 baseOptions(模型客户端发送的默认请求头);在 n8n 上,是 n8n-nodes-base.httpRequest 节点的 headerParameters、jsonHeaders、headerParametersUi 和 headerParametersJson(其当前版本保留前两个,早期版本保留后两个), 以及用作智能体工具的同一节点的这些字段,@n8n/n8n-nodes-langchain.toolHttpRequest 节点的 parametersHeaders 和 jsonHeaders,以及 n8n-nodes-base.graphql 节点的 headerParametersUi。请求头的名称不携带机密,因此无论请求头采用何种形式,都定位每个请求头的值并保留其名称:名称到值的对象、由键和值组成的行(在 n8n 上是由 name 和 value 组成的行),或 Langflow 整体合并到请求头中的对象。每个请求头按其名称报告。列表中不是请求头行的项被整体定位,并按其位置报告。以文本形式写入的请求头被整体定位,但在 Flowise 和 n8n 上文本以 JSON 对象保存请求头时除外:此时置空会原地重写文本,将每个值置空,并连同其包含的请求头名称报告一次。以 = 开头的 n8n 文本是 n8n 在工作流运行时求值的表达式,被整体定位。 置空时,所有值都会被置空,包括 User-Agent 等不含机密的请求头的值,因此导入的请求在其作者恢复这些值之前,发送时这些值均为空。
  • 查询参数 — 在 Langflow 上,是 APIRequest 或 GoogleSerperAPI 节点的 query_params, 以及 SerpAPI、Serp、SearchAPI 或 SearchComponent 节点的 search_params;在 Flowise 上,是 httpAgentflow 节点的 queryParams 和 searchApi 加载器的 customParameters;在 n8n 上,是 n8n-nodes-base.httpRequest 节点(无论是否用作工具)的 queryParameters、jsonQuery、queryParametersUi 和 queryParametersJson, @n8n/n8n-nodes-langchain.toolHttpRequest 节点的 parametersQuery 和 jsonQuery,以及 n8n-nodes-base.facebookGraphApi 节点在其 options 中保留的 queryParameters 和 queryParametersJson。每一项都作为请求的查询发送,而查询参数可能携带密钥(某些搜索 API 在查询中以 api_key 接收密钥),因此每一项都按请求头的方式定位:无论参数采用何种形式,都定位每个值并保留其名称,并按名称逐一报告;以文本形式写入的参数被整体定位,但在 Flowise 和 n8n 上文本以 JSON 对象保存参数时除外,此时置空会原地重写文本,并连同其包含的名称报告一次。置空时,所有值都会被置空,包括不含机密的参数的值,因此导入的请求在其作者恢复这些值之前,发送时这些值均为空(对于 Flowise HTTP 节点,由于它不发送值为空的参数,则发送时不带这些参数)。
  • 没有连接到达的 OpenAI 节点上的默认请求头和默认查询 — Langflow OpenAIEmbeddings 节点的 default_headers 和 default_query,以及 Flowise chatOpenAI 或 openAIEmbeddings 节点的 baseOptions,无论节点位于何处(包括智能体流对其所选模型的配置),前提是草稿既不连接该节点,也找不到按其写法到达该节点的连接;若存在这样的连接,它们就属于连接配置,如上所述。每一项都被整体定位,置空时保留其类型(对象为 {},列表为 [],文本为空字符串),并报告一次。
  • 以命令行形式写入的整个请求 — Langflow APIRequest 节点的 curl_input 和 Webhook 节点的 curl,被整体定位,包括 Webhook 的默认值。两者在流运行时都不会被读取:前者仅在编辑器中填充节点的字段,后者展示一个示例。
  • 以凭据名称保存凭据的输入 — Langflow OlivyaComponent 节点的 api_key、每个 Composio 组件的 verification_token,以及 mem0_chat_memory 节点的 mem0_config(置空时其整个值保留类型);以及 Flowise startAgentflow 节点的 webhookSecret 和 callbackSecret,和 teradataMCP 节点的 bearerToken。每一项都被整体定位。名称仅类似凭据的输入(存储在别处的密钥的名称、用户名,或组件声明为非机密的选项)不会被定位。

除了该设置置空的值、草稿为使流到达其各部分而写入的内容、按 Langflow 编辑器的写法写入的 Langflow 边的句柄,以及下文中改写为换行符的回车符之外,流按导出时的原样携带:若没有上述任何一项,则逐字节原样携带。

草稿中的连接不携带任何凭据值:草拟的 Release 以引用方式附加每个连接所提供的凭据,如 草稿留给 Release 的内容 所述。

该设置保留原样的每个值都会进入草稿,由作者在 credential-carried 警告的指引下审查。针对字段的规则也不会覆盖流的其余部分,因此作者在共享草稿前也要审查这些内容:组件自身的代码(流会携带它,自定义组件可能在其中保存密钥);编辑器在组件声明之外为节点添加的输入;请求发送时的请求体,例如 APIRequest 或 httpAgentflow 节点的请求体,其中可能携带令牌;节点以单独对象传给其模型客户端或加载器的参数,例如 Langflow EmbeddingModel 节点的 model_kwargs 或 Flowise replicate 节点的 additionalInputs,其中可能以任意名称携带密钥;MCP 服务器地址以外的地址,其用户部分或查询中可能携带密钥;n8n Code 节点的代码,以及发送请求但未在上文列出的节点的请求头或查询;以及提示词或消息等自由文本。

草稿留给 Release 的内容

草拟的 Release 在平台的条目和每个部分的条目上携带流无法提供的内容:

  • 平台的镜像,即 infra.image:由导入器自行选择的镜像,版本为已知目录中该平台的 Recipes 可运行的版本——langflowai/langflow:1.6.0、flowiseai/flowise:3.1.3 和 n8nio/n8n:1.110.1——并在其上方附有说明此事的注释。导入从不为了跟随源而提高或降低该版本;当导出声明了不同的平台版本时(如 Langflow 流的 last_tested_version),注释会指出它。
  • 平台发布所用的端口,即 infra.published_port,仅在使用 --target compose 时写入:Langflow 为 7860,Flowise 为 3000,n8n 为 5678,即各平台提供服务的端口,其 Compose Recipe 将其发布在主机的回环地址 127.0.0.1 上。其上方的注释说明该端口只能从本机访问,本机上运行的任何进程都可以访问,并且删除该行可使服务保持在内部。同一次导入中的第二个流会使用之前的流都未占用的下一个端口。使用任何其他目标或不指定目标时,不写入该端口。
  • 平台自身的密钥以及每个模型连接的凭据,以引用方式附加,从不以值的形式附加:在 Langflow 上,是 admin_password 槽位,在 values.require_authentication 保持为 true 时读取;在 Flowise 上,是 owner_password 槽位,在设置了 values.flow_definition 时为必需;以及当某个部分连接到平台的 model 套接字时,该连接上的 credential。n8n 平台不接受自身的密钥。每项如何附加取决于目标,如 各目标的密钥 所述。
  • 任何来源都不包含的每个值,写为空字符串,上方附有说明其含义的注释:在 Flowise 上,是 infra.owner_email,即所有者账户的电子邮件,在设置了 values.flow_definition 时为必需;以及连接到平台的每个 MCP 服务器的地址,即其部分的 infra.endpoint。每一项都是导入欠缺的值,按 导入答案文件 所述方式作答。

连接到工具或向量存储的连接所提供的凭据不会被起草:当工具没有发布用于发送该凭据的请求头时,此类连接的凭据会使构建停止,因此平台条目上方的注释会指出它,供你在工具接受凭据的位置附加。

各目标的 secret

在 --target helm 上,每个 secret 都是一个 core/referenced-secret,其 origin 是命名空间中已有的某个 Kubernetes Secret 的名称,该 Secret 以数据键 value 保存值。这个名称不由任何源提供,因此它被写为空,上方有一条注释说明它保存什么,并且属于导入待补的值;起草的 Manifest 将 core/referenced-secret 映射到 helm/k8s-existing-secret。

在其他所有目标上,以及不指定目标时,每个 secret 都是一个 core/secret-value,其 origin 是对某个变量的引用——${LANGFLOW_ADMIN_PASSWORD}、${FLOWISE_OWNER_PASSWORD},以及用于模型连接凭据的 ${OPENAI_API_KEY}——由替换变量引用的目标从环境中读取,就像 Docker Compose 在启动栈时所做的那样,因此没有任何文件携带该值,也没有为它待补的值。上面的 Flowise chatflow 在不指定目标导入时,会起草为以下 Release:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/multiple-documents-qna
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the flowise format.
spec:
aggregate: imported/multiple-documents-qna
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
flowise:
infra:
# The image running core/ai-agent/flowise, at the version this importer drafts, which the catalog's Recipes for it are known to run; the import does not raise or lower it to follow the source.
image: "flowiseai/flowise:3.1.3"
# Left for the Release, since the source cannot supply it: infra.owner_email, the email address of the platform's owner account, required while values.flow_definition is set
owner_email: ""
features:
owner_password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the owner account's password, required while values.flow_definition is set, read from the variable FLOWISE_OWNER_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${FLOWISE_OWNER_PASSWORD}"
uses:
model:
chatopenai-0:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential flowise presents to chatopenai-0 on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
chatopenai-0: {}

不指定目标时,导入待补两个值:spec.manifest 和 infra.owner_email;使用 --target compose 时,只待补所有者的电子邮件;使用 --target helm 时,待补所有者的电子邮件以及两个 Kubernetes Secret 的名称。

在 compose 目标上,仅由 Release 附加的 secret 以同一个键 value 到达,因此所有者或管理员的密码与连接的凭据都会以该键到达。所以在平台建立连接的地方,Aggregate 会为每一项声明独立的键:在 Flowise 上是键为 OWNER_PASSWORD 的 owner_password,在 Langflow 上是键为 LANGFLOW_SUPERUSER_PASSWORD 的 admin_password,在三个平台上都有键为 OPENAI_API_KEY 的模型连接 credential,每一项上方都有说明原因的注释。使用 --target compose 时,这些行以生效状态写出;不指定目标时,它们以注释掉的状态写出,如上例所示,若你为 compose 构建,可取消注释;使用其他任何目标时,不写出这些行。Release 附加每个槽位的来源,指定相同的类型或不指定类型。

当 attach_egress_allowlist 设置为 true 时,平台实例还会在 features 下以 egress-allowlist 的名称声明标准库的 core/egress-allowlist Feature,使平台只连接到其连接所到达的组件、它自己的 pod 和集群的 DNS——这是作为声明调用的 uses 边在出站方向上的对应物。Aggregate 只声明该附加项的类型,因为 Aggregate 的附加项不携带 infra,而起草的 Release 也不写出其中任何内容:平台条目上方的注释在 features.egress-allowlist.infra 下列出 control_plane_present,运维人员将其设为 true 以确认集群的网络插件会执行网络策略,缺少该确认构建会中止;admitted_destinations,这是一个列表,为目标不在集群中运行的每个连接(例如托管模型)包含一个指出目标和地址范围的条目,缺少它构建会中止并指出该连接;以及为容纳平台的边界指出的 aggrega.ai/namespace,因为策略放置在其工作负载所在的命名空间中,而当它们未被输出到任何命名空间时构建会中止。这些键都不会写为空,因此都不属于导入待补的值。每个已连接部件的决策都说明该附加项允许其连接,导入以 feature-attached 报告该附加项。Compose 没有网络策略,因此对这种草稿进行 compose 构建会中止并指出该附加项;在平台建立连接的地方,上述 compose 行写在实例的 features 块内,不会出现第二个 features 键。

部件提供的模型

草稿引用的部件,若其 Component 声明了名为 model 的值(标准库的每个模型 Component 都会声明并要求它),则会以其节点所选模型的名称写入,即 values.model:

  • Langflow — OpenAIModel 或 AnthropicModel 节点的 model_name;OpenAIEmbeddings 节点的 model;以及 LanguageModelComponent 或 EmbeddingModel 节点在设置了 model_name 覆盖时的该值,否则为其 model 字段所选的模型。
  • Flowise — chatOpenAI、chatAnthropic 或 openAIEmbeddings 节点的 modelName。
  • n8n — 导入器映射表中的聊天、补全或嵌入节点的 model 参数,或 Google Gemini 和 Vertex 节点上的 modelName,写为名称,或写为 n8n 较新节点存放它的选择器的值。n8n 导出时会省略设为默认值的参数,因此保留默认模型的节点在导出中不指定任何模型。

Release 无法写入值。因此,当节点没有指定草稿可写入的模型时——它未选择模型、通过全局变量或仅在流运行时读取的表达式指定模型、从与之相连的另一个节点获取模型,或者其类型的模型字段导入器不读取——部件内的注释会把 values.model 留给作者,导入以 model-not-named 报告。草稿起草的部件不写入任何值。

流如何写入草稿

流被写为一个 YAML 字面量块,其截断方式保留末尾的换行,因此 values.flow_definition 读回时即为流自身的文本。Aggregate 的文本会作为模板读取,因此流中的每个 {{——Flowise chatflow 会为两个节点之间的每个连接写入 {{<node id>.data.instance}}——都写为 {{"{{"}},插值会将其还原为两个花括号,如Text that carries its own double braces所述。模型名称也以同样方式写入。

字面量块无法按原样携带所有字符:

  • 回车符——无论是 CR LF 对中的,还是单独出现的——都写为一个换行符。JSON 文档只在其词法单元之间包含回车符,而那里的任何空白读起来都相同,因此平台读取的是同一个流。导入以 carriage-returns-rewritten 报告其数量。
  • 字面量块无法携带的任何其他字符都会使流无法被携带:换行类字符——U+0085、U+2028 或 U+2029;制表符和换行符以外的控制字符——U+0000 至 U+001F、U+007F,以及 U+0080 至 U+009F;非字符 U+FFFE 和 U+FFFF;以及不属于 UTF-8 序列的字节。此时 values.flow_definition 保持未设置,并附有说明此情况的注释,其余内容照常起草,导入会针对每种字符报告 definition-not-carried,并给出流中该字符的数量以及第一个出现位置的行号和列号。

当草稿置空或重新写入的某个值并不位于导出字节中其解析树所对应的位置时,流同样不会被携带,导入会报告 definition-not-carried 并指出该值的位置。此时,在草稿能够携带的情况下,流的标识符沿用其自身的标识符,否则使用从流中各节点标识符派生出的标识符。

逐节点起草

使用 layout: nodes 时,导入会将流的每个节点起草为一个独立的 Component,并写入:

  • aggregate.yaml — 一个以流程命名的草稿 Aggregate,如 草稿如何命名 所述,它组合流中的节点:每个节点一个条目,流的每条边作为其所馈入节点的一个 uses 连接,其插槽和别名都以馈入它的节点的键命名,因此由多个节点馈入的节点会为每个连接赋予各自的别名。
  • 为其起草的每个节点在 components/ 下生成一个文件——一个名为 <target_namespace>/<category>/<name> 的草稿 Component,名称取自节点的类型,版本为 0.1.0,其值字段作为封闭 values 对象的字符串字段,其凭据字段作为必需的凭据槽位,交付方式由 Recipe 决定。
  • release.yaml——同名的 Release 草稿,指定该 Aggregate,每个节点各有一个条目。

流本身不会被携带,也不会读取任何字段的值。

携带导出的流程本身

默认草稿会携带该流程:平台的实例将导出内容作为 values.flow_definition 接收,其写法如流程如何写入草稿所述。手动将流程写入 Aggregate 的作者——无论是写入按节点布局的草稿,还是写入自己的 Aggregate——也以同样方式书写。按原样运行流程的 Component 将导出内容作为一个值接收——在标准库的 core/ai-agent/langflow 和 core/ai-agent/flowise 上为 flow_definition——而 Aggregate 的文本会作为模板读取,因此导出内容中的双花括号会被当作模板动作读取:Flowise chatflow 会为两个节点之间的每个连接写入 {{<node id>.data.instance}}, Flowise 提示词以 {{question}} 命名变量,而 Langflow 导出内容携带其组件的源代码,其中也可能出现花括号。 请在块标量中将导出内容里的每个 {{ 写为 {{"{{"}},插值会在该 Component 的 Recipes 读取之前还原导出内容的文本; 自带双花括号的文本 说明了原因。导出内容中包含的凭据值应放在 Release 附加的密钥中,而不是放在 Aggregate 中:将其写为空值,就像草稿在 empty_credentials 设置要求时所做的那样。

# Aggregate fragment — a Flowise chatflow carried as exported
spec:
components:
chat:
type: core/ai-agent/flowise
values:
chatflow_id: 3f2b8c1e-7a4d-4e9b-8c2f-1a6d5e9b0c47
flow_definition: |
{
"nodes": [
{
"id": "llmChain_0",
"data": {
"name": "llmChain",
"inputs": {
"model": "{{"{{"}}chatOpenAI_0.data.instance}}",
"prompt": "{{"{{"}}promptTemplate_0.data.instance}}"
}
}
}
],
"edges": []
}

MCP 导入器

importer/mcp 读取 MCP 客户端配置中列出的 MCP 服务器,或 MCP 注册表服务器描述所描述的那一个服务器,并将每个服务器起草为标准库 MCP 工具 core/ai-tool/mcp 的一个实例。每个服务器都是同一种实例,因此该导入器不权衡任何候选项,也不报告任何映射决策。

读取的内容

  • 客户端的配置。 Claude Code 的 .mcp.json、Claude Desktop 的 claude_desktop_config.json 和 Cursor 的 .cursor/mcp.json 在 mcpServers 下按名称列出其服务器;Visual Studio Code 的 .vscode/mcp.json 在 servers 下列出它们,同时在两者下列出 服务器的文件先按 mcpServers 读取。type 为 stdio 的服务器,或未指定 type 但带有 command 的服务器,通过命令行启动——即其 command 和 args—— 并以其 env 作为环境。type 为 http、streamable-http 或 sse 的服务器,或 未指定 type 和 command 但带有 url 的服务器,通过其 url 访问,并向其发送 headers。
  • 注册表服务器描述。 即 MCP 注册表发布的 server.json:其 name,以及 其第一个包,若未列出任何包,则为其第一个远程端点。npm 或 PyPI 包通过以下各项组成的命令行启动:其启动器——即其 runtimeHint,或 npm 使用 npx、PyPI 使用 uvx——其 runtimeArguments、带版本的包(npm 写作 <identifier>@<version>,PyPI 写作 <identifier>==<version>),以及其 packageArguments,并以其 environmentVariables 作为环境。位置参数取其 value 或其 default; 命名参数在具有两者之一时写作 <name>=<value>,两者皆无时写作其 name。OCI 包从其 identifier 指定的镜像运行。远程端点通过其 url 访问,并发送其 headers。描述中列出的其他包和远程端点都在注释中列出名称,因为一个实例只运行其中之一。

服务器的其他成员——cwd、envFile、Cursor 的 auth,或其类型不读取的成员,例如通过命令行启动的服务器的 url——不会写入任何位置,而是在 Release 中该服务器条目上方的注释中列出名称,因为 core/ai-tool/mcp 没有任何基础设施键接收它。配置的 inputs 描述 Visual Studio Code 提示输入的内容,不包含任何值,因此不会被读取。服务器、其环境和其请求头保持源中书写的顺序,但按带注释的 JSON 读取的配置除外,它保持其解析树书写的顺序:按名称排序(参见包含注释的配置)。

读取目录时,会读取其中包含的客户端配置——任意深度下文件名为上述四者之一的每个文件——按其路径顺序读取,并将每个文件的每个服务器起草到同一个 Aggregate 中。

服务器转换的结果

aggregate.yaml 是一个草稿 Aggregate,按草稿如何命名所述以源命名,每个服务器对应一个 core/ai-tool/mcp 实例。实例以其服务器名称为键,转为小写,每段连续的非字母和数字字符写作一个连字符,若较早的服务器已占用该键,则添加数字后缀。若键与服务器书写的名称不同,或导入读取了多个文件,实例上方的注释会列出该服务器及其来源文件。不会起草使用这些实例的 agent。

在它旁边,release.yaml 是一个同名的草稿 Release,其 spec.aggregate 指向该 Aggregate,并为每个实例携带源中声明的运维输入:

  • 对于通过命令行启动的服务器,为 infra.stdio_command,即其命令及之后的每个参数,各占一项;以及 infra.stdio_runtime,即启动器的生态系统:命令为 npx、npm 或 node 时为 npm,为 uvx、uv、python 或 python3 时为 pypi;对于注册表包,则为其注册表 npm 或 pypi;
  • 对于通过地址访问的服务器,为 infra.endpoint:去掉用户部分、查询和片段的地址,因为该 Component 接收的地址不包含任何携带密钥的部分;省略的每个部分都写在条目上方的注释中,位于地址旁边,如服务器持有的凭据值所述;
  • 对于 OCI 包,为 infra.image;
  • 在任何目标上,都不为任何服务器写出 infra.published_port:草稿从不在主机上发布服务器;
  • 对于服务器的环境,写出 server_env 槽位,按导入的目标以引用方式附加。在 --target helm 上,它是一个 core/referenced-secret,指定命名空间中已有的某个 Kubernetes Secret,该 Secret 为每个变量保存一个数据键,每个键都以其保存的变量命名;Secret 的名称写为空,上方有一条列出这些数据键的注释,并且属于导入待补的值。在其他所有目标上,以及不指定目标时,它是一个 core/referenced-secret-set,每个变量在 infra.entries 下各有一个条目,以变量名为键,其值按源中所写,因此像 ${GITHUB_TOKEN} 这样的变量引用仍然是引用,由替换变量引用的目标从环境中读取。

源中未声明的内容写为空,上方有一条说明其为何物的注释:若命令的启动器不由任何一个桥接镜像提供,则 infra.stdio_runtime 留空,并属于导入待补的值;注册表描述留给用户填写的参数写作空项,源中未写值的变量写作值为空的条目,每一项都在条目上方的注释中列出。

与每个起草的 Release 一样,它将 metadata.environment 写为 development,上方有一条注释说明这是一个待修改的起草默认值;不指定目标时,它将 spec.manifest 写为空字符串,属于导入待补的值。指定目标时,导入器会自己起草 Manifest,因为目录通过多个 Recipes 实现 core/ai-tool/mcp,而只有导入器知道每个服务器如何运行:它按键在 mappings.components.name 下将每个服务器映射到目标上对应该服务器运行方式的实现——命令行对应 mcp-stdio-bridge,地址对应 mcp-remote,镜像对应 mcp,例如 helm/mcp-stdio-bridge 或 compose/mcp-remote——并将环境所附加的 secret 类型映射到其实现,在 helm 上为 helm/k8s-existing-secret,在 compose 上为 compose/dotenv-secret-set。导入会补全该 Manifest 并在 Release 中指定它,如目标带来的内容所述。

一个 Claude Code .mcp.json,列出一个通过 HTTP 访问的服务器和一个通过 npx 启动的服务器:

{
"mcpServers": {
"api-server": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${API_KEY}" }
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
}
}
}

起草结果为:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/mcp
version: 0.1.0
description: Draft Aggregate imported from a source in the mcp format.
spec:
components:
api-server:
type: core/ai-tool/mcp
github:
type: core/ai-tool/mcp
release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/mcp
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the mcp format.
spec:
aggregate: imported/mcp
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool:
# - Authorization: "Bearer ${API_KEY}"
api-server:
infra:
endpoint: "https://api.example.com/mcp"
github:
infra:
stdio_command:
- "npx"
- "-y"
- "@modelcontextprotocol/server-github"
stdio_runtime: npm
features:
server_env:
type: core/referenced-secret-set
infra:
# Attached by reference wherever the source names a variable: the environment github is started with, one entry per variable, each written as the source writes it, so a variable reference stays one, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, and an empty value is one still owed.
entries:
- key: "GITHUB_PERSONAL_ACCESS_TOKEN"
value: "${GITHUB_TOKEN}"

使用 --target helm 导入时,同一配置的 Release 将环境作为其指定的 Secret 附加,导入器起草的 Manifest 按键映射每个服务器:

# release.yaml, the github entry's environment
features:
server_env:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN.
origin: ""
manifest.yaml
apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/mcp
version: 0.1.0
spec:
mappings:
components:
type: {}
name:
api-server: helm/mcp-remote
github: helm/mcp-stdio-bridge
features:
type:
core/referenced-secret: helm/k8s-existing-secret

服务器持有的凭据值

Release 写入的服务器配置中的每个值——每个 header 的值、其命令行的每一项、其地址、infra.endpoint 省去的地址的每个部分以及每个环境变量值——都可能携带密钥,而没有任何客户端将其标记为凭据,因此导入会把每个值定位为 MCP 服务器配置的成员;标记为 isSecret 的注册表输入则被定位为其格式标记为凭据的值。注册表输入——环境变量或远程端点的 header——读取为其 value,若未写出则读取为其 default。默认情况下,每个值按原样携带到 Release 中,并在 credential-carried 警告中按其服务器和位置命名——headers.<header>、infra.stdio_command.<position>、infra.endpoint 或 server_env.<variable>,地址的某个部分则按其所在的 url 和该部分的名称命名,例如“url of node remote-search is carried with its query as written(节点 remote-search 的 url 连同其查询按原样携带)”——从不按其值命名。当 empty_credentials 设置为 marked 或 all 时,每个值都写为空并以 credential-emptied 报告:命令行的一项写为空项,环境变量值写为空值,每一项都在条目上方的注释中列出;地址写为空的 infra.endpoint,属于导入待补的值;header 的值或地址的某个部分从注释中省去,注释只指出该 header 或该部分。客户端的 infra.stdio_runtime 是从 Release 所写的命令中读出的,因此写为空的命令也会使其为空,并属于导入待补的值。在 --target helm 上,Release 完全不写环境变量值:它们保存在 server_env 槽位所指定的 Secret 中。

仅由一个变量引用构成的值——裸名称 ${NAME}(包括 ${workspaceFolder} 等预定义变量)、${env:NAME} 或 ${input:id}——本身不持有值:无论设置如何,它都按原文写出,并且不在任何警告中被指出,与流中的引用一样。值为此类引用的环境变量会作为条目的值写出,引用仍然是引用;值为此类引用的 header 或地址部分则与其读取的引用一同列出。在运算符之后带有文本的引用——默认值、替代值、消息或赋值,例如 ${NAME:-value} 或 ${NAME-value},无论有无冒号——持有该文本,引用旁边的文本也是如此;它们都像其他值一样被定位。

core/ai-tool/mcp 的任何基础设施键都不接受 header 的值:远程服务器的凭据由每个使用方在其与该工具的连接上持有,而导入不起草任何使用方。因此,服务器条目上方的注释会列出源发送给它的每个 header,并附上按原样写出的值——一个读回时与源文本完全一致的双引号字符串——供你移到出示该凭据的使用方的连接上。源未写出值的 header,例如既无值也无默认值的注册表 header 输入,列为没有值。OCI 包指定的镜像按原样写出,不属于该设置所作用的值。

infra.endpoint 接受不含任何携带密钥部分的地址,因此源写出而它省去的地址部分——@ 之前的用户部分、? 之后的查询以及 # 之后的片段(第一个 # 之后的全部内容均为片段)——列在同一注释中,每个部分都附有其名称并按原样写出,不带分隔它的 @、? 或 #。从地址读取密钥的使用方会在其自身与该工具的连接上提供完整地址。在没有设置的情况下,位于 https://user:pw@api.example.com/mcp?key=k 的服务器起草为:

# The address's user part and query are not written in infra.endpoint, which holds the address without any part that carries a key; a consumer reading its key from the address supplies the whole address on its own connection to the tool:
# - user part: "user:pw"
# - query: "key=k"
api:
infra:
endpoint: "https://api.example.com/mcp"

而当 empty_credentials 为 marked 时,infra.endpoint 留给 Release 提供,注释列出 user part 和 query,各自的值均被省去。

包含注释的配置

Visual Studio Code 将 .vscode/mcp.json 作为带注释的 JSON 读取,MCP 导入器也是如此:它针对该文件的签名通过服务于 parse:jsonc 的解析器读取文件,因此包含 // 和 /* */ 注释以及尾随逗号的配置无需指定格式即可被识别,并且导入器通过该解析器读取每个在 servers 下列出服务器的源。此类配置的起草结果与去掉注释和尾随逗号的同一配置完全相同。该解析器按名称顺序写出对象的成员,因此此类配置的服务器、其环境和其 header 均按名称顺序起草,无论是否包含注释;命令行保持其顺序。其他客户端和注册表将其文件作为 JSON 读取,导入器也是如此:包含注释的 .mcp.json、claude_desktop_config.json、.cursor/mcp.json 或 server.json 不会被任何签名识别,若指定 --format mcp 导入,则会以 parse-failed 停止并给出解析器的原因。以 /* 开始但从未闭合的注释按原样保留,解析器会拒绝该文件。

它读取的设置

MCP 导入器读取 target_namespace 和 empty_credentials(如设置所述),不读取其他任何设置。

Compose 导入器

importer/compose 读取 Compose 文件声明的服务和模型。它将每个服务起草为其镜像所匹配的目录 Component 的实例,或者起草为标准库通用服务器 core/compute/server 的实例并运行其镜像;将每个模型在你的目录包含标准库的 Docker Model Runner 运行时 core/ai-model/docker-model-runner 时起草为它的实例,不包含时起草为一个独立的模型 Component;并在它们旁边起草一个 Release,承载每个服务为其运行所声明的内容。

读取的内容

  • 文件。 单独导入的文件只读取它本身。目录按 Compose 读取目录的方式读取: 在每个包含 Compose 文件的目录中,按目录路径的顺序,compose.yaml、compose.yml、docker-compose.yml 和 docker-compose.yaml 中第一个存在的是 Compose 文件, 而 compose.override.yml、compose.override.yaml、 docker-compose.override.yml 和 docker-compose.override.yaml 中第一个存在的会合并到它之上。这些文件中的其他文件 不会被读取。包含覆盖文件但没有 Compose 文件的目录,只单独读取其第一个 覆盖文件。起草的 Aggregate 开头的注释按合并顺序列出读取的文件, 以及未读取的文件。每个目录的每个服务和模型都起草到 同一个 Aggregate 中。
  • 合并。 覆盖文件按 Compose 合并的方式合并:image 被替换;ports 按地址、发布端口、容器端口和协议 合并,volumes 按其在容器中的路径合并,environment 按变量名合并,后出现的条目取代先出现的条目, 新条目追加在后;expose 被追加;depends_on 和服务的 models 被合并,条目的 endpoint_var 和 model_var 各自取代较早文件中声明的值。对于 模型,model 和 context_size 被替换,runtime_flags 被追加。Compose 的 !reset 和 !override 标签不会被遵循:带有这些标签的值按 YAML 解析器读取的结果合并。
  • 服务。 它的 image,以及它是否在 build 下构建镜像;它的 ports、expose、 volumes 和 environment——一个映射,或一个由 NAME=value 项组成的列表,没有值的名称 从 Compose 运行时所在的环境中取值;depends_on,一个列表或映射;以及它的 models,一个模型名称列表,或一个映射,其条目可以在 endpoint_var 和 model_var 下指定模型的地址和标识符传递给服务所用的变量。其他所有 成员——command、healthcheck、secrets、env_file 等——都不写入任何地方,而是 在 Release 中该服务条目上方的注释里列出。
  • 模型。 顶层 models 的每个条目:它的 model(模型的 OCI 标识符)、 context_size 和 runtime_flags,在你的目录包含 core/ai-model/docker-model-runner 时按原样写入它的实例, 不包含时写入为该模型起草的模型 Component 的实例;模型的决策说明是哪一种以及原因。其他任何成员都在 其实例上方的注释中列出。
  • 其余部分。 其他顶层成员——name、networks、volumes、secrets、configs—— 不会被读取,Aggregate 开头的注释会列出它们。

服务、模型和服务的环境保持文件中书写的顺序。解析器的 树按排序后的顺序写出映射的成员,因此在以块映射书写时,顺序从文件文本中读取; 以流式风格书写的映射保持排序后的顺序。

服务是哪个 Component

导入器按服务镜像所指定的仓库匹配服务:即去掉标签和 摘要的引用,Docker Hub 引用使用其简写形式——docker.io/library/postgres:16 写作 postgres。它通过镜像表匹配仓库,该表将镜像 仓库映射到标准目录中某个 Compose Recipe 为其运行该仓库镜像的目录 Component。该表在构建导入器时由标准目录的 Compose Recipes 和 Components 生成并编译进导入器,因此导入运行时不读取任何 Recipe, 且无论你的目录包含什么,该表都包含标准目录的标签;导入器的 Plugin 实体在其描述中写明生成该表所用的 hub 修订版本。对于每个 Recipe,该表读取 Recipe 实现的 Component,以及其名为 main 的容器的镜像——前提是该镜像在自身文本中写明了仓库,或者是一个这样写明的 locals 条目。运行由 Release 完整指定的镜像的 Recipe,或以其他方式由模板组合镜像的 Recipe,不会添加 行;Recipe 在其主容器旁运行的镜像也不会。两个 Recipes 为不同的 Components 指定同一个 仓库时,表的生成会停止,因此一行绝不会在两者中指定其一。 对于一行所指定的 Component,该表按导入时交给导入器的方式读取其标签——即不带版本引用该 Component 时解析到的版本,包括通过 extends 继承的标签——并将除 component.aggrega.ai/category 以外的每个标签作为特征写入该行。实现标准目录中不存在的 Component 的 Recipe 同样会使表的生成停止。

行的读取方式与流程导入器的表行相同:Component、其名称所归入的类别、 其特征,以及其名称的最后一段作为供应商。 mapping_overrides 设置在 compose 格式下叠加在该表之上,以 仓库为键,针对表已映射的仓库的条目会取代该行。因此,标准目录的 Recipes 未指定的镜像——你自己的镜像, 或目录中某个 Component 以另一个仓库运行的镜像——通过条目进行映射:

with:
settings:
mapping_overrides:
compose:
bitnami/redis:
component: core/datastore/redis
category: datastore
traits:
datastore.aggrega.ai/engine: kv
vendor: redis

镜像被某行映射的服务,其决策方式与流程导入器对节点的决策相同:与你目录中的 Components 评分比较,当 reuse_mode 为 auto-apply-above-threshold(默认值)且其最佳候选是达到或高于 reuse_threshold 的高层级匹配时被引用,否则起草为独立的 Component,起草的 Component 文件开头有一条注释,指出它相似的 Component。一行携带其所指定 Component 的标签,因此当你的目录包含该 Component 且其标签与标准目录赋予的相同时,该行映射的服务是它的高层级匹配,得分 0.90,auto-apply-above-threshold 在默认 reuse_threshold 下引用它。你的目录修改过标签的 Component 得分较低,降低幅度与它不再携带的该行特征所占比例成正比,并且只有在仍处于高层级时才会被引用;类别只在其自身信号中衡量一次,不会再作为特征计算。起草同一个 Component 的多个服务共享其同一个文件。镜像未被任何行映射、镜像未指定导入器可读取的仓库,或自行构建镜像的服务,无论你的目录包含什么,都是 core/compute/server 的实例。每个服务的决策按每个节点的决策方式报告。

服务会变成什么

aggregate.yaml 是一个草稿 Aggregate,按草稿如何命名所述以项目命名,每个服务对应一个实例,实例的类型是该服务的决策所选的 Component,其键的取法与 MCP 导入器为服务器取键的方式相同;当键不是服务名,或导入读取了多个目录时,实例上方有一条注释,指出该服务及其来源文件。服务的 depends_on 所列的每个服务都是一条连接,即 uses: <key>: <key>: {target: <key>},写在一个 socket 和一个别名之下,二者都以目标的键命名。组件通过别名读取它的每条连接,无论该连接接入哪个 socket,因此服务的每条连接都有自己的别名。服务环境中的变量也可以生成连接,从它所指向的服务发布的内容中提供该变量,如服务的环境和镜像会变成什么所述。当工作区的目录包含 core/ai-model/docker-model-runner 时,无论 reuse_mode 如何设置,每个模型都是它的一个实例,且不为其起草 Component:该实例按源文件所写的形式写出 model 和 runtime_flags,并将源文件的 context_size 写为 context_window,即该运行时为模型上下文长度声明的值,其 Compose Recipe 会将其写回为 Compose 的 context_size。当目录中没有 core/ai-model/docker-model-runner 时,模型被起草为 <target_namespace>/ai-model/<key>,这是一个 ai-model 类别的 Component,其 values 声明 model、context_size 和 runtime_flags,其实例写出源文件所给的每一项。每个模型都有一条决策说明属于哪种情况——mapped llm (model) to core/ai-model/docker-model-runner as a reference, NONE,或一个草稿,其决策记录工作区的目录中没有 core/ai-model/docker-model-runner——无论哪种情况,引用该模型的每个服务都会连接到它,如同连接到它所依赖的服务。以长格式引用模型并带有 endpoint_var 或 model_var 的服务,会指明模型地址和标识符传给该服务时所用的变量。草稿中没有任何键保存变量名——连接写在以模型命名、不声明任何值的 socket 上,而导入器拿不到任何 Component 的 infrastructure 键——因此连接上方有一条注释,按条目所写的形式列出每个变量,服务的决策也记录同一句话:

search:
type: core/compute/server
uses:
# The service search reads the address of the model embedder as AI_MODEL_URL and its identifier as AI_MODEL_NAME, the names its models entry gives them; no key of the draft holds either name.
embedder:
embedder:
target: embedder

以短格式引用模型,或未带任何变量的服务,会连接到该模型,不附注释。

与之并列,release.yaml 是一个同名的草稿 Release,其 spec.aggregate 指向该 Aggregate。对于 core/compute/server 的实例,它写出 infra.image(按原样写出的镜像)和 infra.port(ports 第一个条目中容器监听的端口;若 ports 为空,则取 expose 的第一个条目)。使用 --target compose 时,它还会写出 infra.published_port,即同一个 ports 条目按源文件所写发布的主机端口,并附上注释,说明该端口只能从本机、由本机上运行的任何进程访问,删除该行即可使服务保持内部;低于 1024 的主机端口 published_port 不接受,因此不会写出,而由条目上方的注释指出。每个服务条目上方的注释写出源文件中有、但草稿中没有任何键承载的内容——匹配到其他 Component 且草稿未转换其标签的服务的镜像,它的 ports、expose、volumes,以及草稿未转换的 environment 中的每个变量——供你在 Component 接受时自行填入。草稿留给 Release 的内容——未指定镜像的服务的镜像(例如自行构建镜像的服务),以及不是单个数字的端口——会以空值写出,并附上说明原因的注释。构建只放置 Release 所列的实例,因此每个模型的实例在各服务条目之后都有一个空条目 <key>: {}:core/ai-model/docker-model-runner 的实例如此(它在 Compose 上没有缺少默认值的输入),被起草为独立 Component 的模型也是如此,因此起草的模型已经放置好,一旦你编写了实现它的 Recipe 即可构建。Component 不接受的端口(例如低于 core/compute/server 下限 1024 的端口)会按源文件所写写出,构建会因此中止并指出该端口。Release 写出 metadata.environment,在未指定目标时写出空的 spec.manifest,与 MCP 导入器的 Release 相同;指定目标时,导入会起草 Manifest,如目标会添加什么所述,将每个 Component 映射到在该目标上实现它的 Recipe——core/compute/server 映射到 compose/server 或 helm/server,core/ai-model/docker-model-runner 映射到 compose/docker-model-runner 或 helm/docker-model-runner。

一个运行 PostgreSQL 和一个依赖它的自有 API 的 compose.yaml:

services:
db:
image: postgres:16
environment:
POSTGRES_DB: shop
api:
image: ghcr.io/example/shop-api:1.4.2
depends_on:
- db
ports:
- "8080:8080"
environment:
CACHE_URL: redis://cache:6379/0

在不做任何设置、且目录中包含标准库的 core/datastore/postgres 时,单独导入,并因项目未带 name 而以文件命名,被起草为:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/compose
version: 0.1.0
description: Draft Aggregate imported from a source in the compose format.
spec:
components:
db:
type: core/datastore/postgres
# The values of core/datastore/postgres the source sets as POSTGRES_DB, the variables its Compose Recipes set from them.
values:
database: "shop"
api:
type: core/compute/server
uses:
db:
db:
target: db
release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/compose
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the compose format.
spec:
aggregate: imported/compose
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
db:
infra:
# The tag of the image the source runs, postgres:16, the engine_version of core/datastore/postgres its Compose Recipes run.
engine_version: "16"
# The source also states, for the Release to carry where core/compute/server takes it:
# ports:
# - "8080:8080"
# environment:
# CACHE_URL: "redis://cache:6379/0"
api:
infra:
image: "ghcr.io/example/shop-api:1.4.2"
port: 8080

导入报告 mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9。项目中没有 cache 服务,因此 CACHE_URL 不生成连接,保留在注释中。使用 reuse_mode: hints-only 时,db 则是 type: imported/datastore/postgres,起草在 components/imported-datastore-postgres.yaml 中,该文件以 # resembles core/datastore/postgres (score 0.9000); reference it by setting type: core/datastore/postgres 开头;此时它的镜像和环境写在其条目上方的注释中,因为起草的 Component 不声明目录中的 Recipes 所读取的任何值。指定 --target compose 时,Manifest 将 core/datastore/postgres 映射到 compose/postgres,将 core/compute/server 映射到 compose/server;指定 --target helm 时,则映射到 helm/postgres 和 helm/server。

服务的环境和镜像会变成什么

当服务是其镜像所在行指定的目录 Component 的实例,且工作区的目录包含该 Component 时,导入器会按照标准目录中该 Component 的 Compose Recipes 读取镜像和环境的方式来读取它们(依据镜像表为每个 Recipe 记录的内容),并将其转换到草稿中:

  • 镜像的标签是 Recipe 用来构建镜像引用的 infrastructure 键,例如 engine_version(postgres:16 对应 16),写在 Release 中,上方有一条指出源镜像的注释。
  • Recipe 根据 Component 的某个值设置的变量(POSTGRES_DB、POSTGRES_USER),若其值包含文本,则在目录的 Component 声明该值时,成为实例的该值 database 或 user,写在 Aggregate 中,上方有一条列出这些变量的注释。
  • Recipe 从中读取密码的变量,例如 POSTGRES_PASSWORD,若其值是单个变量引用,则成为挂接在该槽位上的 secret,从该引用指定的变量中读取,并以 Recipe 读取它时所用的键声明。

此外,对于每个服务,其环境中未按上述方式读取的每个变量:

  • 值为项目中另一个服务的名称时,若该服务所在行指定了发布其主机名的 provides 键,则生成一条到该服务的连接,其 inject 块从该键提供该变量——CACHE_HOST: cache 即从缓存的 host 得到 CACHE_HOST。
  • 值等于另一个服务为其 Component 设置、且该 Component 会发布的某个值时(例如 DATABASE_USER: notes,与之并列的 PostgreSQL 服务设置了 POSTGRES_USER: notes),生成一条连接,从该 provides 键提供该变量。若多个服务或键持有该值,则读取其键或其自身变量的结尾与该变量名结尾相同的那个;若没有,则读取该服务的其他变量尚未从中读取的那个;否则不读取该变量。
  • 值为单个变量引用、且所引用的变量是另一个服务的 secret 的读取来源时(DATABASE_PASSWORD: ${POSTGRES_PASSWORD}),在 core/compute/server 的实例上,若目标将 secret 写为服务器接受的值,它就成为一个独立的 secret,以小写的变量名挂接,并从同一个变量读取。helm/server 拒绝 core/referenced-secret,因此使用 --target helm 时,这类变量保留在注释中。

其他所有变量都按源文件所写保留在服务条目上方的注释中。Compose 导入演练展示了一个项目,其 API 以这种方式访问数据库和缓存,并按起草结果构建和运行。

服务持有的凭据值

Compose 不将任何环境变量值标记为凭据,导入器也不根据变量名判断其含义,因此每个非空的环境变量值都被定位为一个其格式未标记为凭据、但可能携带凭据的输入。默认情况下,每个值按原样写入草稿(写入它被转换成的值,或写入 Release 中其服务条目上方的注释),并在 credential-carried 警告中按其服务和变量(environment.<variable>)指出,从不写出其值。将 empty_credentials 设置设为 all 时,每个值被写为空并以 credential-emptied 报告:注释只列出变量,不带值。设为 marked 时不会清空任何值,因为 Compose 没有标记任何值。仅由一个 Compose 会插值的变量引用构成的值(${NAME} 或 $NAME)本身不含值:它按原文写出,不出现在任何警告中。带有默认值或消息的引用(例如 ${NAME:-value})含有该文本,会像其他值一样被定位。Compose 从别处读取的值(env_file、secret 的文件)不会被读取。

它读取的设置

Compose 导入器读取 target_namespace、reuse_mode、reuse_threshold、emit_hints、 render_mode、mapping_overrides 和 empty_credentials,含义如设置所述,不读取其他设置。emit_hints 控制的提示只写在起草的 Component 文件中;起草的 Aggregate 不带任何提示。

Dify 导入器

importer/dify 读取以 Dify DSL(Dify 为应用编写的 YAML 文档)从 Dify 导出的应用,并起草一个组合标准库中 Dify 安装 core/dify 的 Aggregate,应用由该安装的 app_definition 参数承载。安装在部署时通过其 API 服务器的 Recipe 为此渲染的步骤导入该应用。

读取的内容

  • 应用。 kind,其值为 app;version,即应用所用 DSL 的版本;以及 app 及其 mode。
  • 工作流或对话流(mode 为 workflow 或 advanced-chat)将其图保存在 workflow 下:workflow.graph.nodes 中每个在 data.type 下注明类型的节点都是应用的一个节点,按图列出的顺序排列;workflow.environment_variables 保存应用读取的变量。
  • 聊天、智能体聊天或文本生成应用将其配置保存在 model_config 下:其 model、dataset_configs.datasets.datasets 下的每个知识库以及 agent_mode.tools 下的每个工具都是应用的一个节点,以其所在位置命名,例如 model_config.model。agent 模式的应用是一个节点,即 agent。
  • 应用所需的插件。 dependencies 的每个条目也是一个节点,命名为 dependencies.<n>,其类型为条目所注明的类型,例如 marketplace。

起草的内容不由其他任何因素决定:整个应用都会被承载。

应用变成什么

aggregate.yaml 是一个草稿 Aggregate,按草稿如何命名所述以应用命名,组合一个键为 dify 的 core/dify 条目,其 app_definition 参数按原样承载应用,方式与流如何写入草稿对流的描述相同,因此 Dify 自身的 {{#…#}} 引用按导出时的样子到达安装。安装自行连接其 API 服务器的所有连接:数据库、缓存、向量存储、沙箱、插件运行时和出站代理。因此草稿不起草任何 Component,也不连接任何内容:每个节点都保留在应用中,其决策也如此说明。在它旁边,release.yaml 是一个同名的草稿 Release,它将安装放置在一个边界 platform 中,并承载应用无法提供的内容。

导入能看到工作区目录中的 Components,但看不到其中的 Aggregates,因此不会检查目录是否包含 core/dify,条目上方的注释会说明这一点。若目录中没有 core/dify 所运行的 API 服务器 core/ai-agent/dify,导入会以 platform-not-in-catalog 发出警告,但仍照常起草该条目。

安装的应用密钥是 Dify 用来签名会话 cookie、并用来加密其所存储的模型提供方凭据的密钥,即 core/dify 的 secret_key 参数,它没有默认值。因此,草稿会声明一个自己的 secret_key 参数——字符串类型、必填、长度至少为一个字符且没有默认值——并将其传递给它写入的每个 core/dify 条目,由 Release 在其 parameters 下提供;如果 Release 未设置它,构建会停止并指出它的名称。

应用以安装的所有者账户导入,该账户由 Release 在其针对该安装的路由条目中指定:安装的 api 组件上的 infra.owner_email,以及该组件上的 owner_password 槽位,后者以 core/referenced-secret 的形式附加,缺少它们构建会停止。所有者的电子邮件不是任何来源能够提供的,因此它被写为空值,上方有一条注释说明它是什么,导入会将其列为待提供的值。

在每个目标上,同一个路由条目都会在安装的 api、worker 和 scheduler 组件上将 infra.marketplace_enabled 设为 true,每一项上方都有注释说明原因:除非 Release 允许,否则安装无法访问 Dify 供应商的任何内容;这三个组件各自读取自己的设置;而 Dify 会从其插件市场安装为应用的模型(例如 OpenAI 的模型)提供服务的插件。

应用密钥和所有者的密码都是 secret,会按导入的目标以引用方式起草:

  • 在 --target helm 下,每一项都指定一个已存在于命名空间中的 Kubernetes Secret:secret_key 指定该 Secret 的名称,core/dify 在数据键 secret-key 下读取它;owner_password 指定一个在数据键 value 下保存密码的 Secret。这两个名称都不是任何来源能够提供的,因此每一项都被写为空值,上方有一条注释说明它是什么,导入会将两者都列为待提供的值;起草的 Manifest 将 core/referenced-secret 映射到 helm/k8s-existing-secret。
  • 在其他所有目标上,以及没有目标时,每一项都是对一个变量的引用——secret_key 写为 "${DIFY_SECRET_KEY}",所有者的密码写为 "${DIFY_OWNER_PASSWORD}",即标准目录中面向 Compose 的 Dify Recipes 所读取的名称——Docker Compose 会在栈启动时从环境中读取它们,因此两者都无需另行提供;在 --target compose 下,起草的 Manifest 将 core/referenced-secret 映射到 compose/dotenv-referenced-secret。

给定目标时,Manifest 会映射安装所组合的每个组件的类型以及草稿自身的类型,如目标会添加什么所述。

本导入器测试所导入的编写好的工作流应用,名为 Support Answers,在不做任何设置时起草为:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-answers
version: 0.1.0
description: Draft Aggregate imported from a source in the dify format.
spec:
parameters:
secret_key:
type: string
required: true
minLength: 1
description: "Passed down to core/dify's secret_key parameter, which has no default; that parameter's description in core/dify says what the value is."
aggregates:
# An import sees the Components of the workspace's catalog and none of its Aggregates, so it does not check that the catalog holds core/dify.
dify:
type: core/dify
parameters:
secret_key: "{{ .parameters.secret_key }}"
app_definition: |
app:
description: Answers a support question from a knowledge base and files it.
...

使用 --target helm 导入时,其起草的 Release 会提供 secret_key,并在放置安装的路由条目中指定所有者并开启插件市场,其中每个待提供的值都写为空值:

release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/support-answers
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the dify format.
spec:
aggregate: imported/support-answers
manifest: imported/support-answers
parameters:
# Left for the Release, since the source cannot supply it: secret_key, which the drafted Aggregate declares and passes down to core/dify; that parameter's description there says what the value is
secret_key: ""
boundaries:
platform:
aggregates:
dify:
components:
api:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
# Left for the Release, since the source cannot supply it: components.api.infra.owner_email, the email of the installation's owner account the application is imported under, on the api component of core/dify
owner_email: ""
features:
owner_password:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding, under the data key value, the owner account's password.
origin: ""
worker:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
scheduler:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true

导入会将这三个空值列为待提供的值。使用 --target compose 导入时,同一个 Release 会写入 secret_key: "${DIFY_SECRET_KEY}" 和 origin: "${DIFY_OWNER_PASSWORD}",只将所有者的电子邮件列为待提供的值;它还会在 api 组件上写入 infra.published_port 为 5001,在前端即 console 组件上写入 3001,每一项上方都有注释说明该服务只能从本机访问,本机上运行的任何进程都可以访问,并且删除该行会使服务保持为内部服务;并在 api 组件的端口下方写入 infra.console_url,其值为控制台发布所在的地址 "http://127.0.0.1:3001",Dify 服务器将其作为控制台的地址。Dify 导入演练为两种目标构建一个应用,并在 Kubernetes 上运行它。

Dify 自行配置的内容

Dify 在内部配置应用所调用的模型和工具的提供方,且 core/ai-agent/dify 未声明模型套接字,因此草稿不连接任何模型。每个指明此类内容的节点都以 part-configured-in-platform 报告,并在其决策中按所指明的内容说明:

  • llm、question-classifier 或 parameter-extractor 节点,以及聊天应用的 model_config.model:模型,按其名称和提供方;
  • tool 节点,以及聊天应用的工具:工具,按其名称和提供方;
  • agent 节点:智能体策略及提供该策略的插件;
  • knowledge-retrieval 节点,以及聊天应用的知识库:其检索的知识库,以及其用于路由查询或重排序的模型(如有指明)。应用以导出它的安装中的标识符来指明知识库,且不携带任何文档和存储,因此每个知识库都在 Dify 内部创建,位于安装连接到其 API 服务器的向量存储中;
  • 依赖:插件,按 Dify 安装它所用的标识符,以及 Dify 从何处安装它。

其他所有节点都保留在应用中,不报告任何内容。

应用持有的凭据值

导入器按应用编写的顺序定位:

  • 每个 value_type 为 secret 的环境变量的值,Dify 将其标记为凭据。除非导出包含密钥,否则 Dify 的导出将其写为空;
  • HTTP 请求节点的 authorization.config.api_key,Dify 将其标记为凭据并按原样导出;
  • tool 节点或 agent 节点的工具在 credential_id 下选择的已存储凭据,Dify 将其标记为凭据,且仅在导出包含密钥时写入;
  • HTTP 请求节点的 headers 和 params,Dify 未将其标记为凭据,但它们可能携带凭据,各自整体定位。

默认情况下,每个持有值的项都按原样承载在应用中,并在 credential-carried 警告中以其节点(环境变量为 workflow)和字段指明,从不以其值指明。当 empty_credentials 设置为 marked 时,Dify 标记为凭据的每个值都写为空;为 all 时,请求头和查询参数也写为空,每项以 credential-emptied 报告。仅为一个变量引用而无其他内容的值不持有值,无论设置如何都按原样承载,且不在任何警告中指明,与 流中相同。值在应用自身的文本中写为空:其键后的标量替换为 '',其他内容不变。仅当服务 parse:yaml 的解析器将结果读回为恰好清空了这些值的导出应用时,才承载该应用;否则不承载,app_definition 保持未设置并附注释,并由 definition-not-carried 说明原因,例如应用中有 YAML 别名读取密钥的值,将该值写为空也会改变它。设置保留原样的值从不被改写,因此从不会阻止应用被承载。

DSL 版本

若应用所用 DSL 版本比 0.7.0(core/ai-agent/dify 默认运行的 Dify 1.17.0 所写的版本)更新,导入会以 dsl-version-newer 发出警告。Dify 会暂停此类应用的导入以等待确认,部署时导入它的步骤会给出确认,因此请对照 Release 所运行的 Dify 版本检查应用。

它读取的设置

Dify 导入器读取 target_namespace、empty_credentials、layout、attach_egress_allowlist 和 render_mode,如设置所述;还读取 reuse_mode、reuse_threshold、 emit_hints 和 mapping_overrides,但它们不改变默认布局起草的任何内容:每个节点都保留在应用中。attach_egress_allowlist 不附加任何内容,因为被组合的 Aggregate 的条目接受参数而不接受 Feature;将其设为 true 时,导入会以 feature-not-attached 发出警告。layout: nodes 将每个节点起草为独立的 Component,如 逐节点所述,且不承载应用。

CrewAI 导入器

importer/crewai 读取 CrewAI 项目在其配置文件中声明的 agent 和任务,并起草一个 Aggregate,其中每个 agent 对应标准库 CrewAI agent core/ai-agent/crewai 的一个实例,每个实例都连接到其配置所指定的模型,同时在其旁边起草一个 Release。

读取的内容

CrewAI 将 crew 的行为保存在程序中,并在配置文件中声明其 agent 和任务,配置文件采用两种布局之一,导入器两种都能读取:

  • 经典项目——config/agents.yaml,其中每个 agent 以其名称为键;以及 config/tasks.yaml,其中每个任务以其名称为键,两者都按 YAML 读取。agent 按 agents.yaml 中书写的顺序读取。
  • 采用 JSON 优先布局的项目——crew.jsonc,它在 agents 下按名称列出 crew 的 agent,在 tasks 下列出其任务;以及 agents/<name>.jsonc,每个 agent 一个文件。所有这些文件都按带注释的 JSON 读取,因此其中的注释和尾随逗号按 CrewAI 的方式读取。agent 按 crew.jsonc 列出的顺序读取,随后是其他 agent 的文件,按名称排序;crew 列出但导入未获得其文件的 agent 会在注释中注明,且不起草任何内容。 以严格 JSON 书写的同一布局——crew.json 和 agents/<name>.json——按相同方式读取。如果某个 crew 或 agent 同时以两种形式书写,则按 CrewAI 的方式读取 .jsonc 文件,.json 文件则在注释中注明为未读取。

对于 agent,导入器读取其 role、goal 和 backstory;位于声明顶层或 settings 下的 allow_delegation 和 verbose,两处都有时以 settings 为准,与 CrewAI 的读取方式一致;其 llm;以及其 tools 的名称。对于任务,读取其名称及其所分配的 agent。其他所有成员都在注释中注明,不会携带到任何地方。

目录交给导入器时,只包含其签名所指定的文件,不含其他文件,因此 crew 的程序——经典项目的 crew.py、flow 的 main.py、项目用 Python 定义的工具——永远不会被读取。单独导入的文件按其结构所对应的声明读取。一个项目的目录可以包含多个 crew,每个 crew 从其自己的目录读取。

项目会变成什么

aggregate.yaml 是一个 Aggregate 草稿,按草稿如何命名所述以 crew 命名,开头的注释列出已读取的声明、说明 crew 的程序未被读取,并列出每个 crew 的任务及每个任务所分配的 agent。它为每个 agent 包含一个以其名称为键的 core/ai-agent/crewai 实例,其中:

  • role、goal 和 backstory 按声明设置;
  • allow_delegation 按声明设置,agent 未声明时为 false;
  • 声明为 verbose 的 agent 的 log_level 为 DEBUG,会叙述其推理的每一步;未声明的则为 INFO,只报告进度和问题。既不是 true 也不是 false 的 verbose 或 allow_delegation 保留为 Component 的默认值,并在注释中注明;
  • 其 model 连接,连接到其 llm 所指定模型的实例。

写作 <provider>/<model> 的 llm,或写作对象并在 model、model_name 或 deployment_name 下指明模型者,指明一个提供方和一个模型。该模型是目录中对应该提供方的 Component 的一个实例——core/ai-model/<provider>,提供方名称中的下划线读作连字符,azure 读作 azure-openai——以模型名称为键,并以该模型作为其 values.model;指明同一提供方和模型的多个 agent 共享一个实例。如果工作区的目录中没有该名称的 Component,则起草一个 <target_namespace>/ai-model/<provider>,声明 model 值,并在其决策中说明;agent 的 model socket 据以选择 Component 的 model.aggrega.ai/api 标签,以及发布其端点和模型的 Recipe,留给你补充,如其开头的注释所述。未指明提供方的 llm——即裸模型名称(CrewAI 在程序运行时为其解析提供方),或程序所定义的某个 llm 的名称(即对程序的引用)——以及未声明 llm 的 agent(CrewAI 随后从其程序运行的环境中读取),都不连接任何对象,agent 上方的注释会说明原因;在连接之前,构建会停止并指明 model socket。

任务是 crew 的程序运行的逻辑,工具是程序定义或加载的代码:两者都不会成为 Component。每一项都在一个不做任何选择的决策中报告;如果某个工具的名称——去掉末尾的 Tool 以及其中的连字符和下划线后——与目录中某个工具 Component 的名称相同,则会将该 Component 作为提示携带:search_tool 和 SearchTool 都提示 core/ai-tool/search。core/ai-agent/crewai 没有为工具声明 socket,因此不会为工具连接任何内容。

旁边的 release.yaml 是一个同名的 Release 草稿,指向该 Aggregate。它将每个 agent 的 infra.image——运行 crew 程序的镜像,任何声明都未指定——写为空值,上方有一条注释说明它是什么,导入会将其列为待提供的值。使用 --target compose 时,每个 agent 的条目还会写入 infra.published_port 为 8000,即 Component 的 infra.port 默认为该程序指定的端口,其 Compose Recipe 将其发布在主机的回环地址 127.0.0.1 上,上方有注释说明该服务只能从本机访问,本机上运行的任何进程都可以访问,并且删除该行会使服务保持为内部服务;第二个 agent 使用下一个空闲端口,因此经典项目的两个 agent 分别发布在 8000 和 8001 上。它将每个 agent 向其模型出示的凭据附加在其 model 连接的 credential 下,以引用方式而非值的方式:没有任何声明为其指定变量,因此它从提供方的客户端库读取 API 密钥所用的变量中读取——对于 OpenAI 为 OPENAI_API_KEY——在除 helm 之外的所有目标上以 ${…} 引用的形式,在 helm 上则作为一个 Kubernetes Secret 的名称,写为空值,由导入列为待提供的值;在 compose 上,agent 的 model 连接以该键声明它。每个模型也有一个条目,其中不含任何基础设施,因此 Release 将模型与各 agent 一起放置。对于以 llm 对象声明的模型,其其他每个成员在目录的 Component 声明了同名值时写为模型实例的值,否则写在 Release 中该模型条目上方的注释里,供你在该 Component 接受它的位置携带。与每个起草的 Release 一样,它将 metadata.environment 写为 development,并在没有目标时写入一个由导入列为待提供的空 spec.manifest;给定目标时,导入会起草 Manifest,如目标会添加什么所述。

本导入器的测试所导入的经典项目,其两个 agent 都指定 openai/gpt-4o,在没有任何设置时起草如下;若以其项目目录 market_brief(即 crewai create crew market_brief 为此类项目创建的目录)导入,由于其声明未指定任何 crew,它以该目录命名:

aggregate.yaml
# CrewAI declarations read:
# - src/market_brief/config/agents.yaml
# - src/market_brief/config/tasks.yaml
# Not read: the crew's program, which runs its agents and its tasks and defines its tools; it runs in the image the Release names for each agent.
# Tasks the crew's program runs, drafted as no Component:
# - research_task, assigned to researcher
# - brief_task, assigned to brief_writer
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/market-brief
version: 0.1.0
description: Draft Aggregate imported from a source in the crewai format.
spec:
components:
# Tools the crew's program defines or loads for this agent, drafted as no Component: search_tool.
researcher:
type: core/ai-agent/crewai
values:
role: "{topic} Market Researcher\u000A"
goal: "Gather the facts about {topic} a buyer needs before a first meeting\u000A"
backstory: "You have briefed sales teams for years. ..."
allow_delegation: false
log_level: DEBUG
uses:
model:
gpt-4o:
target: gpt-4o
# For the compose target only, uncomment the lines below, which declare credential on gpt-4o: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# The agent brief_writer.
# Not carried, since core/ai-agent/crewai takes no value for it: max_iter.
brief-writer:
type: core/ai-agent/crewai
...
# The model openai/gpt-4o.
gpt-4o:
type: core/ai-model/openai
values:
model: "gpt-4o"

以及其 Release,在没有目标的情况下起草如下,这里省略了第二个 agent 的条目并以 ... 标记;导入会将 spec.manifest 和每个 agent 的镜像列为待提供的值:

release.yaml
spec:
aggregate: imported/market-brief
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
researcher:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the crew's program
image: ""
uses:
model:
gpt-4o:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential researcher presents to gpt-4o on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
brief-writer:
...
gpt-4o: {}

随后,每个 agent 渲染为运行你所回答的镜像,并以 OPENAI_BASE_URL 和 MODEL 获得模型的端点和模型名称,CrewAI 从这两个变量中读取它们。

声明中包含的凭据值

以对象形式书写的 llm 可以携带密钥——在 api_key 下、在地址中、在 header 中。除指定模型的成员外,其每个不是数字或布尔值的成员都是可能携带密钥的值,CrewAI 不将其标记为凭据。默认情况下,每个持有值的成员都按原样携带——在其 Component 声明了相应值时作为模型实例的值,否则携带到 Release 中其模型条目上方的注释里——并在 credential-carried 警告中按其 agent 和成员(例如 llm.api_key)指出,从不按其值指出。当 empty_credentials 设置 为 all 时,每一项都写为无值,并以 credential-emptied 报告;为 marked 时每一项都会携带,因为 CrewAI 未标记任何一项。成员的名称不会按其含义解读。声明中草稿未携带的其他所有成员——工具的配置、crew 的 inputs——只注明名称,从不给出值。

它读取的设置

CrewAI 导入器读取 target_namespace、empty_credentials 和 render_mode,如 设置 所述,不读取其他任何设置。

LangGraph 导入器

importer/langgraph 读取 LangGraph 应用的配置 langgraph.json 所声明的图,并起草一个 Aggregate:其中每个图对应一个标准库 LangGraph 智能体 core/ai-agent/langgraph 的实例,各自连接到其 checkpointer 保存状态所用的数据存储以及一个模型;同时在旁边起草一个 Release,承载该配置所声明的环境。它读取该配置,从不读取图的代码。

读取的内容

LangGraph 应用将图保存在代码中,并在 langgraph.json 中声明它们:在 graphs 下,每个图的 id 映射到应用代码中该图的导入路径(./src/agent/graph.py:graph 或 module:attr),或映射到一个对象,该对象在 path 下给出该路径,在 description 下描述该图。导入器按配置书写的顺序读取:

  • graphs:每个图的 id、导入路径和描述;
  • checkpointer:其 backend,可以是 default,即 PostgreSQL,也是未指定时 LangGraph 采用的值;mongo,即使用 MongoDB 协议的数据库;或 custom,即应用代码在 path 处定义的 checkpointer;
  • store:内存存储,不指定后端:LangGraph 将其保存在其服务器所用的 PostgreSQL 数据库中;
  • env:应用运行时的环境:一个由变量名映射到值的对象,或一个由 KEY=VALUE 行组成的环境文件的路径。

配置 langgraph build 所构建的服务器镜像的成员(dependencies、source、python_version、node_version、base_image、image_distro、dockerfile_lines、pip_config_file、pip_installer、keep_pkg_tools、api_version)会在注释中列出而不被承载,因为 Release 所指定的镜像是应用自己的镜像;其他所有成员(其中包括服务器自身的配置,如 auth、http 和 webhooks)也是如此,store 的 index 和 ttl 以及 checkpointer 的 ttl 和 serde 同样如此。

目录交给导入器时只包含 langgraph.json,不含其他文件,因此从不从中读取应用代码或环境文件。环境文件只有在导入器的 with.sources 提供它时才会到达导入器,且从不被解析:对于配置的 env 所指定的那个文件(按其路径的最后一段匹配),只读取变量名;没有任何配置指定的环境文件会在注释中标明为未读取。如果导入时未提供配置所指定的文件,Aggregate 会标明它未提供,并说明应在导入器的 with.sources 下指定它,其变量留给 Release:

plugins:
importer:
- uri: importer/langgraph:<version>
with:
sources:
- ./local.env

单独导入的配置无论名称如何都会被读取。一个目录可以包含多个应用,每个应用从其各自的目录读取。

应用变成什么

aggregate.yaml 是一个 Aggregate 草稿,按草稿如何命名所述以图命名,开头的注释列出所读取的配置、仅读取了名称的环境文件、未读取应用代码这一事实,以及草稿未承载的内容。它为每个图包含一个以其 id 为键的 core/ai-agent/langgraph 实例,具有:

  • graph_entrypoint:图的导入路径,与配置中的写法一致;
  • description:图的描述(如果配置给出了);
  • 其 checkpointer_db 连接,连接到应用的数据存储;
  • 其 model 连接,连接到应用的模型。

不写入 recursion_limit,因此沿用该 Component 的默认值 25。配置没有指定模型,因此草稿包含一个键为 model 的 core/ai-model/openai 实例,每个图都会调用它:即交给 agent 的 OpenAI 客户端的模型。其 values.model 写为空值,上方有一条注释说明配置未指定任何模型,导入会将其列为待提供的值。

checkpointer 的后端就是应用的每个图所连接的数据存储:default 或未指定后端的 checkpointer 对应 core/datastore/postgres 的一个实例,键为 postgres。mongo 是 FerretDB,它使用 MongoDB 的协议,运行在带有 DocumentDB 扩展的 PostgreSQL 之上:即一个键为 ferretdb 的 core/datastore/ferretdb 实例,每个图都连接到它;以及一个键为 documentdb 的 core/datastore/documentdb 实例,FerretDB 的 backend 连接到达它,其 inject 块以 FerretDB 读取的名称交付 DocumentDB 所发布的内容;一个从变量 FERRETDB_PASSWORD 读取的密码,附加在 DocumentDB、FerretDB 到它的连接以及每个图到 FerretDB 的连接上。如果工作区的目录中没有以 PostgreSQL 数据存储命名的 Component,则会起草一个 <target_namespace>/datastore/postgres,声明智能体的 checkpointer_db 连接所读取的 host 和 port,其决策会说明这一点;运行该数据存储并发布这些值的 Recipe 留给你编写,其开头的注释会说明这一点。如果目录中没有 FerretDB 或 DocumentDB 的 Component,mongo checkpointer 不会连接到任何数据存储。custom checkpointer,或导入器无法映射到任何数据存储的后端,不会连接任何内容,每个图上方的注释和 checkpointer 的决策会说明原因;在连接之前,构建会停止并指出 checkpointer_db 插槽。store 会在一个不做任何选择的决策中报告。

数据存储的密码是草稿以引用方式附加的 secret,附加在数据存储自身的 password 槽位和每个图的 checkpointer_db 连接上;每个图在其 model 连接上向模型出示的凭据也是如此:由于配置没有为两者指定变量,它们分别从 POSTGRES_PASSWORD(或 FERRETDB_PASSWORD)和 OPENAI_API_KEY 读取,在除 helm 之外的所有目标上以 ${…} 引用的形式,在 helm 上则作为一个 Kubernetes Secret 的名称,写为空值,由导入列为待提供的值。在 compose 上,Aggregate 以其 Recipe 读取的键声明每一项,如各目标的 secret针对平台所述。

旁边的 release.yaml 是一个同名的 Release 草稿,指向该 Aggregate。第一个图条目上方的注释说明每个图的镜像是什么(应用自己的镜像,即安装了 LangGraph 的应用代码,而不是 langgraph build 构建的服务器镜像)、它接收哪些变量,以及哪个 inject: 块替换其中哪个变量名。每个图的条目将其 infra.image(即运行该应用的镜像)写为空值,上方有一条注释说明它是什么,导入会将其列为待提供的值;在未设置期间,Docker Compose Recipe 运行目录自带的快速入门智能体,它读取默认变量。使用 --target compose 时,每个图的条目还会写入 infra.published_port 为 8000,即 Component 的 infra.port 默认为该应用指定的端口,其 Compose Recipe 将其发布在主机的回环地址 127.0.0.1 上,上方有注释说明该服务只能从本机访问,本机上运行的任何进程都可以访问,并且删除该行会使服务保持为内部服务;第二个图使用下一个空闲端口。数据存储和模型也有条目,因此 Release 会将它们与各个图放置在一起。应用第一个图上方的注释给出其配置所声明的环境,如配置所声明的环境所述。与每个起草的 Release 一样,它将 metadata.environment 写为 development,并在没有目标时写入一个由导入列为待提供的空 spec.manifest;给定目标时,导入会起草 Manifest,如目标会添加什么所述。

该导入器的测试所导入的 Python 应用声明了两个图、一个未指定后端的 checkpointer、一个 store 以及一个以对象形式书写的 env,在不使用任何设置时起草如下;若以其目录 support_desk(如此处所示,以定义其图的包命名)导入,由于它有两个 id 不同的图,它以该目录命名:

aggregate.yaml
# LangGraph configurations read:
# - langgraph.json
# Not read: the application's code, which defines each graph; it runs in the image the Release names for each graph.
# Not carried, since they configure the server image langgraph build builds, and the image the Release names is the application's own: dependencies, python_version.
# Not carried, since core/ai-agent/langgraph takes no value for them: http.
# The store configures the memory store, which LangGraph keeps in the PostgreSQL database its server uses; not carried, since core/ai-agent/langgraph takes no value for it: index, ttl.
# Not carried, since core/ai-agent/langgraph takes no value for them: checkpointer.ttl.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-desk
version: 0.1.0
description: Draft Aggregate imported from a source in the langgraph format.
spec:
components:
triage:
type: core/ai-agent/langgraph
values:
graph_entrypoint: "./src/support_desk/triage.py:make_graph"
description: "Routes an incoming ticket to the {team} that owns it."
uses:
checkpointer_db:
postgres:
target: postgres
# For the compose target only, uncomment the lines below, which declare credential on postgres: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: POSTGRES_PASSWORD
model:
model:
target: model
# For the compose target only, uncomment the lines below, ...
support:
type: core/ai-agent/langgraph
...
# The database the configuration's checkpointer keeps each graph's state in, PostgreSQL.
postgres:
type: core/datastore/postgres
# For the compose target only, uncomment the lines below, ...
# The model every graph calls, which the configuration does not name.
model:
type: core/ai-model/openai
values:
# Left for the author, since the configuration names no model: values.model, the name of the model core/ai-model/openai serves.
model: ""
release.yaml
spec:
aggregate: imported/support-desk
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# Each graph's image is the application's own, not the server image langgraph build builds: its code, with LangGraph installed.
# It is handed, for its code to read, the graph to run as LANGGRAPH_GRAPH_ENTRYPOINT, the model's name as OPENAI_MODEL, the checkpointer store's host and port as LANGGRAPH_CHECKPOINTER_HOST and LANGGRAPH_CHECKPOINTER_PORT, its user and database, where the store publishes them, as LANGGRAPH_CHECKPOINTER_USER and LANGGRAPH_CHECKPOINTER_DATABASE, and a password attached on the checkpointer_db connection as LANGGRAPH_CHECKPOINTER_PASSWORD.
# It is also handed the model's address as OPENAI_BASE_URL and a key attached on the model connection as OPENAI_API_KEY, which the OpenAI client library reads, and recursion_limit as LANGGRAPH_DEFAULT_RECURSION_LIMIT, which LangGraph reads.
# An inject: block on the graph's own instance, through an entry reading graph_entrypoint alone, replaces LANGGRAPH_GRAPH_ENTRYPOINT with the name it writes; one on the model connection replaces OPENAI_MODEL, and one on the checkpointer_db connection the store's host, port, user and database, with the names it writes.
# The environment langgraph.json states for its application, for the Release to carry where core/ai-agent/langgraph takes it for each of its graphs:
# SUPPORT_QUEUE: "..."
# OPENAI_API_KEY: "..."
# MAX_TICKETS: "25"
triage:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application
image: ""
uses:
checkpointer_db:
postgres:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential triage presents to postgres on its checkpointer_db connection, the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
model:
model:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential triage presents to model on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
...
postgres:
features:
password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
model: {}

导入会将四个值列为待提供的值:spec.manifest、每个图的镜像和模型的名称。回答这些值之后,每个图被渲染为运行你所回答的镜像,并以 LANGGRAPH_CHECKPOINTER_HOST 和 LANGGRAPH_CHECKPOINTER_PORT 获得其数据存储的地址,以 LANGGRAPH_CHECKPOINTER_USER 和 LANGGRAPH_CHECKPOINTER_DATABASE 获得数据存储所发布的用户和数据库(PostgreSQL 两者都会发布;如果数据存储两者都不发布,则这两个变量都不会被渲染),以 OPENAI_BASE_URL 和 OPENAI_MODEL 获得模型的端点和名称,以 OPENAI_API_KEY 获得其模型凭据交付的密钥,以 LANGGRAPH_GRAPH_ENTRYPOINT 获得其导入路径,以 LANGGRAPH_DEFAULT_RECURSION_LIMIT 获得其步数上限。附加在其 checkpointer_db 连接上的凭据还会以 LANGGRAPH_CHECKPOINTER_PASSWORD 向其提供数据存储的密码。

配置所声明的环境

配置的 env 所列出的每个变量都是需要由 Release 提供的输入,且都不会被起草为凭据槽:LangGraph 不将任何变量标记为机密,且不会根据变量名推断其含义。core/ai-agent/langgraph 不接受环境的值,因此 Release 在应用第一个图上方的注释中给出它。

  • 以对象形式书写的 env 是配置的一部分,因此其值会按原样、按配置书写的顺序写入该注释。每个非空值都可能携带凭据,而 LangGraph 不将其标记为凭据:默认情况下,每个值都按原样承载,并在 credential-carried 警告中以其配置和变量(如 env.OPENAI_API_KEY)指明,从不显示其值。当 empty_credentials 设置为 all 时,每个值都写为空值并以 credential-emptied 报告;为 marked 时,每个值都会承载,因为 LangGraph 不标记任何值。
  • 指向文件的 env 指向一个配置仅引用的文件,该文件通常包含本地机密。只有当导入器的 with.sources 提供它时才会读取。注释列出该文件中的每个变量,留给 Release 提供,并且不读取文件中的任何值:无论设置如何,都不会有值进入草稿、决策或诊断。跨多行引用的值算作一个值,因此其中的行不会被当作变量,未指定变量的行会以其行号标明。如果导入时未提供该文件(对于目录始终如此,目录从不提供该文件),Aggregate 会标明它未提供,并说明如何提供,其变量留给 Release。

它读取的设置

LangGraph 导入器读取 target_namespace、empty_credentials 和 render_mode(如设置所述),不读取其他任何设置。

Google ADK 导入器

importer/google-adk 读取基于 Google 的 Agent Development Kit(ADK)构建的应用在其 Agent Config 文件(root_agent.yaml 及其子智能体所指定的配置)中声明的智能体,并起草一个 Aggregate:每个智能体树对应一个标准库 ADK 智能体 core/ai-agent/google-adk 的实例,当 ADK 将该树所指定模型的请求发送到 Gemini API 时,该实例连接到该模型;同时在其旁边起草一个 Release。它读取这些配置,从不读取应用的代码。

ADK 声明其 Agent Config 功能尚属实验性质。智能体的模型默认是 Gemini 模型;对于其他一些提供方的模型,ADK 通过自己的类按名称提供,例如 claude-sonnet-4-5 和 gpt-4o,另一些则通过 LiteLLM 模型字符串提供。智能体的 model 套接字只接受 Gemini API,因此导入器会连接 ADK 发送到 Gemini API 的模型,其他模型则留给你处理,如智能体树会变成什么所述。

读取的内容

ADK 的 adk create --type=config 会写入 root_agent.yaml(应用根智能体的配置),并在其旁边写入一个环境文件。 一个配置声明一个智能体:

  • name、description 和 agent_class——ADK 构建该智能体所用的类,未指定时为 LlmAgent;
  • model——智能体请求的模型——或 model_code,即对构建其模型的代码的引用;
  • tools——按 name 列出的每个工具,以及其配置传给它的 args;
  • generate_content_config——智能体模型请求的选项,其中包括 http_options;
  • sub_agents——每项为 config_path,即相对于引用它的配置所在目录的另一个配置的路径, 或为 code,即由应用代码构建的智能体。

目录交给导入器时,只交其中的 root_agent.yaml 文件,不交其他文件;单独导入的配置无论名称如何,都作为根读取。 每个根的树先读根,再按各智能体列出的顺序读取其子智能体。sub_agents 条目通过 config_path 指定的配置, 仅在导入器的 with.sources 提供它时才读取,按路径的最后一段匹配;导入未获提供的配置会在 Aggregate 及其决策中被标明为未提供, 并说明如何提供,其智能体不会被读取:

plugins:
importer:
- uri: importer/google-adk:<version>
with:
sources:
- ./my_agent/code_tutor_agent.yaml
- ./my_agent/math_tutor_agent.yaml

绝对路径的 config_path,或指向命名它的配置所在目录之外的路径,不会被读取,因为 ADK 也会拒绝它。with.sources 交出但没有任何配置命名的文件,会在注释中被注明为未读取,其任何内容都不会被读取;它交出的文件只作为某个根的树所命名的配置来读取,因此一个既不含 root_agent.yaml、也没有单独导入的文件的导入不会读取任何树,并在 no-nodes 下报告每个文件。应用的代码——配置通过其代码命名的工具、回调、schema 和 agent——以及环境文件从不会被交给导入器,导入器两者都不读取:应用从 Release 指定的镜像中自行加载其配置。一个目录可以包含多个应用,每个应用都从其自身的 root_agent.yaml 读取。

配置的其他成员(其中包括智能体的 instruction)由应用从其自身配置中读取, 因此草稿不携带其中任何一个。

智能体树变成什么

ADK 从根智能体提供应用,其配置所指定的每个智能体都在其中构建,而 core/ai-agent/google-adk 运行一个这样的应用。因此,aggregate.yaml 是一个草稿 Aggregate,按草稿如何命名所述以根智能体命名,每个智能体树对应一个以其根智能体名称为键的 core/ai-agent/google-adk 实例,包含:

  • description,根智能体的描述(如果其配置提供);
  • 其 model 连接,在 ADK 将该模型的请求发送到 Gemini API 时,连接到该树指定的模型。

其上方的注释列出:树中的其他智能体,它们不会成为各自的实例;每个未读取的子智能体及其原因——由应用代码构建、导入未获提供的配置,或 ADK 拒绝的配置;树中智能体指定的工具,包括 ADK 自带的和应用代码定义的;类为 LoopAgent、ParallelAgent 或 SequentialAgent、ADK 已弃用并推荐改用 Workflow 的智能体;以及在树的模型已连接时,树中其他智能体请求的模型,每个模型都附有 ADK 为其提供服务所经由的模型系列。每一项都在一个不做任何选择的决策中报告。

树中第一个(从根开始)指定模型或构建模型的代码的智能体决定实例的模型。它指定的模型若由 ADK 将其请求发送到 Gemini API——即 ADK 通过其 Gemini 类提供的模型名称(例如 gemini-2.5-flash,Vertex AI 资源名称除外),或通过其 Gemma 类提供的模型名称——则是一个 core/ai-model/gemini 实例,提供该模型并以其为键,指定同一模型的树共享一个实例。若工作区的目录中没有 core/ai-model/gemini,则起草一个 <target_namespace>/ai-model/gemini,带有智能体 model 插槽所选择的 model.aggrega.ai/api: gemini 标签,其决策会说明这一点;发布其端点和模型的 Recipe 留给你编写,开头的注释会说明这一点。ADK 以其他任何方式提供的模型——例如 openai/gpt-4o 这样的 LiteLLM 模型字符串、Vertex AI 资源名称,或 claude-sonnet-4-5、gpt-4o 这类 ADK 通过 Anthropic 或 OpenAI 提供的名称——不连接任何对象:智能体的 model 插槽接受的是 Gemini 模型,而智能体不会从其环境中读取模型名称,因此你需要在那里连接一个 Gemini 模型,并在智能体的配置中指定该模型。实例上方的注释和根智能体的决策会指出该模型以及 ADK 为其提供服务所经由的模型系列。由应用代码构建的模型,或未指定模型的树(此时 ADK 使用其默认模型),同样不连接任何对象,实例上方的注释会说明原因。只要模型未连接任何对象,构建就会停止并指出 model 插槽,直到连接了一个模型。在树中其他智能体请求的模型中,ADK 将其请求发送到 Gemini API 的模型不需要各自的连接:ADK 的 Gemini 客户端使用实例连接所提供的密钥发送其请求。应用通过 Gemini API 还是 Vertex AI 访问 Gemini,由其环境决定,而导入不读取环境;智能体的 model 插槽只接受 Gemini API。

该导入器的测试还导入了一个单独的、指定 openai/gpt-4o 的根智能体,其实例起草如下:

spec:
components:
# The agent tree of root_agent.yaml, served from its root agent routed_agent.
# The model connection is left for the author, since the model openai/gpt-4o, which routed_agent names, is one ADK serves through LiteLLM, not through the Gemini API, while core/ai-agent/google-adk takes a Gemini model on its model socket and reads no model name from its environment, so the author wires a Gemini model there and names that model in routed_agent's configuration; the build halts naming the socket until one is wired.
routed-agent:
type: core/ai-agent/google-adk
values:
description: "Answers questions with a model another provider serves."

release.yaml 位于其旁边,是一个同名的草稿 Release,指定该 Aggregate。每个实例的条目将其 infra.image(运行基于 ADK 构建的应用、包含其配置的镜像)写为空,并在其上方加一条说明其含义的注释,由导入将其列为待提供。使用 --target compose 时,条目还会写入 infra.published_port,即 8000,也就是应用监听的端口,其 Compose Recipe 会将它发布在主机的回环地址 127.0.0.1 上,上方的注释说明它只能从本机访问(本机上运行的任何进程都可访问),删除该行即可使服务保持为内部服务;第二棵树会取用下一个空闲端口。在其模型已连接时,条目会将实例向该模型出示的凭据以引用形式(而绝不以值的形式)附加在其 model 连接的 credential 下:没有任何配置为其指定变量,因此它从 GOOGLE_API_KEY 读取,即 Google 的 Gemini API 客户端库读取密钥所用的变量;在除 helm 之外的每个目标上写为 ${…} 引用,在 helm 上写为一个 Kubernetes Secret 的名称,且写为空,由导入将其列为待提供;在 compose 上,model 连接以该键声明它。已连接的模型也有一个条目,不包含任何基础设施,因此 Release 会将其与该实例放置在一起。树中各配置传给其工具和模型请求的值会写在条目上方的注释中,如配置所含的凭据值所述。与每个起草的 Release 一样,它将 metadata.environment 写为 development,并在没有目标时写入一个由导入列为待提供的空 spec.manifest;指定目标时,导入会起草 Manifest,如目标会添加什么所述。

本导入器测试所导入的应用(一个根智能体,引用两个子智能体的配置和一个由代码构建的子智能体),以其目录导入并在 with.sources 下指定这两个配置,在没有任何设置时以其根智能体的名称 tutor_root 起草为:

aggregate.yaml
# Google ADK agent configurations read:
# - root_agent.yaml
# - code_tutor_agent.yaml
# - math_tutor_agent.yaml
# Not read: the application's code, which defines the tools, callbacks and agents a configuration names by their code, nor the environment file ADK's scaffold writes beside root_agent.yaml; the application runs in the image the Release names for each instance, and loads its configurations itself.
# ADK states that its Agent Config is experimental. An agent's model is a Gemini model by default; ADK serves some other providers' models by name through classes of its own, such as claude-sonnet-4-5 and gpt-4o, and others through a LiteLLM model string.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/tutor-root
version: 0.1.0
description: Draft Aggregate imported from a source in the google-adk format.
spec:
components:
# The agent tree of root_agent.yaml, served from its root agent tutor_root.
# Sub-agents ADK builds inside this application, drafted as no instance of their own: code_tutor_agent, math_tutor_agent.
# Not read: a sub-agent of tutor_root, which is built by the application's code at tutor_agents.review_agent, which the import does not read.
# Tools ADK ships, which run inside the application, drafted as no Component: google_search.
# Tools the application's code defines, drafted as no Component: tutor_tools.make_snippet_runner.
# Models other agents of the tree ask for, ...: gemini-pro-latest (math_tutor_agent, served through Gemini).
tutor-root:
type: core/ai-agent/google-adk
values:
description: "Learning assistant that tutors {{`{{`}} students }} in code and math."
uses:
model:
gemini-flash-latest:
target: gemini-flash-latest
# For the compose target only, uncomment the lines below, which declare credential on gemini-flash-latest: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: GOOGLE_API_KEY
# The model gemini-flash-latest.
gemini-flash-latest:
type: core/ai-model/gemini
values:
model: "gemini-flash-latest"

草稿从配置复制到 Aggregate 中的文本,无论在值中还是注释中,都会将每个 {{ 写为 {{`{{`}},即结果为两个花括号的动作,这样描述以及注释中含有两个花括号的名称,在 Aggregate 求值后都会按原样读回。

release.yaml
spec:
aggregate: imported/tutor-root
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The configurations also hand these values to their tools and their model requests, which the application reads from its own configurations, written here for review:
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.api_key: "..."
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.sandbox: "python3.12"
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.timeout_seconds: 20
# math_tutor_agent generate_content_config.http_options.headers: "..."
# math_tutor_agent generate_content_config.http_options.timeout: 30000
tutor-root:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on ADK, holding its configurations
image: ""
uses:
model:
gemini-flash-latest:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential tutor-root presents to gemini-flash-latest on its model connection (the source names no variable for it, so it is read from the one Google's Gemini API's client libraries read the API key from), read from the variable GOOGLE_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${GOOGLE_API_KEY}"
gemini-flash-latest: {}

镜像一经回答,该实例就会被渲染为运行该镜像,并以 GOOGLE_API_KEY 获得凭据,ADK 的 Gemini 客户端会将其发送到 Gemini API;模型则渲染为一个访问 Gemini API 地址的 Service。

配置中包含的凭据值

配置可以把密钥交给工具(在其 args 中),或交给其模型请求(在其 generate_content_config 的 http_options 中)——即请求的标头、地址以及其客户端的参数。工具的 args 中以及这些 HTTP 选项中的每个成员,都按其配置的写法写入 Release 中该实例条目上方的注释里;其中每个文本、对象或列表都可能携带凭据,而 ADK 不将任何一项标记为凭据:默认情况下,每一项都按原样携带,并在 credential-carried 警告中按其智能体和字段命名,例如 tools.tutor_tools.make_snippet_runner.args.api_key,从不按其值命名。当 empty_credentials 设置为 all 时,每一项都写为无值,并以 credential-emptied 报告;为 marked 时,每一项都会被携带,因为 ADK 不标记任何一项。数字或布尔值不携带密钥,按配置的写法写入。ADK 不展开配置中的任何变量引用,因此每个值都按原样读取;环境文件通常保存 ADK 的 Gemini 客户端读取的密钥,但无论设置如何,都从不读取它。

它读取的设置

Google ADK 导入器读取 target_namespace、empty_credentials 和 render_mode,含义如设置所述,不读取其他任何设置。

Agent Framework 导入器

importer/agent-framework 读取 Microsoft Agent Framework 声明式智能体——即基于 Agent Framework 构建的应用从中加载智能体的、kind 为 Prompt 的 YAML 文档——并起草一个 Aggregate,其中包含标准库的 Agent Framework 智能体 core/ai-agent/agent-framework 的一个实例,连接到它所指定的 OpenAI 模型,并在其旁起草一个 Release。它读取声明式智能体,从不读取应用的代码。Agent Framework 以预发布版本的形式发布其声明式智能体软件包。

读取的内容

声明式智能体声明:

  • name、displayName 和 description,其 instructions 以及其输入和 输出的模式;
  • model——模型的 id、为其提供服务的 provider、其客户端发送请求的目标 API (apiType)、其请求的 options,以及其 connection:key 连接向 endpoint 出示一个密钥, 写在 key 或 apiKey 下;remote 连接访问一个 endpoint; reference 连接指定一个由应用解析的连接;anonymous 连接则不出示任何内容;
  • tools——每个工具属于一种 kind:由应用绑定代码的 function,由模型的提供方运行的 web_search、 file_search 或 code_interpreter 工具,或在其 url 处访问的 mcp 服务器, 附带其调用采用的 approvalMode、智能体可调用的该服务器的 allowedTools,以及 它自己的 connection。

写为 =Env.NAME 的成员,仅当应用以 AgentFactory(safe_mode=False)(Agent Framework 自身的安全设置)加载声明式智能体且存在 .NET 运行时时,才由 Agent Framework 从环境变量 NAME 中读取,否则按原样被视为该表达式的文本;其他任何以 = 开头的成员都是由应用计算的表达式。导入器两者都不读取:它按变量命名引用,并将表达式命名为表达式。

单独导入的文件无论名称如何,都作为一个声明式智能体读取;导入器的 with.sources 交给它的每个文件都作为另一个声明式智能体读取,因此一次导入可起草多个:

plugins:
importer:
- uri: importer/agent-framework:<version>
with:
sources:
- ./agents/triage.yaml
- ./agents/writer.yaml

目录从不会交给该导入器:其签名不指定任何文件,因此未指定格式的目录导入不会识别它,而指定 --format agent-framework 的导入会在打开其中任何文件之前以 An importer that declares no file patterns is handed a directory(未声明文件模式的导入器被交给了一个目录) 被拒绝。请改为将每个声明式智能体作为单独的文件导入。Agent Framework 无法从中构建提示智能体的源——其 kind 既不是 Prompt(不区分大小写), 也不是 Agent——会以 no-nodes 报告。应用的代码——加载每个 声明式智能体的程序及其绑定到工具的函数——从不在源之中: 应用会从 Release 指定的镜像中自行加载其声明式智能体。

声明式智能体变成什么

aggregate.yaml 是一个 Aggregate 草稿,按草稿如何命名所述以智能体命名,它为每个声明式智能体包含一个以其名称为键的 core/ai-agent/agent-framework 实例,其中包括:

  • display_name 和 description,即智能体的 displayName 和 description(如果它声明了 这些);
  • 其 model 连接,连接到它指定的模型(如果该模型已连接)。

其指令、输入和输出的模式、模板、元数据以及模型请求的选项 由应用从声明式智能体中读取,并在实例上方的注释中列出。函数工具、由模型的提供方运行的工具以及任何其他 类型的工具也会在注释中列出,并在一个不作任何选择的决策中报告。

provider 为 OpenAI 且指定了 id 的模型是 core/ai-model/openai 的一个实例, 提供该 id 的服务并以其为键:智能体的 model 插槽接受提供 OpenAI API 的模型, 运行时会通过 Agent Framework 的 OpenAI 客户端读取的变量交付该模型的地址、名称和密钥。在同一地址指定同一模型的智能体共享一个实例。如果工作区的目录 中没有 core/ai-model/openai,则会起草一个 <target_namespace>/ai-model/openai,带有 智能体的 model 插槽所选择的 model.aggrega.ai/api: openai 标签,其决策会说明这一点;发布其端点和模型的 Recipe 留给你编写,开头的注释会说明。以引用形式写出的 id 会将模型的 values.model 留给你,模型上方的注释会指出该 变量;在设置之前,构建会停止并指出它。anonymous 连接写为 连接的 unauthenticated: true。任何其他提供方的模型——AzureOpenAI、Anthropic——以引用形式指定提供方或未指定提供方的模型(此时 Agent Framework 使用应用设置的默认提供方),以及未指定 id 的模型,都不连接到任何内容,实例上方的注释会说明原因;在连接一个模型之前,构建会停止并指出 model 插槽。

kind 为 mcp 的工具既不会被起草为 Component,也不会被起草为连接:Agent Framework 将该服务器作为托管工具发送给模型的提供方,由提供方而非应用通过其 url 访问它,因此该地址必须可从提供方访问,草稿部署的任何内容都不会访问它。智能体实例上方的注释会列出该服务器,说明这一点,并列出声明式智能体为其声明的描述、approvalMode 和 allowedTools;其 url 会完整写入 Release 中该智能体条目上方的注释,其决策不做任何选择。

其旁边的 release.yaml 是一个同名的 Release 草稿,指向该 Aggregate。智能体的条目将其 infra.image(运行基于 Agent Framework 构建的应用的镜像,其中包含其声明式智能体)写为空,并在其上方加一条说明其含义的注释,由导入将其列为待提供。使用 --target compose 时,该条目还会写入 infra.published_port 为 8000,即 Component 的 infra.port 默认为该应用指定的端口,其 Compose Recipe 将其发布在主机的回环地址 127.0.0.1 上,上方有注释说明该服务只能从本机访问,本机上运行的任何进程都可以访问,并且删除该行会使服务保持为内部服务。在其模型已连接时,条目会将智能体向该模型出示的凭据以引用形式(而绝不以值的形式)附加在其 model 连接的 credential 下:从声明式智能体为其密钥指定的变量(写作 =Env.NAME)读取,否则从 OPENAI_API_KEY 读取,即 OpenAI 客户端库读取密钥所用的变量;在除 helm 之外的每个目标上写为 ${…} 引用,在 helm 上写为一个 Kubernetes Secret 的名称,且写为空,由导入将其列为待提供;在 compose 上,model 连接以该键声明它。声明式智能体为其模型和 MCP 服务器声明的值——各个密钥以及每个服务器的 url——写在智能体条目上方的注释中,如声明式智能体中包含的凭据值所述。每个已连接的模型都有一个条目,因此 Release 会将其与智能体放置在一起。其连接所声明的端点写为模型的 infra.endpoint,以引用形式写出的端点会在其条目旁列出,在设置之前使用 Component 自身的地址;未声明端点的连接会使该条目不包含任何基础设施,Component 自身的地址保持有效。与每个起草的 Release 一样,它将 metadata.environment 写为 development,并在没有目标时写入一个由导入列为待提供的空 spec.manifest;指定目标时,导入会起草 Manifest,如目标会添加什么所述。

该导入器的测试所导入的声明式智能体——使用 OpenAI 提供方和密钥连接,带有一个出示自己密钥的 MCP 服务器、一个函数工具和一个网页搜索,作为单独的文件导入——在没有任何设置的情况下以其 name,即 LearnAgent,起草为:

aggregate.yaml
# Not read: the application's code, which loads each declarative agent and binds the functions of its function tools; the application runs in the image the Release names for each instance, and loads its declarative agents itself.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/learnagent
version: 0.1.0
description: Draft Aggregate imported from a source in the agent-framework format.
spec:
components:
# The declarative agent LearnAgent.
# Read by the application from the declarative agent, and taken by no key of core/ai-agent/agent-framework: instructions, outputSchema, the options of its model requests (temperature, topP).
# Function tools, whose code the application binds, drafted as no Component: GetRelease.
# Tools the model's provider runs, drafted as no Component: search.
# The MCP server microsoft_learn, drafted as no Component and no connection, since Agent Framework sends it to the model's provider as a hosted tool, and the provider, not the application, reaches it at its url, which must therefore be reachable from the provider; its url is written above learnagent's entry in the Release.
# Stated by the declarative agent for microsoft_learn: its description, "Get information from Microsoft Learn."; its approval mode, never; the tools of the server it allows, microsoft_docs_search, microsoft_docs_fetch.
learnagent:
type: core/ai-agent/agent-framework
values:
display_name: "Learn Assistant"
description: "Answers questions about {{`{{`}} product }} from the Microsoft Learn content."
uses:
model:
gpt-4-1-mini:
target: gpt-4-1-mini
# For the compose target only, uncomment the lines below, which declare credential on gpt-4-1-mini: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# The model gpt-4.1-mini, which LearnAgent names with the OpenAI provider.
gpt-4-1-mini:
type: core/ai-model/openai
values:
model: "gpt-4.1-mini"

草稿从声明式智能体复制到 Aggregate 中的文本(无论在值中还是在注释中)会将 每个 {{ 写为 {{`{{`}},以便在 Aggregate 求值后按原样读回。

release.yaml
spec:
aggregate: imported/learnagent
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The declarative agent also states these values for its model and its MCP servers, written here for review:
# - model.connection.key: "..."
# - tools.microsoft_learn.url: "https://learn.microsoft.com/api/mcp?session=..."
# - tools.microsoft_learn.connection.key: "..."
learnagent:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on Agent Framework, holding its declarative agent
image: ""
uses:
model:
gpt-4-1-mini:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential learnagent presents to gpt-4-1-mini on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
gpt-4-1-mini:
infra:
endpoint: "https://llm-gateway.example.com/v1"

镜像一经回答,智能体就会被渲染为运行该镜像,并获得以 OPENAI_BASE_URL 提供的模型端点、以 OPENAI_MODEL 提供的模型 id 以及以 OPENAI_API_KEY 提供的凭据,模型则被渲染为访问其主机的 Service。没有任何变量携带 MCP 服务器的地址:访问它的是模型的提供方,而不是应用。

声明式智能体持有的凭据值

key 连接所提供的密钥(写在 key 或 apiKey 下,位于模型或某个 MCP 服务器上)是 Agent Framework 唯一标记为凭据的成员:它是其加载器在日志中唯一脱敏的值。声明式智能体以字面量写出的每个密钥,都会按声明式智能体的写法写入 Release 中该智能体条目上方的注释,并且默认按原样携带,在 credential-carried 警告中以其智能体和字段(例如 model.connection.key)指明,而绝不以其值指明。MCP 服务器的 url 完整写在同一注释中,并以其字段指明(例如 tools.microsoft_learn.url of node LearnAgent is carried as written),它是 MCP 服务器配置的成员;而已连接模型的端点是 Agent Framework 标记为非凭据的输入。当 empty_credentials 设置为 marked 时,密钥和 MCP 服务器的 url 都写为无值(注释仅以字段指明每一项),并以 credential-emptied 报告,而模型的端点照常携带;为 all 时,模型的 infra.endpoint 也被省略,在其条目上方的注释中注明留给 Release 设置,在设置之前使用 Component 的默认地址。写作 =Env.NAME 的值不持有任何值,因此无论设置如何,都以其变量指明,并附上 Agent Framework 从环境中读取它的条件(例如 model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads …),且不以上述任一代码报告;写作其他任何表达式的值则作为表达式指明,绝不写出。

它读取的设置

Agent Framework 导入器读取 target_namespace、empty_credentials 和 render_mode,如设置中所述,不读取其他任何设置。

目标会添加什么

指定了目标的导入(aggrega import 上的 --target,或助手导入工具上的 target 及会话的 aggrega/import 方法,命名一个 provider 能力,例如 compose 或 helm)会将该目标交给导入器,因此导入器会为该目标起草:每个机密都采用该目标读取的形式,仅该目标需要的行会以生效状态写入,而仅其他目标需要的行则会省略。在 compose 上,凡是导入器在主机回环地址上发布服务之处,这些行都包括 infra.published_port,如各导入器的章节所述;导入器选择的端口绝不会占用 Release 中另一个端口已占用的端口号。随后,无论运行的是哪个导入器,导入都会在导入器起草的内容旁边起草 Manifest:manifest.yaml,位于起草的 Release 旁边,其命名和版本与该 Release 相同(若导入器未起草 Release,则位于起草的 Aggregate 旁边,其命名和版本与该 Aggregate 相同)。

对于草稿所需的每种组件类型和每种 feature 类型(包括起草的 Aggregate 的组件、其连接及其子系统上的类型,它所组合的目录 Aggregates(例如 core/dify)上的类型,以及起草的 Release 的附加项上的类型),Manifest 会将该类型映射到工作区目录为其提供的、属于该能力的 Recipe(对于 feature 类型则为 feature recipe):即唯一存在的那一个,同一 Recipe 的多个版本算作一个;或者,若存在多个名称不同的,则为以该类型本身命名的那一个,例如 core/datastore/postgres 对应 helm/postgres。没有任何此类 Recipe,或有多个但均未以此命名的类型,将保持未映射状态,并由一条警告指出该类型及原因;构建这些草稿时会停止并列出该类型的每个实例或附加项,直到你为其建立映射。

当只有导入器知道多个 Recipes 中哪一个适用时,它会自行起草 Manifest(MCP 导入器按键将每个服务器映射到该服务器运行方式的实现,按名称附加机密的导入器则将 core/referenced-secret 映射到 helm/k8s-existing-secret),再由导入将其补全:导入器所写的、目录为该类型和该能力提供的每个映射都会保留,其他映射则会被丢弃并给出警告,它留下的类型按上文所述进行映射。

起草的 Release 的 spec.manifest 在没有目标时写为空,此时会被设置为 Manifest 的名称,其上方的注释会被删除,Release 中的其他内容均不变。aggrega import 对此有完整说明。

设置

导入器会收到挂载它的 plugins.importer 条目在 with.settings 下的设置,如 Which importer turns a source into drafts 所述。没有条目或没有设置时,每项设置都取其默认值。

plugins:
importer:
- uri: importer/langflow:<version>
with:
settings:
target_namespace: payments
reuse_mode: hints-only
设置默认值功能说明
target_namespaceimported起草的实体所在的命名空间:Component 为 <target_namespace>/<category>/<name>,Aggregate 和 Release 为 <target_namespace>/<name>;其中 <name> 为源自身的名称,若没有,则为其目录的名称或其文件去掉扩展名后的名称,若仍没有,则为 flow,以小写书写,且每一段由 ASCII 字母和数字以外的字符组成的连续字符都写为一个连字符,详见草稿如何命名。
reuse_modeauto-apply-above-threshold对于草稿为其提供独立 Component、且匹配处于高等级并得分不低于 reuse_threshold 的节点,auto-apply-above-threshold 会引用最佳匹配的目录 Component,其余节点则起草。hints-only 会起草每个此类节点,不引用任何目录 Component,并将强匹配记录为提示。其他任何值均按 hints-only 处理。
reuse_threshold0.85auto-apply-above-threshold 引用 Component 所需的最低得分。仅在该模式下读取;0 按默认值处理。
emit_hintstrue对于高等级或中等级匹配,起草的 Component 文件是否以一条注释开头,注明其相似的目录 Component。草稿 Aggregate 在该节点条目上方带有同样的注释;在被引用的条目上方,则带有一条注释,注明可替换的次佳候选,或说明没有候选得分高于零。false 不写这些注释。
render_modehumanhuman 写入上述草稿。llm 不写草稿,而是将完整的决策记录——每个节点、权衡过的候选以及所做的选择——写成一个文档 import-decisions.json,供其他工具读取。其他任何值均按 human 处理。
mapping_overrides无叠加在导入器自身映射表之上的映射,先按格式、再按节点类型作为键——对于 Compose 导入器,按镜像仓库。每个条目注明该类型节点映射到的 component,并可选地注明其 category、匹配的 Component 所带的 traits(标签及其值),以及其名称所含的 vendor 词。对映射表已映射的节点类型,条目会取代表中的对应行。只读取正在导入的格式下的条目。
layoutplatformplatform 起草运行该流程的平台,由平台承载流程,流程的每个部分都是一个独立的 Component 并连接到平台,如 The platform carrying the flow 所述。nodes 将每个节点起草为独立的 Component,如 Node by node 所述。对于 Dify 导入器,platform 起草承载应用的 Dify 安装,如 What an application becomes 所述。其他任何值均按 platform 起草,并且导入会给出 unknown-layout 警告。
empty_credentialsnone指定哪些凭据值被写为空:平台承载的流程中的凭据值,如 Credential values the flow holds 所列;MCP 导入器起草的 Release 中的,如 Credential values a server holds 所列;Compose 导入器起草的 Release 中的,如 Credential values a service holds 所列;Dify 导入器承载的应用中的,如 Credential values an application holds 所列;CrewAI 导入器起草的 Release 中的,如 Credential values a declaration holds 所列;LangGraph 导入器起草的 Release 中的,如 The environment a configuration states 所列;Google ADK 导入器起草的 Release 中的,如 Credential values a configuration holds 所列;以及 Agent Framework 导入器起草的 Release 中的,如 Credential values a declarative agent holds 所列。none 不将任何值写为空:每个值都按原样承载,并在 credential-carried 警告中注明。marked 将格式标记为凭据的内容以及 MCP 服务器配置的每个成员写为空。all 还会将格式未标记为凭据但可能承载凭据的输入写为空——请求头、查询参数、以命令行形式写出的请求、以密钥命名的输入。草稿为使节点连接到其连接而写入的内容,无论此设置如何都会写入。其他任何值都会使导入停止,不起草任何内容,并给出 unknown-empty-credentials。逐节点起草的草稿不读取任何值,因此也不读取此设置。
attach_egress_allowlistfalsetrue 将标准库的 core/egress-allowlist Feature 以 egress-allowlist 的形式挂载到草稿写入的每个平台实例上,不设置其任何 infra,如 What the draft leaves for the Release 所述。false 不挂载任何内容。在 layout: nodes 下不写平台的草稿,以及 Dify 导入器的草稿(其 Dify 安装条目不接受 Feature),无论此设置如何都不挂载任何内容;若设置为 true,导入会给出 feature-not-attached 警告。任何非布尔值均按 false 处理。

导入器不认识的设置会被忽略。

with:
settings:
mapping_overrides:
langflow:
AzureOpenAIModel:
component: acme/ai-model/azure-openai
category: ai-model
vendor: azure

导入报告的内容

每个核心导入器都会以诊断的形式报告它未能完成的事项,以及它代表作者完成的事项。命令会在每个节点对应的行之前,将每条诊断以 <severity>: <message> 的形式打印到标准错误;编辑器会话的 aggrega/import 方法和助手的 import 工具还会连同其 code 一起返回每条诊断。

代码严重级别报告时机
parse-failedhalt源无法解析:其解析器拒绝了它,消息中带有解析器给出的原因。
no-nodeswarn源中没有导入器能识别的节点——对 MCP 导入器而言,没有服务器;对 Compose 导入器而言,没有服务也没有模型;对 CrewAI 导入器而言,crew 未声明任何 agent;对 LangGraph 导入器而言,配置未声明任何图;对 Google ADK 导入器而言,根配置未声明任何 agent,或 with.sources 交给导入的每个文件都不含根配置;对 Agent Framework 导入器而言,源未声明任何 prompt agent。
unknown-layoutwarnlayout 既不是 platform 也不是 nodes;流程按 platform 起草。
unknown-empty-credentialshaltempty_credentials 的值不是 none、marked 或 all,诊断会指明该设置;导入不起草任何内容。
platform-not-in-catalogwarn工作区的目录中没有与平台同名的 Component,因此没有任何部分连接到它;对 Dify 导入器而言,是没有 core/ai-agent/dify,但 core/dify 仍会照常组合。
part-not-placedwarn流程的某个部分未连接到平台的任何插槽,并说明原因;该部分保留在流程中。
socket-selector-unreadablewarn平台某个插槽声明的选择器无法读取,因此没有任何部分连接到它;每个插槽报告一次。
credential-carriedwarn某个凭据值在草稿所承载的流程中,或在 MCP、Compose、CrewAI、LangGraph、Google ADK 或 Agent Framework 导入器起草的 Release 中按原样承载;诊断以其节点(或其服务器、服务、agent 或配置)及其字段指明该值,绝不显示值本身,并给出会将其写为空的 empty_credentials 值。
credential-emptiedwarn某个凭据值在草稿所承载的流程中,或在 MCP、Compose、CrewAI、LangGraph、Google ADK 或 Agent Framework 导入器起草的 Release 中,按 empty_credentials 的要求被写为空;诊断以其节点(或其服务器、服务、agent 或配置)及其字段指明该值。
carriage-returns-rewrittenwarn流程中的回车符被写为换行符,并给出数量。
definition-respelledwarn流程的值会以平台自身工具读取它们时的写法写出,值本身不变,并说明是哪些值以及原因:Langflow 流程的边句柄,按 Langflow 编辑器的写法写出。草稿为使流程到达某个部件而写入的值,或可能携带凭据的值,绝不会改写——它保持为连线所写的值,或 empty_credentials 所决定的值——警告会统计每个未改写的值。
definition-not-carriedwarn流程未承载于 values.flow_definition 中,或 Dify 导入器的应用未承载于 parameters.app_definition 中,并说明原因。
part-reads-connectionwarn流程如何通过连接到达某个已连接的部分,或者某个连接如何按原样到达草稿未连接到任何插槽的节点。
part-address-in-flowwarn流程通过连接以外的方式到达某个已连接的部分,并说明方式。
model-not-namedwarn被引用部分的 values.model 留给作者填写,并说明原因。
feature-attachedinfoattach_egress_allowlist 已将 core/egress-allowlist 附加到起草的平台,并说明 Release 设置了其中哪些内容;每个平台实例报告一次。
feature-not-attachedwarnattach_egress_allowlist 为 true,但草稿未写入任何平台,或组合的是 Dify 安装(其条目不接受 Feature),因此未附加任何内容。
part-configured-in-platformwarnDify 应用的某个节点指明的是 Dify 自行配置的内容——模型及其提供方、工具、知识库、agent 策略、插件——因此草稿不为其连接任何部分。
dsl-version-newerwarnDify 应用所用的 DSL 版本比 core/ai-agent/dify 默认运行的 Dify 版本所写的 DSL 版本更新。

指定了目标的导入会在导入器的诊断之后报告起草 Manifest 时的发现:一条 warn,指明 Manifest 未映射的每种组件类型或 feature 类型及原因;以及一条 info,在起草的 Release 已指定某个 Manifest,或没有任何起草的 Release 引用它时报告。这些属于导入本身而非导入器,不带代码;目标会添加什么对其进行了说明。随后,每次导入还会以其自身的名义,为草稿仍待提供的每个值报告一条 warn,指出起草的文件、键路径及其描述;在 --offline 下,若起草了 Release 且没有待提供的值,则报告一条 info,指出接下来要运行的 aggrega pull,如导入答案文件所述。

随每个编译器版本发布

每个编译器版本都会从打了标签的源码构建这十个导入器,并从导入器本身生成它们的 Plugin 实体,因此实体的能力、识别特征、宿主 函数和描述都与其导入器报告的一致。该版本会以其版本号对全部十个导入器进行签名和发布,即 importer/langflow、importer/flowise、importer/n8n、importer/mcp、importer/compose、importer/dify、importer/crewai、importer/langgraph、importer/google-adk 和 importer/agent-framework,与其他 核心插件一同发布,并将它们的实体与其他核心插件的实体一起记录到标准 目录中。