Agent-Native：让 AI Agent 和用户界面「同呼吸共命运」的 TypeScript 框架

开篇：当 AI Agent 变成「看不见摸不着」的黑盒

你花了两周训练了一个 AI Agent，帮运营人员自动处理客户工单。它确实在跑，API 返回正确，但运营同事不买账——「这玩意儿我怎么信？它干了啥我看不懂，改错了怎么撤回？」

这就是当前大多数 AI Agent 的真实处境：** Agent 在后端跑，用户在黑盒外交互**。Agent Native（BuilderIO 开源）正是来解决这个问题的：让每个 AI 能力天然就有配套的 UI，让 Agent 的工作「看得见、管得住」。

背景：Agent 为什么需要 UI？

传统 Agent 往往只有一个 API 端点，靠 prompt 工程和 function calling 驱动。但真实工作场景中：

• Agent 的结果需要被审查：合同审核 Agent 生成修改建议，用户得能逐条查看、选择性采纳
• Agent 的执行需要上下文：一个代码审查 Agent，得知道当前仓库结构、CI 状态
• 人机协作需要反馈回路：Agent 给出建议，人可以纠正、补充，而不是只能「接受或拒绝」

Agent Native 的核心洞察是：Agent 不应该「操作」UI（比如模拟鼠标点击），而应该和 UI 共用同一套动作层（Action Layer）。

核心机制：「一次定义，多端复用」的 Action 层

Agent Native 的设计哲学可以用一句话概括：同一个 Action，Agent 调用它作为工具，UI 调用它从代码层面执行。

开发者定义一个 Action：

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

export default defineAction({
  description: "返回友好问候",
  schema: z.object({
    name: z.string().default("world").describe("被问候的名字"),
  }),
  http: { method: "GET" },
  run: async ({ name }) => {
    return { message: `Hello, ${name}!` };
  },
});

这一段代码，同时给 Agent 暴露为一个 tool（自动注册到 Agent 的工具列表），又给 React 前端暴露为一个函数调用（useActionQuery），同时还通过 HTTP、MCP（Model Context Protocol）、A2A（Agent-to-Agent）协议对外暴露。零重复定义，多端生效。

技术架构：Monorepo + Nitro + Drizzle

从项目结构看，这是一个 pnpm monorepo：

• packages/ 目录存放核心包（@agent-native/core 等）
• templates/ 提供开箱即用的 Agent 模板（chat、clips、design 等）
• e2e/ 包含端到端测试套件（Vitest）
• 依赖 Nitro（底层 HTTP 服务框架）和 Drizzle（ORM）

技术栈组合：TypeScript + React + Nitro + Drizzle + PostgreSQL/PGlite，全栈自洽，开发者无需引入外部技术栈就能跑起来。

上手体验：pnpm dev 就是全部

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

无需 Docker，不依赖外部数据库（开发用 PGlite），开箱即用的聊天界面。官方还提供了 Clips（会议录音理解）、Design（设计稿 AI 辅助）等真实应用模板，可以直接当参考。

争议与局限

1. 生态锁定：依赖 BuilderIO 自家生态（Agent chat、Skills、Automations），迁移出去不一定容易
2. 没有容器化：没有提供 Dockerfile 或 docker-compose，生产部署需要自己写，对运维团队不友好
3. 相对年轻：2024 年底才发布，文档和社区还在成熟中
4. 特定场景：更适合「AI + 业务 SaaS」类应用，纯后台批处理场景反而增加了不必要的复杂度

行业意义：Agent 的下一站——「应用化」

Agent Native 背后的趋势判断是：AI Agent 的下一阶段不是更强的模型，而是更好的「载体」——让 Agent 从 API 变成真正的应用。用户不想要一个会跑的黑盒，他们想要一个「能干活、能解释、能协作」的同事。

从 GitHub Trending 霸榜来看，这个方向正在被大量开发者认可。对于正在构建 AI 原生应用（尤其是有 UI 交互需求）的团队，Agent Native 提供了目前最清晰的架构范式之一。