Agent-Native：让 AI Agent 与专用 UI 无缝融合的 TypeScript 框架

Agent-Native 是一个开源 TypeScript 框架，用于构建将自主 Agent 能力与专用 UI 无缝融合的「agentic apps」。它解决了一个核心矛盾：传统 Agent 仅限于文本对话，而真实的工作环境需要上下文感知、持久状态、人机协作与可视化反馈。Agent-Native 通过「统一 action 层」让 AI Agent 和前端 UI 调用同一套能力，实现真正的端到端自动化。截至 2026-09-24，该项目已斩获 6,707 stars、605 forks，上线首日即登上 GitHub Trending，并受到开发者社区广泛认可。

核心能力与设计原则

Agent-Native 的设计哲学是「one action, every surface」——同一个 action，AI Agent 可以当工具调用，React UI 可以用 hook 调用，HTTP/MCP/A2A/CLI 全部共享同一套验证、权限和实现逻辑。

核心设计原则：

• Shared actions（共享 action）：一次定义，Agent 和 UI 同时获得能力，无重复工作
• Shared data（共享数据）：Agent 的工作结果直接出现在 UI，UI 的操作结果 Agent 也能读取
• Shared application state（共享状态）：Agent 实时感知 UI 上下文（当前页面、选中记录、活跃视图）
• Agent 不操作 UI：Agent 通过 action 层工作，而非模拟点击——这是它与传统 browser agent 的本质区别

认可度

链接

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

官方文档：https://agent-native.com/docs

原作者

BuilderIO — 专注于让 Web 开发更高效的知名开源组织，旗下项目累计获得数万 stars，以架构设计精良著称。

介绍

Agent-Native 的起源非常务实：编码 Agent 有文件、测试、预览环境来展示能力，但知识工作型 Agent（如处理邮件、分析数据、生成内容）却缺少同样的可见性和控制力。Agent-Native 为此打造了一个完整的应用框架。

框架以 action 为核心原子单元。一个 action 包含描述（description）、输入 schema（Zod 校验）、运行逻辑（run 函数），同时声明 HTTP 方法、权限等元数据。定义一次，Agent 作为 tool 调用它，UI 通过 useActionQuery 调用它——两边完全对等。

框架内置六大功能模块：Agent Chat（人机对话界面）、Authentication & Permissions（权限控制）、Skills & Memory（Agent 专业能力与持久记忆）、Automations（定时/事件驱动任务）、Agent Teams（多 Agent 协作）、PostgreSQL Backend（生产级数据持久化）。开发者只需关注业务逻辑，基础设施全部由框架承担。

框架还提供了丰富的开箱即用 App 示例：Clips（会议录制理解）、Design（设计生成）、Slides（演示文稿）、Analytics（数据分析）、Calendar（日历）、Mail（邮件）等，覆盖知识管理的核心场景。

特点

• TypeScript 原生：完整类型安全，IDE 全链路补全
• 多端暴露：同一 action 自动支持 UI、Agent、HTTP、MCP、A2A、CLI 六个调用入口
• 无 UI 点击：Agent 通过 action 层工作，结果可审计、可回滚，与真实用户操作等效
• 开箱即用的 App Gallery：9 个生产级示例应用，可直接使用或二次开发
• NPM 生态：一行命令创建项目 npx @agent-native/core@latest create my-agent --standalone --template chat
• PostgreSQL 生产就绪：生产环境用 PostgreSQL，本地开发用 PGlite，数据层无需额外适配

使用方法

安装

npx --yes @agent-native/core@latest create my-agent --standalone --template chat
cd my-agent
npm run dev

定义一个 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 }) => {
    return { message: `Hello, ${name}!` };
  },
});

Agent 调用

Agent 自动获得 hello 作为 tool，调用方式与普通 tool 无异，无需额外配置。

UI 调用

import { useActionQuery } from "@agent-native/core/react";

const { data } = useActionQuery("hello", { name: "Alex" });
// data: { message: "Hello, Alex!" }

使用场景与人群

适用场景：

• 需要人机协作的知识工作流（邮件处理、内容审核、数据分析）
• 多 Agent 协作系统（各 Agent 通过 action 分工，人工监督最终结果）
• 企业内部工具（HR 审批、财务报销、客服工单）——天然需要 UI 可视化而非纯对话
• 需要持久状态和上下文感知的 Agent 应用（不能每次对话从零开始）

目标用户：

• 全栈开发者，想快速构建有 AI 能力的企业级应用
• AI 应用架构师，设计 Agent 与 UI 的协作模式
• 开发者关系/技术布道师，基于框架示例快速 demo

输入与输出案例

案例 1：日历助理创建会议

• Input（Agent）：用户说「帮我约周五下午 3 点和张总开会，讨论季度规划」
• Action：calendar.createEvent({ title: "季度规划讨论", attendees: ["zhang@company.com"], startTime: "2026-09-26T15:00:00Z" })
• Output：会议创建成功，UI 实时显示新日程条目，Agent 返回确认消息给用户

案例 2：数据分析仪表盘

• Input（Agent）：用户问「Q3 的收入趋势如何？」
• Action：analytics.query({ metric: "revenue", dimension: "month", filter: "quarter=Q3" })
• Output：框架渲染图表，用户在 UI 中看到折线图，同时 Agent 给出文字总结：「Q3 收入环比增长 23%，主要来自企业客户的订阅增长」

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