Builder.io Agent-Native 架构解构：一份能力契约，六个接入面

背景：聊天框之外，还缺一块「看得见的手」

过去两年，把智能体接进一个已有产品的主流做法是加一个聊天侧栏：左边是原来的界面，右边是能回答问题的对话窗口。这个做法上手快，但留下了两个长期问题。

其一，能力被实现了两遍。界面里有一套改颜色、改优先级、改归属人的业务逻辑，智能体那侧为了能干活，往往要再包一层工具接口。两处实现一旦不同步，同一句请求经由人和经由智能体会得到不同结果——校验规则在界面加了、在工具侧忘了，或者智能体能改到界面上根本不允许人改的字段。

其二，纯对话缺少状态表达。改一个配色、调一个参数这类「看得见、需要反复微调」的工作，用对话做意味着每次调整都要写一句提示、等一轮推理、付一次 token，还要再确认别的地方没被动到。Builder.io 在发布文中把这件事说得很直接：改一个颜色不该等于写一次提示词、等一轮智能体、付一次 token、再检查一遍别的东西有没有变。

Agent-Native 给出的答案不是「把侧栏做得更好」，而是换一个结构：智能体不是挂在应用上的附件，而是和界面并列的另一类客户端。两者消费同一批能力契约，写入同一份数据，读同一份应用状态。

三块地基：共享动作、共享数据、共享应用状态

官方把智能体与界面的连接拆成三块地基。三块各有明确的职责，缺任何一块，「智能体与应用是一体的」这句话都落不到工程上。

地基	官方表述要点	解决的具体问题	工程上的新增要求
共享动作	能力只定义一次，智能体作为工具调用，界面从应用代码调用，两条路径共用校验、权限与实现	能力被实现两遍导致的行为分叉	动作定义要有窄输入 schema、身份与授权、租户边界
共享数据	智能体的产出直接出现在界面，人在界面上的改动对智能体可见	为了喂给对话而另建一份「智能体记忆副本」	仍需数据库约束、事务与冲突处理，共享模型不免除这些责任
共享应用状态	智能体知道当前页面、选中记录、活动视图	「改这个」这类指代缺少落地依据	状态是便利性而非授权依据，不能替代权限校验

值得单独说明的是第三块。共享应用状态让「把这段总结一下」这类短指令可以指向界面上已经打开的那条记录，而不必让用户再粘贴一次编号或重复描述一遍是哪一个。这是一个明显降低摩擦的设计，但它同时引入了一个容易被忽略的边界：用户当前选中了什么，说明用户正在讨论什么，并不说明用户有权让智能体对它做什么。权限判定仍然必须由服务端从调用者身份推导或校验，而不是从界面状态推断。

三块地基叠加之后，智能体与界面的关系是并列的：界面上能做的事，智能体也能做；智能体做完的事，界面上立刻可见。官方把这个形态命名为「智能体应用」（agentic app）——自带应用的智能体，而不是给人类产品补一个侧栏。

一份契约，六个接入面

动作定义一次之后，Agent-Native 把它同时投射到六个面。这是这次发布里被讨论最多的部分，也是其架构主张的集中体现。

接入面	谁在调用	带来的能力	对动作定义的额外约束
UI	应用界面代码	人在界面上直接操作	需要可交互、可回退的表现层
Agent	智能体作为工具调用	用自然语言驱动同一批能力	需要模型可读的名称、描述与窄参数
HTTP API	外部系统	被其它服务集成	需要稳定的版本与错误语义
CLI	命令行与脚本	无界面环境下的批处理	需要可组合、可脚本化的输入输出
MCP	Claude、ChatGPT、Cursor、Codex 等宿主	外部智能体直接调用本应用能力	需要符合 MCP 的服务端暴露方式
A2A	其它智能体	任务在智能体之间委派与回传	需要可被外部智能体理解的语义与边界

六个面共享同一个动作图，意味着一次能力定义的收益被放大了六倍，代价是动作定义的责任也放大了六倍。一个在界面上只是「点一下按钮」的操作，一旦同时是 MCP 工具和 A2A 端点，就需要回答：外部智能体能不能触发、触发了算谁的、要不要人审批、怎么记进审计日志。框架提供的是投射机制，这些判断仍然是产品与安全决策。

与计算机操控型智能体的路线差异

把 Agent-Native 与当前另一条主流路线——计算机操控（computer-use）——放在一起，差异最清楚。后者让智能体像人一样看屏幕、决定点哪里、操作、再看结果，逐步推进。这条路通用性强，不需要应用配合，但慢且消耗 token，而且对界面改动的容忍度低。

维度	Agent-Native 共享动作	计算机操控型智能体	聊天侧栏加独立工具集
调用方式	直接调用界面使用的同一批动作	通过像素识别与模拟输入操作界面	调用为智能体单独封装的工具
是否需要显示屏	不需要，可从 Slack、定时任务或其它智能体触发	需要，依赖屏幕会话	不需要
token 与时间开销	官方称更少、更快，未给出量化基准	官方口径为慢且 token 密集	取决于工具设计
前置改造成本	高，需把能力重构为动作	低，无需应用配合	中，需维护第二套工具
行为一致性风险	低，两条路径共用实现	中，界面改动会打断流程	高，两套实现易分叉
典型失效模式	动作边界设计不当导致越权	视觉解析失败、流程中断	人与智能体行为不一致

三者的取舍相当清晰：Agent-Native 用较高的前置重构成本，换运行时的效率与一致性；计算机操控用运行时的低效，换接入成本的低门槛；聊天侧栏加独立工具是当前最常见的折中，代价是长期的一致性债。对已经有清晰业务对象与操作边界的应用（看板、表单、内容系统、设计工具），前者的账算得过来；对无法改造的存量封闭系统，后两者仍是现实选择。

团队原语：指令、技能、记忆与子智能体

除了动作层，Beta 还打包了一批面向团队而非个人的应用基础设施：共享指令、技能与记忆，认证、权限、组织与团队、数据存储、多租户与实时同步。几个点值得单独记下：

• 共享与个人分层的记忆：指令与技能可在团队内共享，同时每人保留自己的偏好与记忆。有人改进了一个共享技能，全队受益——这比「每人一套提示词」的做法更容易沉淀。
• 变更来源可辨：历史记录能区分一处改动来自本人、同事还是智能体。这在多人协作加智能体的场景里是刚需，也是审计的起点。
• 敏感动作需人审批：官方提到可以对敏感步骤要求批准。结合共享动作的设计，这意味着审批点应该挂在动作定义上，而不是挂在某个界面按钮或某个工具上——否则六个面里总有几个绕过它。
• 子智能体与定时/事件触发：可以为专门工作配置子智能体，各自有独立的会话、指令与工具；也可以按计划或事件触发，触发条件用自然语言书写。后者在工程上是个便利，但也意味着触发逻辑的可读性依赖提示词质量。

可选的 Toolkit 提供富文本编辑器、画布控件、实时在线状态、共享与评论、版本历史、撤销与恢复、设置与导航等组件。官方用 Clips（屏幕录制与分享）、Slides（演示文稿）、Design（设计与原型）三个自建应用作为参考实现，三者均已开源。参考实现开源这件事对评估有价值：可以直接读代码判断框架的实际复杂度，而不是只看文档示例。

模型与部署：可替换的边界在哪里

模型侧，Agent-Native 支持自带 Anthropic、OpenAI、Google Gemini、OpenRouter 或任意 OpenAI 兼容端点的密钥，也可以用 Ollama 跑本地模型，或使用 Builder.io 的托管连接。官方明确表述：切换模型不需要改动动作、数据与界面。这个承诺的成立前提是动作层与模型层确实解耦——从架构看，模型只负责决定调用哪个动作、传什么参数，动作本身是确定性的业务代码，因此这个前提在设计上是成立的。

部署侧，本地工程用 npx @agent-native/core@latest create 初始化，代码留在自己的仓库，接任意 PostgreSQL（官方举例 Neon、Supabase），可部署到 Node、Vercel、Netlify、Cloudflare 或 AWS。已有 React 应用可以在不重写的前提下加一个智能体面板。这条路径值得强调：它把「存量应用渐进接入」列为了支持场景，而不是只支持从零搭建。

从公开仓库结构还能读出几个工程细节：数据层做了多方言适配，按连接串自动选择 PostgreSQL、libsql 或 Cloudflare D1；为兼容边缘与 serverless 运行时，数据库驱动改为动态懒加载；为兼容无长连接环境，用轮询端点替代了服务器推送，原推送端点保留但标记废弃。这些是「真要部署到生产」才会遇到的问题，能被提前处理说明框架面向的是可用而非演示。

开源形态与工程可落地性

仓库位于 GitHub 的 BuilderIO/agent-native，核心 npm 包为 @agent-native/core，主分支版本约 0.209，采用 MIT 许可；据第三方报道，仓库根 package.json 声明为 ISC，两者口径不同，商用前应以仓库内实际许可文件为准。仓库包含 packages、templates、community-templates、docs、skills、mcp-registry、prototypes 等目录，提交历史超过七千次，整体处于高频迭代状态。

三点可落地性判断：

• 许可友好度较高：核心包按 MIT 公开，商用限制较少；但核心包与仓库根声明的许可口径需自行核实，这是引入前的必查项。
• 形态完整度高：模板、技能、MCP 注册表、参考应用一应俱全，从克隆到跑起来的摩擦较小，这一点与近期多个框架「降低上手门槛」的取向一致。
• 与 Builder.io 托管服务的商业关系需要厘清：框架开源，托管构建是在线可选路径。对担心供应商绑定的团队，关键在于本地工程的代码、数据与部署是否完全自主——从公开说明看是自主的，但这属于厂商自述，长期仍需观察绑定是否随版本推进而加深。

局限与冷静判断

• Beta 状态，生产可靠性尚未验证：官方明确这是 Beta 发布，是架构主张的公开，不是迁移令。第三方报道也直接指出采用率与生产可靠性仍待检验。此时按生产级标准评估为时过早。
• 「更快更省」缺乏量化基准：官方称相对计算机操控型智能体更快、token 更少、也不那么脆弱，但这是定性表述，未给出任务集、对照方法与测量结果。合理的读法是架构上的预期收益，而非已验证的性能结论。
• 前置重构成本被低估的风险：共享动作的前提是把业务逻辑收敛成边界清晰的动作。对历史包袱重、业务规则散落在各处的存量系统，这一步的工程量可能远大于框架本身，且没有自动化手段可以代劳。
• 六个面放大了权限设计的责任：同一动作同时可被界面、HTTP、MCP 与 A2A 触发，意味着任何一个面的授权疏漏都会覆盖全部。审批点、租户边界、审计留痕必须挂在动作层，且需要逐面验证，而不是只测界面路径。
• 应用状态不能当授权用：共享应用状态带来极大的指代便利，也容易被误用为权限依据。服务端必须从调用者身份推导权限，这一点框架无法替开发者保证。
• 许可口径存在不一致：核心包与仓库根的许可声明在不同来源中有 MIT 与 ISC 两种说法，引入前需以仓库内实际许可文件为准，并确认参考应用的许可是否与核心包一致。
• 版本在快速变动：核心包版本号仍在 0.x 区间，提交与发布频率高，接口稳定性与升级路径需要持续跟踪，生产项目应锁定版本并评估升级成本。

总体而言，Agent-Native 提供的是一次明确且有主张的接口层重划，而不是一个已经跑完验证的工程答案。它准确指出了当前「聊天侧栏」方案的真实代价——同一批能力被实现两遍，且两遍迟早会分叉——并给出了一个代价清晰的解法：把能力收敛成一份带类型的动作契约，让智能体与界面成为它的两个客户端。这个解法是否划算，取决于一个每个团队都要自己回答的问题：你的业务逻辑，能不能被干净地切成一组边界清晰、可独立授权、可独立审计的动作。目前官方及行业暂未披露更多细节，后续将持续跟进迭代动态。