Activepieces 架构决策解读Agent 是项目作用域的数据行Flow 步骤对其进行实时引用【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces本篇文章解读 Activepieces 仓库内的一份架构决策记录 000027-an-agent-is-a-project-scoped-row-that-flow-steps-reference-live.md深入剖析Agent智能体以项目作用域的数据行形式存在、Flow 步骤通过agentId实时引用其配置这一核心设计。通过阅读本文你将理解 Agent 行的字段结构、Run Agent 步骤如何做到改一处配置、所有引用它的流程下次运行自动生效且无需重新发布、Detach customise快照机制的工作方式以及该决策在无人值守授权、跨项目迁移、审计与运行来源AgentRunSource等方面带来的影响与权衡。决策概述Live Reference而非快照决策文档给出的核心结论非常简洁而关键一个agent行持有 instructions指令、tools工具、model模型、max steps最大步数和 structured output结构化输出。Run Agent 步骤只存储agentId服务端在运行开始时解析配置——因此编辑一个 Agent 会改变所有引用它的流程的下一次运行结果且无需重新发布。对于需要差异化的步骤Detach customise分离并定制会将配置内联复制一份并清除agentId。也就是说Agent 与流程之间是实时引用live reference关系而非发布时快照snapshot关系。这是 Activepieces 中 Agent 功能与常见下拉框预填步骤配置方案的根本分水岭。数据模型agent 行的字段与索引决策文档声明 Agent 是项目作用域的行project-scoped row。这一表述在源码中有完整的实体映射见 agent-entity.ts实体表名为agent核心字段如下字段类型说明projectIdApId非空项目作用域的直接体现所有 Agent 行隶属于某个项目并带有级联删除外键onDelete: CASCADEownerIdApId非空创建者用户多对一关联user表externalIdString非空供跨环境/项目状态同步upsert使用的稳定外部标识是从第一天起就有的字段displayNameString非空Agent 显示名称descriptionString可空Agent 描述icon/colorString非空界面展示用图标与颜色visibilityString非空可见性如私有/共享sharedWithUserIdsString 数组默认{}显式共享给的用户 ID 列表draftjsonb非空草稿配置instructions、tools、model、max steps、structured output 等publishedjsonb可空已发布配置可空说明允许存在有草稿未发布的状态实体上定义了两个索引恰好对应决策文档强调的两个关键点idx_agent_project_created_id按(projectId, created, id)排序支撑项目内按时间列出 Agent的列表查询idx_agent_project_external_id(projectId, externalId)上的唯一索引直接支撑决策文档中项目状态必须按(projectId, externalId)upsert Agent的要求——这是跨项目迁移与 git sync 场景下的稳定锚点。运行机制步骤只存 agentId配置在运行开始解析决策文档称服务端在运行开始时解析配置其背后的支撑点有两个1. 运行时本来就从 job payload 读取工具而不是从 flow version 读取。Agent 运行被建模为ExecuteAgentRunJobData见 job-data.ts其结构直接承载了解析后的运行配置jobType: EXECUTE_AGENT_RUN、conversationId、flowRunId、waitpointId等运行上下文source: AgentRunSource可选——即下文将详述的第三个 AgentRunSourcetools: AgentTool[]与flowTools: ResolvedAgentFlowTool[]——工具在入队时已解析好放进载荷structuredOutput、maxSteps、provider、providerConfigId、modelName、promptOverride、dryRun等。由于 worker 消费的是这份解析后的 payload而 payload 在运行开始时由服务端生成所以 Agent 配置的修改自然只影响下一次运行完全不需要改动 worker 侧的解析逻辑——正如决策文档所说live reference costs no worker change实时引用不产生任何 worker 改动。2.flow_version.agentIds与extractAgentIds是现成的存量设施。flow_version表上本就存在agentIds数组列相关迁移可见 1753641361099-AddExternalIdToAgentId.ts它源自 2025 年被删除的旧 agents 模块如今被保留并继续使用。在每次 flow version 变更落库时服务端会同步重算这一列见 flow-version.service.tsmutatedFlowVersion.connectionIds flowStructureUtil.extractConnectionIds(mutatedFlowVersion) mutatedFlowVersion.agentIds flowStructureUtil.extractAgentIds(mutatedFlowVersion)与connectionIds并列地维护agentIds意味着哪些流程正在使用这个 Agent这一反查能力是免费获得的——agentIds列就是反向索引。源码中确实存在利用该列的反查查询flow.service.ts 使用latest_version.agentIds :agentExternalIds来按 Agent 外部 ID 匹配流程版本。这也正是编辑器里Used in N flows用于 N 个流程提示的数据来源。项目作用域跟随工具解析决策文档强调项目作用域是跟随工具的——flow tools 按projectId解析connections 按ArrayContains([projectId])匹配。也就是说如果 Agent 被设计为平台作用域platform-scoped反而需要在行内重新实现一套项目作用域逻辑保持项目作用域则可以直接复用既有工具与连接解析链路。Why为什么必须是实时引用而不是快照决策文档用一句话点明设计动机命名一个 Agent 的意义在于改进它一次improve it once。快照会让每个流程各自漂移把把 Agent 做得更好重新变成逐个流程的手工编辑——而这正是该功能想要消除的痛苦。被否决的替代方案正是典型的快照式交互下拉框把配置预填进步骤链接随即消失。这样做的直接后果是你修正了 Agent 的指令或更换了模型所有已经复制过配置的流程仍然停留在旧配置上除非逐个打开重新编辑。实时引用则保证了单一事实来源single source of truth一处编辑处处生效。影响与权衡Consequences1. 无人值守授权的语义随之扩大决策 000024000024-configuring-an-agent-step-tool-authorises-the-action-not-its-arguments.md确立过在 Agent 步骤上配置一个工具即视为授权其无人值守运行由于步骤现在只引用agentId这份授权从步骤转移到了 Agent 行本身——一旦有人能编辑 Agent就等于能影响所有引用它的流程的无人值守行为。因此决策文档明确了配套治理措施编辑 Agent 被视为编辑他人发布的流程以WRITE_AGENT权限门控。源码中该权限在 agent-controller.ts 中多处使用涉及创建、更新、删除、移动等写操作并且在 agent-tools.ts 中作为 Agent 工具的运行时授权检查依据工具名不同时分别要求READ_AGENT或WRITE_AGENT编辑操作写入审计日志audit-logged编辑器在保存前展示 Used in N flows让编辑者明确知晓影响面若实践中授权过宽演进方向是增加每 Agent 的 allow unattended writes允许无人值守写入开关而不是回头重新讨论引用机制本身。2. 跨项目移动会破坏链接externalId 从第一天起就存在由于 Agent ID 是项目局部的project-local把流程从一个项目移动到另一个项目会打破链接而 git sync 会携带 connections 却不会携带 agents。为此agent行从第一天起就包含externalId实体中的唯一索引(projectId, externalId)已证实项目状态project state在恢复时必须按(projectId, externalId)对 Agent 做 upsert在项目状态真正支持 upsert Agent 之前导入流程必须大声失败fail loudly而不是静默丢失引用。3. 清理孤儿表breaking true2025 年旧模块遗留的两张孤儿表agent、agent_run被删除以便新实体可以使用agent这个理所应当的表名。为保证回滚安全该变更标记breaking true且未使用⛓️ breaking-change标签。这也解释了为什么上文实体与枚举中出现的是全新的表结构与运行模型——它们是在清场之后重新落地的。4. Autonomy 依然是 Flow调度不是 Agent 的专属能力按计划运行Run on a schedule并不是在 Agent 行上加一个 cron 字段而是搭建一个真正的流程其中包含一个链接到该 Agent 的步骤。这样保证整个系统只有一套执行模型、一条可观测链路——Agent 的自主运行与普通流程共享相同的运行、重试、日志与监控路径。5. 与 Agent 对话是第三个 AgentRunSource决策文档特别指出与 Agent 聊天是第三个AgentRunSource而不是nullable-agentId检查。源码中AgentRunSource枚举定义于 job-data.tsexport enum AgentRunSource { CHAT CHAT, FLOW_STEP FLOW_STEP, AGENT AGENT, AGENT_BUILDER AGENT_BUILDER, }对应关系如下取值含义FLOW_STEP流程中的 Run Agent 步骤无人值守路径AGENT直接与某个 Agent 对话本决策新增的第三条路径CHAT通用聊天AGENT_BUILDERAgent 构建器内的试运行之所以用显式枚举值而非agentId是否为空来区分是因为每一个门控gate本来就按source分支——运行来源是既有的、统一的判别维度同时它让Agent 对话天然地从 Chat 列表中排除agent-conversation-entity.ts 中对话的source默认值为CHAT列表查询也按source过滤无需额外的清理逻辑。更重要的是受信语义的差异与流程步骤无人值守不同与 Agent 对话是有人值守attended的——taint污点标记从false开始且审批流程不得自动拒绝approval must not auto-decline。这保证了聊天场景下用户可以自然地介入确认而不会被自动化安全策略误伤。相关决策与延伸阅读本决策的上游依赖000024-configuring-an-agent-step-tool-authorises-the-action-not-its-arguments.md工具配置即无人值守授权决策文档目录index.mdAgent 模块的完整实现位于 packages/server/api/src/app/ee/agent其中 agent-entity.ts 定义行结构、agent-controller.ts 定义带权限门控的 API、agent-conversation-service.ts 管理对话与来源分支运行载荷契约含AgentRunSource与ExecuteAgentRunJobData位于 job-data.ts。总结本决策的核心价值在于把 Agent 变成项目内可复用、可集中改进的活配置行而非固化在流程版本里的快照。通过步骤只存agentId 运行开始解析 flow_version.agentIds反向索引的组合Activepieces 在不改动 worker 的前提下获得了一处编辑、处处生效的能力同时用Detach customise保留了个别步骤差异化的出口而externalId、WRITE_AGENT权限、审计日志、AgentRunSource枚举与breaking true的迁移策略则把这一灵活性的代价授权扩大、跨项目断链、运行语义区分逐一显式地治理起来。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
