Agent-Native 是什么?7.7K 星的 TypeScript 框架,写一次 Action 让界面和 Agent 共用(基础篇)

Agent-Native 是什么?7.7K 星的 TypeScript 框架,写一次 Action 让界面和 Agent 共用(基础篇)

让 agent 干活的界面,九成产品只给一个聊天框:你打一句话,它回一段字,剩下的复制、粘贴、改格式全归你。真要把结果交给同事、要让人在它写的东西上改两笔、要留下操作记录,聊天框立刻不够用。

Agent-Native 是 Builder.io 开源的 TypeScript 框架,赌的就是这条缝:给每个 agent 配一个真界面,而界面和 agent 共用同一套「动作」。

它是什么

仓库在 BuilderIO 组织下,2026 年 3 月建,10 月 14 日公开 beta。MIT 许可,TypeScript,现在 7,710 星、710 个 fork;npm 上的 @agent-native/core 最新 0.228.2,上周下载 8.99 万次。

它要解决的不是「再做一个 agent 平台」,而是「agent 做完的东西放哪」。官方那句总结很直白:定义一次 action,agent 把它当工具调,界面从代码里调同一个函数——同一份校验、同一份权限、同一份实现。

对比一下就清楚。browser-use 那类方案让模型看屏幕、找按钮、点下去,一步一次推理,慢且费 token;Agent-Native 干脆不让 agent 碰界面——界面背后那层 action 本来就是它要调的东西。

TypeScript 生态里同类的还有 Mastra、Vercel AI SDK、OpenAI AgentKit,但它们各自盯着编排、模型调用、可视化搭建;Agent-Native 盯的是「界面」这一层。

拆开看:一份定义,六个面

一个 action 就是 actions/ 目录下的一个文件:

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

export default defineAction({
  description: "给邮件线程写一封回复",
  schema: z.object({
    emailId: z.string(),
    body: z.string(),
  }),
  run: async ({ emailId, body }) => {
    return { ok: true, emailId };
  },
});

description 决定 agent 什么时候调它,zod schema 同时是校验规则和 agent 读到的 JSON Schema,run 是真实现。写完不用注册,框架自动把它变成:UI hooks、agent 工具、HTTP 接口 /_agent-native/actions/<name>、MCP 工具、A2A 工具、CLI 命令。文档的说法是「一份定义,七个消费者」(hooks 和 callAction 分开算),公测文章里只说六个面;口径不同,意思是同一个——一份实现,多个调用方。

Agent-Native 架构:defineAction 定义一次,React 界面、Agent 对话、HTTP、MCP、A2A、CLI 共用同一个 action
一个 defineAction,扇出到界面、agent、HTTP、MCP、A2A 和命令行

再往上一层是共享数据和应用状态:agent 干完的活直接出现在界面里,界面里改的东西 agent 也看得见;agent 还能读到当前页面、选中记录这类上下文,不用你手动往 prompt 里贴。

底座是 Nitro + React:本地开发用 PGlite,线上换 PostgreSQL;认证与权限、Skills、Memory、Automations、Agent Teams 都是框架自带的。模板给了九个成品——Clips、Design、Slides、Analytics、Calendar、Mail、Assets、Content、Plans,能不能直接用另说,至少能看清「agent + 界面」长什么样。

上手

前提只有 Node 22.22+ 和 pnpm,三条命令起一个带聊天界面的应用:

npx --yes @agent-native/core@latest create my-app --standalone --template chat
cd my-app && corepack enable && pnpm install
pnpm dev

浏览器会自动打开,选「Continue as local dev」不用注册。模型可以走 Builder.io,也可以在 .env 里填 Anthropic / OpenAI 的 key,或者指到本地 Ollama——这点对国内环境友好。

模板自带一个 hello action,什么都不改就能验证整条链:对话框里说「给 Alex 打个招呼」,agent 按 description 找到它、按 schema 传参;再新建一个页面用 useActionQuery("hello") 调它,然后把 run 的返回值改一遍——聊天框和页面同时变。命令行也能跑:

pnpm action hello '{"name":"Steve"}'

这一步值得亲手做一遍:同一个函数,聊天框、页面、终端三个入口,返回同一份结果。

实话

第一,版本号还在 0.228.2。beta 阶段,nightly 每天在发,API 会动,照着半年前的帖子抄大概率报错。

第二,技术栈绑得死。React + Nitro + TypeScript,想接 Python 后端或者 Vue 前端,这套共享 action 的甜头就吃不到了。

第三,它管外壳不管脑子。模型、业务逻辑、部署仍然是你的事,指望装个框架让 agent 变聪明会失望。它只回答「结果往哪放、人怎么改、别人怎么用」。

第四,如果产出不需要人看、也不需要人改——比如每天定时跑的抓取脚本——界面就是纯负担,直接走 HTTP 接口或 CLI 更省事。

第五,7.7K 星里有渠道因素:Builder.io 自家产品线在推,仓库还塞了 /visual-edit、/remix 这类给 Claude Code 用的技能,涨星速度和生态成熟度不是一回事。

值不值得试

判断只需要一个问题:agent 的产出,别人要不要在上面动手。

要——花半小时把 hello 那条链跑一遍,看「一份 action 两头用」是不是你要的手感,再决定要不要接进自己的业务;不要——继续用脚本和定时任务,别为了架构好看给自己加一层。

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注