Agent 和 UI 不是二选一——Agent-Native 的 defineAction 统一了 6 种入口

项目：Agent-Native

GitHub：BuilderIO/agent-native（1.3k stars）

许可证：MIT

核心：defineAction 统一抽象 + 共享状态层 + SQL 持久化

📌 为什么你现在应该关注这个框架

当前 Agent 应用有一个根本困境：要么只有聊天界面（没有丰富 UI），要么只有 UI（没有 Agent 自主性）。

ChatGPT 式的纯聊天 Agent → 用户要一一步步引导，效率低
传统 Web 应用 → 有丰富 UI 但没有 Agent 自主性，用户必须手动操作

Agent-Native 提出了第三条路：Agent 和 UI 是同一系统的同等公民，共享同一套动作注册和状态管理。

核心抽象：defineAction

一个 defineAction 定义同时服务于 6 种入口：

typescript 复制代码

export default defineAction({
  schema: z.object({
    emailId: z.string(),
    body: z.string(),
  }),
  run: async ({ emailId, body }) => {
    await db.insert(replies).values({ emailId, body });
  },
});

这一个定义同时驱动：

入口	触发方式	用户体验
UI 按钮	用户点击"回复"按钮	点击即执行
Agent 工具调用	Agent 说"我帮你回复这封邮件"	自然语言驱动
HTTP API	POST /api/actions/reply-email	程序化调用
MCP 协议	MCP 客户端调用工具	跨 Agent 调用
A2A 协议	另一个 Agent 请求协作	Agent 间通信
CLI 命令	`agent-native reply-email --emailId 123 --body "Hi"`	命令行执行

关键洞察：6 种入口不是 6 套代码，而是 1 套代码的 6 种表现形式。写一次，到处使用。

共享状态层：Agent 和 UI 是平等公民

传统架构：

复制代码

UI 层 → 自己的状态管理 → 自己的 API
Agent 层 → 自己的状态管理 → 自己的 API
两边不一致，经常打架

Agent-Native 架构：

复制代码

┌─────────────────────────────────┐
│         单一数据库（SQL）         │
│     ┌─────────┬───────────┐     │
│     │  UI 状态 │ Agent 状态  │     │
│     └─────────┴───────────┘     │
│          共享、实时同步            │
└──────────┬──────────┬───────────┘
           │          │
      ┌────▼───┐ ┌────▼───┐
      │  UI 层  │ │ Agent  │
      │(人类)   │ │(AI)    │
      └────────┘ └────────┘

能力	说明
即时同步	任何一侧的变更立即反映到另一侧
实时多人协作	人类和 Agent 作为一等公民共同编辑
上下文感知	Agent 知道用户正在查看什么；选中文本后按 `Cmd+I` 可直接指示 Agent
Agent 间协作	通过 A2A 协议，一个 Agent 可以标记另一个 app 中的 Agent

真实场景：用户在 UI 上选中文本 → 按 Cmd+I → Agent 基于选中文本执行操作 → 结果实时反映到 UI。不是"聊天窗口 + 独立界面"的拼接，而是真正的统一体验。

框架原语全景

原语	说明
Actions	统一的工作定义，驱动所有接口
Agent Runtime	聊天、工具、技能、记忆、任务、可观测性、交接
Tools & Skills	可组合的能力单元（可通过 `npx skills add` 安装）
Jobs	后台任务调度
Observability	内置可观测性
UI Surfaces	与 Agent 紧密集成的界面

认证与持久化

认证

模板组合共享认证------快速启动时选择多个模板（如 Mail + Calendar + Forms），共享同一 auth
Identity 作为一等原语------框架内置身份管理
应用级身份注册机制

SQL 持久化

使用 Drizzle ORM------类型安全的 SQL 操作
支持 PostgreSQL、MySQL、SQLite、Turso 等多种数据库
不锁定特定数据库
与任何 Nitro 兼容的托管服务配合

部署

支持将不同功能模块部署为独立的 Cloudflare Workers：

复制代码

wrangler-analytics.toml    # 分析服务
wrangler-calendar.toml     # 日历服务
wrangler-chat.toml         # 聊天服务
wrangler-content.toml      # 内容服务
wrangler-forms.toml        # 表单服务
wrangler-mail.toml         # 邮件服务
wrangler-slides.toml       # 幻灯片服务
wrangler-videos.toml       # 视频服务

与传统 Agent 框架的对比

维度	LangChain/AutoGen	Agent-Native
Agent 入口	聊天 / API	6 种统一入口
状态管理	Agent 私有	UI + Agent 共享
用户界面	聊天窗口	原生 UI + Agent
数据持久化	通常无 / 自行解决	内置 SQL
认证	自行解决	内置共享认证
部署	自行解决	Cloudflare Workers
协作模式	Agent-to-Agent	Human + Agent + Agent-to-Agent

核心区别：传统框架是"给 Agent 加聊天窗口"，Agent-Native 是"从零开始设计 Agent 和 UI 共存的系统"。

对 OpenClaw Skill 系统的启发

当前 OpenClaw 的 Skill 是 markdown 定义------一段指令文本告诉 Agent 怎么做。

Agent-Native 的 defineAction 启发了一种升级路径：

当前 Skill	升级后 Action
Markdown 指令	Schema + 可执行函数
只有 Agent 能调用	UI + Agent + API + CLI 都能调用
无状态管理	共享 SQL 状态
无 UI 渲染	自动生成 UI 组件

未来方向：Skill = Action 定义 + UI 渲染 + Agent 工具调用三位一体。

快速启动

bash 复制代码

# 创建新项目
npx @agent-native/core@latest create my-app
cd my-app
pnpm install
pnpm dev

# 添加技能（如可视化规划）
npx @agent-native/core@latest skills add visual-plan

创建模式选择：

Full template：完整应用，多模板共享认证
Chat：最小聊天 UI + 浏览器 shell
Headless：无 UI 的 action-first 应用，CLI 调用

So What：三类人的行动清单

🔧 工程师

defineAction 模式改变了 Agent 工具注册方式------不再为 UI 和 Agent 写两套代码
共享状态消除了"UI 和 Agent 不同步"的 bug------单一数据源 = 单一真相
明天就能做 ：npx @agent-native/core@latest create test-app，30 分钟跑通 demo

📊 技术管理者

"Agent + UI"统一开发 = 工程效率翻倍------一套代码服务 6 种入口
内置 SQL 持久化 + 认证 = 减少基础设施选型决策
明天就能做：评估团队 Agent 项目的 UI 层------有多少代码是"为 UI 和 Agent 各写一套"？

🚀 创业者/PM

"Agent-Native 应用"是新品类------不是"聊天机器人"，不是"SaaS + AI"，而是"Agent 和用户共生的原生应用"
6 种入口 = 6 种获客渠道------同一个 action 通过 CLI/API/MCP 暴露给不同用户群
明天就能做：画一个"用户最常用的 3 个操作"的 defineAction 草图，想象它们同时驱动 UI 和 Agent

⚠️ 方法论局限

框架仍处于 v0.66.0------API 可能变动，生产使用需谨慎
认证的具体实现文档不完整------需参考 agent-native.com 完整文档
TypeScript 优先------Python 生态的 Agent 开发者需要适配
Cloudflare Workers 部署模式锁定特定平台------虽然可以自托管，但文档以 Workers 为主
多 Agent 协作的复杂场景（冲突解决、权限控制）文档不足

Agent 和 UI 不是二选一——Agent-Native 的 defineAction 统一了 6 种入口

📌 为什么你现在应该关注这个框架

核心抽象：defineAction

共享状态层：Agent 和 UI 是平等公民

框架原语全景

认证与持久化

认证

SQL 持久化

部署

与传统 Agent 框架的对比

对 OpenClaw Skill 系统的启发

快速启动

So What：三类人的行动清单

🔧 工程师

📊 技术管理者

🚀 创业者/PM

⚠️ 方法论局限

延伸阅读