Builder.io开源Agent-Native框架：让人与AI共享同一操作层

过去两年间，整个软件行业都在争相将 AI 嵌入现有应用。但在 95% 的场景下，实现方式如出一辙：在一个传统 Web 应用的右侧角落，塞入一个 iframe 或浮动聊天侧边栏。

聊天侧边栏虽然容易嫁接，但会造成割裂的用户体验：

上下文零共享：用户不得不在主面板里重新解释自己正在查看的内容。

双重维护负担：工程师要维护两套接口——UI 用的 REST/GraphQL 端点，以及 LLM 用的 function-calling 工具。

异步割裂：用户执行的操作对 agent 不可见，agent 生成的结果也很少能即时反映到原生 UI 状态中。

为了解决这种架构层面的割裂，Builder.io 开源了 Agent-Native（BuilderIO/agent-native）——一个全栈 TypeScript 框架，专为人类用户与 AI agent 在同一套 Action 层上平起平坐、协同工作的应用而设计。

以下是 Agent-Native 的架构深度解析：它如何运作、如何将 UI 与 agent 工具集桥接起来，以及如何构建你的第一个 agent-native 应用。

核心理念：统一 Action 层

在传统 Web 应用中，前端组件触发客户端函数或 API 调用。在 agentic 系统中，LLM 通过 JSON schema 定义来调用工具。

Agent-Native 将这两种范式合并为同一个统一原语：Action（动作）。

                           ┌────────────────────────┐
                           │   defineAction(...)    │
                           │  (Zod Schema & Logic)  │
                           └───────────┬────────────┘
                                       │
         ┌──────────────────┬──────────┴──────────┬──────────────────┐
         ▼                  ▼                     ▼                  ▼
  [ React Hooks ]   [ AI Agent Tools ]     [ MCP Protocol ]   [ REST Endpoints ]
 (useActionQuery)    (Direct Invocation)   (Model Context)    (HTTP / CLI)

无需再单独定义一个 API 端点，然后再在 LLM 工具 prompt 里重复同一份逻辑。使用 @agent-native/core 只需定义一次 action：

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

export default defineAction({
  description: "\"Update the status of a project task.\","
  schema: z.object({
    taskId: z.string().describe("The unique ID of the task"),
    status: z.enum(["todo", "in_progress", "done"]),
  }),
  http: { method: "POST" },
  run: async ({ taskId, status }, ctx) => {
    // Shared business logic, database mutation & permission checks
    const updated = await ctx.db.tasks.update(taskId, { status });
    return updated;
  },
});

得益于这种统一结构：

• React UI 通过 React hooks 自然地调用它：

   const { mutate } = useActionMutation("updateTask");

• AI Agent 自动将其作为 LLM 工具接收，包含完整的参数 schema 和描述。

• 外部系统 可以通过自动生成的 HTTP 端点、Model Context Protocol（MCP）服务器或终端 CLI 来触发它。

共享状态与响应式数据

AI 助手最大的痛点在于上下文盲区。如果用户正在查看一份财务报告或某个看板列，还得在 prompt 里告诉 agent"看一下季度列"实在令人厌烦。

Agent-Native 将应用状态视为人类与 agent 之间的共享实时账本：

• 共享状态：agent 自动接收当前 UI 上下文（当前路由、聚焦元素、高亮的表格行、活跃的筛选器）。

• 共享数据：agent 执行的数据变更会即时反映到 UI 中，无需整页刷新或手动刷新。

• Action 驱动，而非像素驱动：与那些依赖截屏解析和屏幕坐标点击的脆弱 computer-use 工具不同，Agent-Native 的 agent 直接执行带类型的 action。这带来了确定性可靠性、零 UI 劫持以及即时执行速度。

开箱即用的生产级组件

除了 Action 层，Agent-Native 还自带完整的底层设施支持：

• PostgreSQL & PGlite：开发环境下运行轻量的 PGlite 内嵌内存数据库，生产环境无缝连接托管型 PostgreSQL（Supabase、Neon、AWS RDS）。

• 自主自动化：不仅支持手动聊天 prompt 触发 agent 工作流，还能按定时 cron 计划或 webhook 事件触发。

• Agent 团队：内置编排能力，可将复杂工作流委托给同一工作空间中的多个专业 agent。

• Skills 与 Memory：持久化上下文存储与模块化技能，让 agent 具备长期组织知识。

• 企业级权限：细粒度 RBAC，确保 agent 只能执行当前用户会话授权范围内的 action。

快速上手：创建你的第一个 Agent-Native 应用

使用官方 CLI 可以快速引导出一个完整的 agent-native 应用：

npx --yes @agent-native/core@latest create my-agent --standalone --template chat

生成后，进入目录并启动本地开发环境：

cd my-agent
npm run dev

这会启动一个本地 Nitro 兼容服务器，内嵌 PGlite，自动注册 /actions 目录下的所有 action，并提供一个交互式协作 UI，内置 agent 聊天和审查面板。

Agent-Native 代表了生成式 AI 时代软件工程的自然演进。通过抛弃相互孤立的聊天气泡，并将 Action 层在代码与模型之间统一起来，它让开发者能够构建出 AI 作为积极、可靠协作者的应用。

GitHub Repository: https://github.com/BuilderIO/agent-native

Maintained by: Builder.io