Builder.io 的 agent-native,我先把判断放这:它解决的不是「怎么让 Agent 干活」,是「Agent 和 UI 能不能共用一套能力」。别的框架要么偏 Agent 要么偏前端,它硬要把两者焊在一层 action 上。这篇记我装它的过程,讲清这个设计的代价和边界。
我在本机(macOS 14.6.1,Node v22.22.2)真装了一遍。README 给的起步命令是 npx --yes @agent-native/core@latest create my-agent --standalone --template chat。我跑这条,卡了 8 分钟没反应。一查,这个 npm 包 dist.unpackedSize 是 40414351 字节,约 40MB,下载慢。我换了路子:先 npm install @agent-native/core@0.231.0,约 5 分钟装成,node_modules 里 @agent-native/core/package.json 的 version 字段就是 0.231.0。这一步我记清楚了,别在网差的环境下用 npx 硬等。
一个 action 喂给五端
它的核心概念就一个词,defineAction。我在 README 里读到 hello.ts 这个示例,defineAction 一次定义,五个入口都能调。Agent 把它当工具用,React 用 useActionQuery("hello", { name: "Alex" }) 从代码调,同一段还通过 HTTP、MCP、A2A、CLI 暴露。这是它跟 CopilotKit 最本质的区别,CopilotKit 的动作是给前端组件的,agent-native 的动作是双向的。
import { defineAction } from "@agent-native/core/action";
import { z } from "zod";
export default defineAction({
description: "Return a friendly greeting.",
mcpTool: true,
schema: z.object({
name: z.string().default("world").describe("Name to greet"),
}),
http: { method: "GET" },
run: async ({ name }) => {
return { message: `Hello, ${name}!` };
},
});
这段代码我照 README 的结构自己写的。schema 用 zod 定义参数,http 管 HTTP 方法,mcpTool: true 管 MCP 工具暴露,run 是唯一的实现。一个 action 写完,UI 和 Agent 共用同一套校验、权限和实现,不会出现「UI 里一套逻辑、Agent 里又抄一套」的分叉。这就是它说的 shared actions。
共享数据,不是共享一段提示词
我核了 1 遍 README 的三层设计。除了 shared actions,还有 shared data 和 shared application state。Agent 干的活出现在 UI 里,UI 里改的东西 Agent 也能拿到。Agent 不点 UI,它走同一层 action。这句「The agent does not click through the UI」我印象很深,它划清了 Agent 和 UI 的边界。
navigate.ts 这个示例最能说明 shared application state 怎么落地。Agent 要跳转页面,不模拟点击,而是写一条 navigate 命令进应用状态,UI 读到就自动跳、再删掉:
import { writeAppStateForCurrentTab } from "@agent-native/core/application-state";
export default defineAction({
description: "Navigate the UI to a specific view or path.",
schema: z.object({ view: z.string().optional(), path: z.string().optional() }),
http: false,
mcpTool: "search",
run: async (args) => {
const nav: Record = {};
if (args.view) nav.view = args.view;
if (args.path) nav.path = args.path;
nav._writeId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
await writeAppStateForCurrentTab("navigate", nav);
return `Navigating to ${args.view || args.path}`;
},
});
这段也是我按源码思路写的简版。它解决的事很具体:Agent 不用碰 DOM,UI 也不用猜 Agent 想干嘛,中间靠一条带 _writeId 的状态消息。这套设计在 LangGraph 里没有对应物,LangGraph 管的是后端工作流编排,不管 UI。
create 之后长什么样
我跑了 1 遍 node bin/agent-native.js --help,输出 agent-native v0.231.0 和完整命令清单:dev、build、start、action、agent "prompt"、agents list、invoke "prompt"、doctor、mcp。其中 invoke 走 A2A 调另一个 app,mcp 接外部编码 Agent。命令面比我想的宽。
然后我跑了 1 遍 agent-native create my-agent --standalone --template chat,输出 App created!,路径在 /private/tmp/an_create/my-agent。生成的项目里有 actions/ 目录,五个文件:hello.ts、navigate.ts、provider-api-request.ts、run.ts、view-screen.ts。我打开生成的 agent-native.json 读了 1 遍,就三样:
{
"version": 1,
"onboarding": { "firstRun": "off" },
"doctor": { "failOnBuild": false }
}
agent-native.config.ts 也只有两行,defineAgentNativeConfig 加 harness。骨架干净,没有一堆样板。
这里我记一个判断。这套东西装得起来,跑起来还要 pnpm install 加 pnpm dev,它绑 pnpm,我本机只有 npm。这是个小门槛,但对 monorepo 出身的项目不算意外。
它到底适合谁
值不值得上,我给个分界。你在做一个既有 Agent 又有富交互 UI 的产品,希望两者共用一套能力,agent-native 是目前最顺的一层封装。你只是要个后端 Agent 工作流,没有 UI,那 LangGraph 更省事,agent-native 的 UI 层是纯负担。你已经有 CopilotKit 的前端动作,也不值得为「Agent 也能调」重写一遍。
还有个判断。agent-native 的抽象是把动作、数据、应用状态三样都收到一个「shared」框架下,好处是一致,代价是你要接受它的路由和状态模型。CLAUDE.md 里那句「The agent and UI are equal partners」是它的立场,不是空话。你认这个立场,就值得装。不认,别硬套。