知 Zhihu EEAI Notes

2026/07/07

Agent-Native 教程：别给应用外挂聊天框，把动作层做成 Agent 和 UI 的公共契约

深入介绍 BuilderIO/agent-native 的 action-first 架构：defineAction、共享状态、MCP/A2A、模板、安全边界、观测和评测。

Agent-NativeAI AgentMCPA2ATypeScript

BuilderIO/agent-native 讨论的是一个正在变得重要的应用形态：应用不再只给人点按钮，也不再只在旁边挂一个聊天框，而是让人、界面和 Agent 共用同一套动作、状态和上下文。这个方向比“给产品加 AI 助手”更深，它会改变应用本身的 API 设计。

项目由 Builder.io 开源，TypeScript 为主，GitHub 当前约 3.5k stars，核心包 @agent-native/core 最新版本线在 0.90.x，release 中还能看到 @agent-native/[email protected] 这类持续更新。仓库里不只是一个库，还包含 Mail、Calendar、Clips、Plan、Design、Analytics 等模板，说明它想验证的是一套完整应用框架，而不是一个孤立组件。

核心判断：Action 才是应用和 Agent 的公共语言

传统 Web 应用通常有三套东西：前端事件处理、后端 API、Agent 工具定义。最开始这样写很快，但一旦 Agent 真要改数据、查状态、执行业务动作，重复就会出现：UI 调一个接口，Agent 调一个 tool，外部系统又调一个 API。三套入口的权限、校验、日志和语义很容易漂移。

Agent-Native 的主张是把操作收束到 Action。一个 defineAction 同时服务 UI、Agent、HTTP、MCP、A2A 和 CLI。这个设计的意义不是少写几行代码，而是让业务能力只有一个真实实现。

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

这段 README 里的例子很短，但方向很明确：回复邮件这件事不是“前端按钮逻辑”，也不是“Agent 专用工具”，而是一个受 schema 校验、可复用、可审计的应用动作。

为什么聊天框不是 Agent-native 应用

把一个聊天框嵌进 SaaS 右下角，只能解决“用户能不能用自然语言问问题”。真正复杂的是：Agent 是否能看到当前页面状态？能否调用和用户按钮相同的动作？能否在执行前让用户确认？执行结果是否立即反映到 UI？同一动作能否被 MCP 或 A2A 暴露给外部 Agent？

如果这些都做不到，聊天框只是客服入口；如果这些都做到，应用本身就开始变成 Agent-native。Agent-Native 把 action、shared SQL state、chat runtime、skills、memory、jobs、observability、handoffs 放在同一框架里，目的就是避免 Agent 和 UI 变成两套系统。

上手路径

npx @agent-native/core@latest create my-app
cd my-app
pnpm install
pnpm dev

create 命令会让你选择起点：完整模板、Chat、Headless，或者指定 --template mail、--headless、--standalone。对工程团队来说，我更建议先用 Headless 或 Chat 理解 Action 和 Agent loop，再看 Mail、Plan、Clips 这些复杂模板。

模板真正提供的是产品场景，不只是 demo

  • Clips：录屏、自动转写、浏览器 debug logs，Agent 能读取时间轴和画面上下文去修 bug。
  • Plan：给 coding agent 做可视化计划和 recap，包含图、线框、注释和 review link。
  • Design：生成和比较交互式 HTML 原型。
  • Content：本地 Markdown/MDX 内容编辑和 Agent 辅助发布。
  • Analytics：连接数据源，生成图表和可复用 dashboard。
  • Mail / Calendar / Forms：验证 Action、认证、共享状态和业务操作如何落在真实应用里。

这些模板的价值在于把 Agent 放进具体任务，而不是展示一个万能聊天助手。Agent-native 的关键是领域动作明确：邮件怎么回、计划怎么审、录屏怎么转成修复上下文、图表怎么复用。

安全边界：Action 越统一，越要管权限

Action 统一之后，风险也更集中。仓库里的 skill 文档对安全边界写得很细：每个 Action 用 schema 做输入校验；不要把用户输入拼 SQL；server-side fetch 要走 SSRF guard；用户 API key 不能进 process.env，应进入加密 credential / vault / OAuth token 存储；UI-only action 可以用 agentTool: false 从模型工具列表里隐藏。

这部分决定了框架能不能进入真实产品。Agent 调用的不是玩具函数，而是能改数据、发邮件、跑任务的应用能力。如果权限、审计和工具面不收窄，所谓 agent-native 很快会变成风险放大器。

MCP、A2A、CLI、HTTP：同一个 Action 的不同出口

Agent-Native 的一个重要取向，是让同一操作可以暴露给多种表面：用户点按钮、前端 hook 调用、HTTP 请求、CLI、MCP tools/call、A2A agent message。区别不在业务实现，而在调用者身份、授权和展示方式。

这非常适合未来的多 Agent 工作流。一个 Analytics app 可以通过 A2A 暴露“查询数据”能力；一个 Mail app 可以通过 MCP 暴露只读邮件检索；同一套 action 仍然保留应用内部的校验、审计和权限。

观测和评测不是附加功能

项目的 observability 文档把 agent run、LLM call、tool call 拆成 trace，并强调 prompt、tool args、tool results 默认应谨慎采集。它还提供反馈、自动 eval、dataset eval、CI gate 这类能力。这个方向是对的：Agent 应用上线后，问题通常不是“能不能生成回复”，而是质量什么时候退化、工具为什么失败、哪类任务成本异常、用户在哪一步不满意。

如果要把 Agent-Native 用到生产，我会把 eval 当作上线条件，而不是发布后的补丁：关键 action 做契约测试，核心任务写 *.eval.ts，线上 trace 抽样看 tool success rate、latency、cost 和 error recovery。

适合谁，不适合谁

  • 适合：正在做业务型 Agent 应用，需要 UI、数据、工具、权限和 Agent 共用一套操作语义的团队。
  • 适合：想让 SaaS 产品从“带聊天框”升级为“Agent 能真正操作应用”的团队。
  • 适合：需要 MCP/A2A/CLI/HTTP 多出口，但不想维护多套业务实现的团队。
  • 不适合：只想做一个一次性聊天机器人、纯后端 Agent runner 或简单脚本。
  • 不适合：还没准备好处理权限、审计、状态同步和 eval 的团队。

结论

Agent-Native 的价值在于把“Agent 能做什么”这个问题拉回应用架构。真正的 agent-native app 不是聊天框加工具列表，而是 UI 和 Agent 共用同一批可验证动作、同一份状态、同一套权限和同一个观测面。随着 MCP、A2A 和前端 Agent 交互继续扩散，这种 action-first 的应用框架会进入更多工程团队的技术评估清单。