一个框架三种形态：API、聊天、SaaS，agent-native 想通吃？

一个框架三种形态API、聊天、SaaSagent-native 想通吃【免费下载链接】agent-nativeA framework for building agentic apps项目地址: https://gitcode.com/GitHub_Trending/ag/agent-native当行业还在争论Agent 到底应该长在对话框里、长在 API 网关后面还是长成一整个产品时Builder.io 开源的 agent-native 给出了一个略显贪心的答案三种都要。作为一款定位为构建 agentic 应用的 TypeScript 框架它宣称开发者只需把每个能力定义一次就能同时获得无界面 API、富对话界面和完整 SaaS 应用三种形态——agent 把它当工具调用UI 把它当函数调用HTTP、MCP、A2A、CLI 各取所需。一次定义、处处可用的口号在工具链里并不新鲜但真正落到三种产品形态共享同一份业务逻辑的框架并不多。本文不打算复述宣传语而是直接进入仓库源码与官方文档拆解这套统一 Action 架构如何支撑三种形态以及形态切换背后到底要付出什么代价。三种形态共享一条 Action 主线agent-native 的整个设计都建立在一个核心抽象上Action。在官方架构文档中框架被明确划分为三层——Core框架本身actions、PostgreSQL/PGlite、Drizzle、auth、应用状态、Agent 执行、路由与实时同步、Toolkit可复用的 UI 与产品系统组件、Templates构建在 Core 之上的完整领域应用。而贯穿这三层的是同一份 Action 注册表。一个最简 Action 长这样直接来自仓库里的真实模板文件// community-templates/account-expert/actions/hello.ts import { defineAction } from agent-native/core/action; import { z } from zod; export default defineAction({ description: Return a friendly greeting., mcpTool: true, schema: z.object({ name: z.string().default(world).describe(Name to greet), }), http: { method: GET }, run: async ({ name }) { return { message: Hello, ${name}! }; }, });这段代码没有注册表、没有 index 文件、没有路由配置。框架在启动时扫描actions/目录并自动挂载每个文件见 Actions 总览随后同一个defineAction()会扇出到六个消费方Agent 工具Agent 依据 zod 推导出的 JSON Schema 调用它前端 HookuseActionQuery(hello, { name: Alex })带完整类型推断框架传输层自动挂载在/_agent-native/actions/helloCLI 命令pnpm action hello --nameAlexMCP 工具任何 MCP 兼容宿主Claude、Cursor、Codex可直接发现并调用A2A 工具工作区内其他 agent-native 应用可跨应用委托。更关键的是架构层面的对比传统应用里前端只调用自己的 API 层Agent 想获得同样的能力必须再写一套独立集成而在 agent-native 中UI 和 Agent 调用的是同一个 action、同一张 SQL 表只有一个实现要写只有一个地方可能藏 bug——这是它敢于宣称三种形态通吃的底层逻辑。API 形态无浏览器但绝不是无状态API 形态对应官方文档里的 Automation-first 路径脚手架命令是npx --yes agent-native/corelatest create my-agent --headless社区情报中关于 agent-native 的描述经常出现可构建无界面 API的说法但仓库文档《Automation-First Apps》里有一句被反复强调的话值得注意Automation-first 并不意味着无状态。会话、线程、运行记录、设置、凭据、应用状态、分享记录全部落在 SQL 里——本地开发用 PGlite生产环境用持久化 PostgreSQL。在这种形态下API 层根本不需要单独构建。每一个defineAction天生就是一个 HTTP 端点curl -sS -X POST https://your-app.example.com/_agent-native/actions/summarize-week \ -H Authorization: Bearer $AGENT_NATIVE_TOKEN \ -H Content-Type: application/json \ -d {formId: form_123}关于鉴权HTTP API 文档给出了一个值得注意的细节connectCLI 可以签发两类令牌——绑定个人身份的 Personal Token以及绑定组织合成身份的 Org Service Token。后者的设计意图很直白CI、客服机器人、定时集成这类人走了还得继续跑的场景token 的 subject 是svc-support-deskservice.orgId即使签发者离职或撤销个人令牌也不受影响。这说明框架对API 形态的思考不是简单地把 chat 端点暴露出去而是把它当作一个需要身份治理的生产级集成面。同样的能力也可以整段交给 Agentpnpm agent Summarize this weeks forms.会在项目文件夹里直接跑完整的 app-agent 循环而如果另一个服务需要调用整个 Agent 而非单个 action可以用agentNative.invoke()或runAgentLoop()来自agent-native/core/server自行驱动循环。至于更细粒度的协议选择MCP 文档说明每个部署的应用会自动挂载/mcp端点并提供ask-agent元工具把复杂任务委托给完整 Agent 循环。聊天形态Agent 与 UI 共享同一个会话聊天形态是官方推荐的默认入口脚手架命令npx --yes agent-native/corelatest create my-app --standalone --template chat共享在这个形态下有三个层次构成了核心概念文档所谓的五个架构规则中的关键部分共享 Actions。用户在聊天里说Call the hello action for AlexAgent 依据 description 和 schema 找到 action 并执行用户在页面上点击按钮React 通过useActionMutation调用同一个 action。两条路径走同一份校验、同一份权限、同一份实现。共享数据。Agent 干的活出现在 UI 里UI 里干的活 Agent 也能读到因为双方读写的是同一张 PostgreSQL 表。框架通过/_agent-native/events走 SSE 流式推送并保留轮询作为通用兜底——实时同步文档里明确说这条链路在所有部署环境都工作包括 serverless 和 edge因为它依赖数据库而非内存状态或文件系统监听。共享应用状态。这是最容易被忽视的一层。UI 在每次路由变化时向application_state表写入一条navigation记录Agent 在行动前通过view-screenaction 读取它。仓库模板中的实现很直观// community-templates/account-expert/actions/view-screen.ts export default defineAction({ description: See what the user is currently looking at on screen. Returns the current navigation state for the chat-first app. Always call this first before taking any action., schema: z.object({}), http: false, readOnly: true, run: async () { const navigation await readAppState(navigation); ... return screen; }, });这解决了编辑这个到底指哪个对象这个经典歧义Agent 不是盲猜而是读取用户当前聚焦的线程、图表或文档。Agent 不点击 UI它通过和 UI 相同的 action 层工作——这句话是整套设计的公约数。SaaS 形态开箱即用的可克隆产品第三种形态最重也最激进。它不再是一个脚手架而是一整套可直接改品牌上线的产品。官方称之为Cloneable SaaS从完成品而不是空模板开始。仓库里的templates/目录提供了完整的领域应用——Mail智能收件箱、Calendar智能日历、ContentMDX 笔记、Brain企业知识问答、Slides演示文稿、Analytics数据分析、Clips会议录制、Design设计原型、Forms表单、Plan可视化计划、Dispatch工作区控制台等。这类模板自带什么Templates 文档和核心概念文档列出的清单包括SQL 状态、上下文感知、实时同步、深链、原生聊天组件、生成式 UI、认证与组织权限Better Auth orgs/members/roles/RBAC、技能与记忆、自动化任务、Agent 团队、MCP 双向接入、跨应用 A2A 委托。对一个 SaaS 团队来说这些恰好是每个产品都要做一遍但又不想做的横切能力。值得注意的是生态层的设计community-templates/目录里的示例如 account-expert与官方模板走同一套框架接口而社区模板机制允许任何人把自己的仓库变成模板源CLI 通过--template community:owner/repo#v1.2.0直接安装并可 pin 分支、标签或 commit。换句话说SaaS 形态不仅是拿来即用还具备成为别人的起点的传播属性——这解释了为什么社区文章会反复强调技能复用、自我进化与 Monorepo 工作区能力。形态切换的代价配置复杂度与部署取舍三种形态共享 Action 层听起来像是一次开发、三处交付。但仓库文档在几个关键位置诚实标注了边界这些细节恰恰是评估框架时最该读的部分。第一--headless只是脚手架选择不是运行时模式。《Automation-First Apps》明确写道--headless只选择初始脚手架不选择不同的架构且不存在把 action-only 项目原地转换为浏览器应用的agent-native命令。当产品需要 UI 时官方路径是用 Chat 模板作为迁移参考把模板的 shell、server 插件和 UI 依赖引进来然后保留你的 action 名称、Zod schema、SQL 数据、instructions 和 skills。合同被刻意保持为可移植的——但迁移工作仍然真实存在不是零成本。第二部署形态与数据层绑定。框架基于 Nitro 构建可以编译到 Node.js、serverless 函数、edge worker、Docker、Vercel、Netlify、Cloudflare Workers 等目标见 Deployment 文档。但本地开发用的 PGlitedata/pglite在容器、预览环境和 serverless 文件系统里都可能随时被重置因此每个部署的应用都需要持久化 PostgreSQL。上线前要配置的远不止一个连接串DATABASE_URL、BETTER_AUTH_SECRET用openssl rand -hex 32生成、工作区场景的A2A_SECRET还要在首次访问前运行pnpm migrate:production。三种形态在部署层的共同点是全部状态进 SQL这条硬约束。第三安全与治理不免费。社区对 agent-native 的一篇使用介绍2026-09明确指出项目不替代安全治理与低代码平台权限、审计与部署仍需开发者自行实现。这与仓库的自我定位一致——框架提供 auth 骨架和 access 守卫的复用模式如server/lib/access.ts中的accessFilter、assertAccess、authorize但业务级的细粒度权限边界由应用自己定义。例如 account-expert 模板里对 Slack 写操作的审批逻辑就是业务代码显式声明的// community-templates/account-expert/actions/provider-api-request.ts export function requiresProviderApiApproval(args: { method: string }): boolean { return args.method ! GET args.method ! HEAD; }非幂等的写操作触发审批流读操作放行——这种操作即策略的模式是框架留给开发者的设计空间也是形态自由背后真正的配置成本所在。结语通吃的不是形态是那份契约回到标题的问题agent-native 想通吃 API、聊天、SaaS 三种形态吗从产品野心看确实如此但从架构看通吃的并不是三种界面——而是那份Action SQL 状态 上下文感知的契约。无界面的定时任务、聊天里的实时协作者、完整产品里的仪表盘最终都汇聚到同一个defineAction()和同一张数据库表。这种设计真正省下的是传统架构里UI 一套 API、Agent 一套集成、外部系统再一套封装的重复劳动而真正要付的代价是理解这套契约、接受一切状态入 SQL的约束以及为三种形态分别做权限、审计与部署治理。至于这个取舍是否划算取决于你的产品里 Agent 与 UI 是否真的在持续处理同一份工作——如果是它可能是当前把这种耦合做得最彻底的框架之一。【免费下载链接】agent-nativeA framework for building agentic apps项目地址: https://gitcode.com/GitHub_Trending/ag/agent-native创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考