Agent 和 UI 不再是两张皮：BuilderIO agent-native 用一个 action 层打通六个面

2026 年 9 月，BuilderIO 开源了 agent-native 框架。89 颗星一天涨上来，不算爆炸，但它的设计思路值得拆解——它把 Agent 和 UI 之间的墙拆了，让两者共享同一套 action 层。

一个痛点：Agent 能干活，用户看不见

如果你用过 Claude Code、Cursor、Codex 这类编程 Agent，你会发现一个共同模式：Agent 在终端里干活，你在终端里看。Agent 说"我要修改 src/auth.ts"，你看到这行字，然后它改了，你再看 diff。

这个模式的痛点是：Agent 的能力被终端这个"窄口"限制了。它能做的事情远比"打印文字"多——它能调 API、查数据库、发通知——但终端只能显示文字。

反过来，UI 应用也有痛点：用户在 UI 里点按钮、填表单，但这些操作和 Agent 的能力是割裂的。Agent 不知道用户在 UI 里做了什么，UI 也不知道 Agent 能做什么。

agent-native 的核心洞察是：Agent 和 UI 不应该是两个独立系统，而应该共享同一套 action 层。

核心机制：defineAction 定义一次，六个面都能用

agent-native 的 action 定义长这样：

import { defineAction } from "@agent-native/core/action";
import { z } from "zod";

export default defineAction({
  description: "Return a friendly greeting.",
  schema: z.object({
    name: z.string().default("world").describe("Name to greet"),
  }),
  http: { method: "GET" },
  run: async ({ name }) => {
    return { message: `Hello, ${name}!` };
  },
});

这一个 hello action，定义完之后：

1. Agent 把它当工具调用——LLM 看到 hello 的 description 和 schema，知道可以调用它
2. UI 把它当函数调用——React 组件用 useActionQuery("hello", { name: "Alex" }) 调用
3. HTTP 接口——http: { method: "GET" } 让它自动暴露为 HTTP API
4. MCP 接口——其他 Agent 可以通过 MCP 协议调用
5. A2A 接口——其他 Agent 可以通过 A2A（Agent-to-Agent）协议调用
6. CLI 接口——命令行可以直接调用

六个面，同一份代码。这就是 "agent-native" 的含义——应用从出生就是为 Agent 设计的，不是后来加个 chat 框。

类比：REST API 之于前后端

如果觉得这个模式眼熟，那是因为它和 REST API 的思路一脉相承。

在 REST 架构里，后端定义一组 API，前端消费这些 API。前端和后端通过 API 契约解耦——前端不关心后端用什么语言写，后端不关心前端是什么 UI。

agent-native 把这个思路延伸到 Agent 时代：

关键区别是：传统 REST 只有"前端"和"后端"两个面，agent-native 有六个面——UI、Agent、HTTP、MCP、A2A、CLI。同一个 action，六个面都能调。

"Agent 不点 UI" 的设计哲学

agent-native 的一个关键设计决策是：Agent 不通过点击 UI 来工作。

这听起来反直觉——如果 Agent 能点 UI，不就能做用户能做的一切事了吗？

问题在于：UI 点击是为人设计的交互方式，不是为 Agent。Agent 点 UI 意味着：

• Agent 要理解 UI 布局（按钮在哪、表单怎么填）
• Agent 要模拟点击事件（脆弱，UI 一改就坏）
• Agent 要等待 UI 响应（慢，比直接调函数慢几个数量级）

agent-native 的做法是：Agent 和 UI 都调用同一个 action 层，但 Agent 不经过 UI。Agent 直接调 action，UI 也直接调 action。两者共享数据（PostgreSQL），共享状态（当前页面、选中记录），但不共享交互路径。

这就像银行的柜员和客户都访问同一个账户系统，但柜员用内部终端（直接调 API），客户用手机银行（UI）。两者操作的是同一份数据，但交互方式各自优化。

共享数据 + 共享状态

除了共享 action，agent-native 还共享两样东西：

1. 共享数据——Agent 做的工作出现在 UI 里，UI 里做的工作对 Agent 可见。数据存在 PostgreSQL（生产）或 PGlite（本地），两者读写同一个数据库。

2. 共享应用状态——Agent 知道 UI 当前在哪个页面、选中了哪条记录、激活了哪个视图。这让 Agent 能根据上下文工作——如果用户在看某条客户记录，Agent 知道"这个客户"是谁，不需要用户再解释一遍。

这两个共享让 Agent 和 UI 真正"协同"工作，而不是各干各的。

和其他 Agent 框架的对比

大多数 Agent 框架的思路是"Agent 在后台干活，结果通过 API 或消息返回"。agent-native 的思路是"Agent 和 UI 是同一个应用的两个面，共享 action 层"。

这个差异在实践中很重要：传统框架需要你单独搭一个 UI 来展示 Agent 的工作，agent-native 自带 UI，Agent 的工作直接出现在用户面前。

内置能力

agent-native 不只是一个 action 定义器，它还内置了：

• Agent chat——用户可以委派工作、提问、审查结果
• 认证和权限——控制谁能访问和修改共享工作
• Skills 和 memory——给 Agent 可复用的专业知识和持久上下文
• Automations——按计划或事件触发 Agent 工作
• Agent teams——在同一工作区委派工作给专家 Agent
• PostgreSQL 后端——生产用 PG，本地用 PGlite

这些能力让 agent-native 不只是一个库，而是一个"Agent 应用脚手架"——你拿来就能跑，不用自己搭认证、数据库、UI。

开源 Agent 示例

agent-native 提供了两个开源 Agent 作为示例：

1. Clips——记录和理解会议、屏幕、语音笔记
2. Design——（README 未详细展开）

这两个示例的价值不在于它们本身能做什么，而在于它们展示了"agent-native 范式"长什么样——一个有 UI 的 Agent 应用，不是只有 chat 框。

什么时候该用，什么时候不该

该用 agent-native 的场景：

• 内部工具——需要 Agent 自动化 + UI 人工操作结合
• 知识工作——分析师、律师、医生等需要 Agent 辅助但有 UI 审查
• 多 Agent 协作——需要多个专家 Agent 在同一工作区工作
• 需要 MCP/A2A 集成——Agent 要被其他 Agent 调用

不该用的场景：

• 纯 chatbot——不需要 UI，用 Vercel AI SDK 就够
• 纯自动化——不需要 UI，用 LangChain 就够
• 高并发 API——action 层有开销，不如直接写 REST

和 Vercel json-render 的关系

有趣的是，今天 GitHub Trending 上同时出现了两个相关项目：Vercel 的 json-render 和 BuilderIO 的 agent-native。两者都关注"AI 和 UI 的关系"，但角度不同：

• json-render：AI 生成 UI spec，UI 消费 spec——关注"AI 怎么画 UI"
• agent-native：Agent 和 UI 共享 action——关注"Agent 和 UI 怎么协作"

一个是"生成"维度，一个是"协作"维度。两者不冲突，甚至可以互补——agent-native 的 UI 可以用 json-render 来生成动态界面。

收尾：Agent 的瓶颈不是模型，是手脚

过去两年，Agent 领域的注意力主要在"模型能力"上——更强的推理、更长的上下文、更好的工具调用。但 agent-native 揭示了一个被忽视的维度：Agent 和用户环境的集成方式。

一个 Agent 再聪明，如果只能通过终端文字和用户交互，它的能力就被截断了。agent-native 的贡献不是让 Agent 更聪明，而是让 Agent 有"手脚"——能通过 UI 展示工作、能通过 HTTP/MCP/A2A 被其他系统调用、能共享用户的应用状态。

这和大脑皮层的进化类似——人类智能的跃迁不只是因为大脑变大了，还因为手变灵活了、语言出现了、工具复杂了。Agent 的进化也需要"手脚"的进化，不只是"大脑"（模型）的进化。

agent-native 可能不是最终答案，但它指出了一个正确方向：Agent 应用不是"模型 + chat 框"，而是"模型 + action 层 + UI + 数据 + 状态"。这五样东西的集成方式，决定了 Agent 应用的上限。

项目地址：https://github.com/BuilderIO/agent-native
文档：https://agent-native.com/docs/getting-started