一、它到底解决了什么问题
过去两年，几乎所有团队都在给产品加 AI Agent，但做法基本是"外挂式"的：让一个 AI 助手在旁边观察界面，模拟人类去点击按钮、填表单、截图识别。这条路有三个致命问题。
第一，慢且贵。Agent 每操作一步都要截图、识别、思考、再点击，一个简单任务跑几十秒很正常，Token 消耗巨大。
第二，不可靠。界面稍微改版，Agent 就"瞎"了；弹窗、验证码、动态加载都可能让流程中断。
第三，重复开发。同一个业务能力，人类用要写一套 API，Agent 用要包一层 MCP 工具，CLI 命令再写一遍，HTTP 接口又是一套——四份代码做同一件事。
agent-native 的答案很直接：与其让 Agent 模仿人类点 UI，不如让 Agent 和人类使用同一套"动作层"（Actions）。这是它最核心的架构决策——Agent 不点界面，而是调用与界面按钮完全相同的函数。
二、它是怎么解决的
agent-native 把 Agent 时代应用的重构归纳为"三个共享"。
共享动作（Shared Actions）：业务逻辑全部写成 Action，放在扁平的 actions/ 文件夹里自动挂载。一个 Action 同时就是：React UI 里按钮背后的函数、Agent 的工具（tool）、HTTP 接口、CLI 命令、MCP 工具、A2A 端点。写一次，六个入口全通。
共享数据（Shared Data）：生产环境用 PostgreSQL，本地开发自动切换为零配置的 PGlite，数据模型完全一致，不再为本地另搞一套 SQLite。
共享应用状态（Shared App State）：页面、选中项、当前视图这些状态，Agent 和 UI 读写同一份。用户刚在界面上选中了一张图片，Agent 立刻知道，可以直接基于它继续操作。
一句话总结：它不是把 Agent 塞进应用，而是把应用改造成 Agent 天然能理解的结构。
三、技术栈与开发语言
agent-native 由 BuilderIO 开源（就是做 Mitosis 跨端框架和 Party.io 的团队），MIT 协议。
开发语言是 TypeScript，全栈统一。核心技术选型：前端 React；类型与参数校验用 Zod schema；服务端跑在 Nitro 上；数据库 PostgreSQL / PGlite；LLM 接入支持 Builder.io（送免费额度）、Anthropic、OpenAI，甚至本地 Ollama。
除了框架本身，官方还开源了 9 个基于它构建的完整应用：会议记录 Clips、设计工具、幻灯片、数据分析、日历、邮件、素材库、内容和计划，每一个都是可学习、可二开的参考实现。
四、怎么安装部署
前置要求只有三项：Node.js 22.22 及以上、pnpm 包管理器、一个 LLM 连接（Builder.io / Anthropic / OpenAI / Ollama 任选）。
三步启动：
npx --yes @agent-native/core@latest create my-app --standalone --template chat
cd my-app
pnpm install && pnpm dev
第一条命令会交互式引导你配置 LLM 连接，装完依赖启动开发服务器即可看到带聊天界面的模板项目。部署方面，因为底层是 Nitro，构建产物可以发布到 Node 服务器、Docker 或各类 Serverless 平台，数据库接上 PostgreSQL 就是生产环境。
五、怎么使用：写一个 Action
新建 actions/hello.ts：
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 }) => ({ message: `Hello, ${name}!` }),
});
界面里调用同一个 Action，用官方 React Hook：
const { data } = useActionQuery("hello", { name });
注意看这个流程的精妙之处：description 和 Zod schema 里的 describe，既是给 AI 看的工具说明文档，也是类型校验规则；run 函数人类界面在调，Agent 也在调。你写下的每一行业务代码，天然就是 Agent 的能力。
六、写在最后
agent-native、一周内持续霸榜 Trending，说明"AI-native 应用该怎么写"确实戳中了大量开发者的焦虑。它给出的答案未必是唯一解，但"Agent 与人共用动作层、不模拟点击"这个思路，大概率会成为下一代应用架构的共识。
仓库地址：github.com/BuilderIO/agent-native
相关文章
