Agent-Native（BuilderIO/agent-native）：让 UI 与智能体共用一个「动作层」

一、导读

Agent-Native 是 Builder.io 开源的 TypeScript 框架，核心主张只有一句话：把应用里每一件"能做的事"定义成一个 action，它同时成为智能体的工具、React 的 hook、HTTP 端点、MCP 工具、A2A 工具和 CLI 命令。它当日涨星 607（Trending daily，2026-09-21 快照），累计 5,838 星（GitHub API，2026-09-21T22:02Z 抓取），而建仓时间是 2026-03-12——不到半年。它值得研究的地方在于：多数"给应用加 AI"的路线是把聊天框钉在右上角，而它选择重构应用的调用面，让人类和智能体走同一条代码路径，并为此写了一套约 40 个停止条件的智能体运行时。

二、项目速览

项目	详情
仓库	BuilderIO/agent-native（官网与文档 agent-native.com；npm 包 @agent-native/core）
定位	"agentic application framework"：让 UI 与智能体共用动作、数据与权限的全栈框架
作者/团队	Builder.io（曾做 Visual Copilot、Mitosis、Qwik 的开发者工具公司）
主语言	TypeScript（pnpm monorepo；服务端 Nitro，数据层 Drizzle ORM + PostgreSQL）
Star 总数	5,838（GitHub API，2026-09-21T22:02Z；fork 534，开放 issue 90）
当日涨星	+607（GitHub Trending daily，2026-09-21 快照，候选池第 3）
License	MIT（README 与 npm 元数据均标注 MIT；GitHub API 的 license 字段为空、仓库根目录未见 LICENSE 文件，待确认）
首次发布	仓库创建于 2026-03-12；npm 首个版本同日发布（registry 时间戳 2026-03-12T15:22Z）
版本与包体	@agent-native/core 最新 0.183.0，另有 nightly 通道（0.184.0-nightly-20260921210811）；npm 上累计 1,553 个版本
下载量	近 30 天 174,075 次（npm registry，统计区间 2026-08-22 至 2026-09-20）
仓库规模	约 356 MB（GitHub API size），21 个 packages、17 个官方模板应用、213 篇框架文档

三、为什么是它

它抓的是"聊天框困境"。 Builder.io 的官方博客把软件分成三段：AI-enabled（产品照旧运转，只是多了 AI 功能）、AI-native（抽掉 AI 产品就塌）、agent-native（AI 是核心，同时存在完整的人类界面，且两者共享动作、数据与权限）。判据也很直白：抽掉 AI 产品还能用 → AI-enabled；不能用 → AI-native；UI 和智能体都能操作同一套工作流 → agent-native。这条界线解释了为什么很多"AI 功能"天花板很低：角落里的聊天框既看不到用户正在看的记录，也无法通过产品自身的原语改数据。

第二，它把"重复实现"当成架构债务来还。 传统做法要写四份同样的逻辑：一份 REST 路由给前端、一份工具定义给模型、一份 UI mutation、一份脚本。Agent-Native 的做法是只写一份 defineAction()，由框架扇出到七个调用面。创始人 Steve Sewell 在自己博客里给的演进阶梯同样是这个逻辑：单次 LLM 调用 → 工具加循环 → 流式结果加人工反馈 → 再补上指令/技能/记忆等定制层，最后才是 agent-native 应用。

第三，它踩在 MCP/A2A 的生态节拍上。 当 MCP 成为"把能力交给智能体"的事实标准后，"我的应用如何变成智能体可调用的工具"成了新问题。这个框架把 MCP、A2A、CLI 与 UI 一起做成同一个 action 的出口，等于把这个问题下沉到框架层解决。

涨星动因可归为三条：命名与话语权（agent-native 这个提法正在被广泛引用，作者本人的概念文章与框架同名互相导流）、可直接运行的产品化程度（17 个模板都是完整可部署的 SaaS 形态应用，而非脚手架）、以及发布频率极高带来的可见度（2026-09-21 一天内就发布了 toolkit、skills、scheduling、dispatch、pinpoint、recap-cli、creative-context 等多个包的新版本）。需要克制看待的是：6 个月、0.183 版本号，意味着 API 仍在漂移期。

四、架构原理

4.1 整体架构：一个动作面，七个出口

框架的全部设计都围绕一个取舍展开——应用的能力只定义一次，所有调用者共享它。数据流可以概括为：UI 与智能体循环都调用同一批 action，action 通过同一个 Drizzle 客户端读写同一批 PostgreSQL 表；同步则靠 SSE（带轮询兜底）。

┌────────────────────────────────────────────────────────────────────┐
│ 调用面（Callers）                                                  │
│   浏览器 / React UI        Agent Loop（chat / automation / team）  │
│        │                            │                              │
│        ▼                            ▼                              │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ Actions 层（actions/*.ts，框架自动发现并挂载）               │  │
│  │  defineAction({ description, schema(Zod), run(args, ctx) })  │  │
│  │  职责：输入校验 · 权限判定(authorize) · 审批(needsApproval)  │  │
│  │        · 审计 · 数据库读写(getDb + Drizzle)                  │  │
│  └──────────────────────────────────────────────────────────────┘  │
│        │              │            │         │        │       │    │
│        ▼              ▼            ▼         ▼        ▼       ▼    │
│  React hooks    内部 HTTP      MCP 工具   A2A 工具  CLI   原生聊天UI│
│  useActionQuery /_agent-native MCP host  别的       pnpm   chatUI  │
│  useActionMut.  /actions/<n>  客户端     app       action  renderer │
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ 运行时与基础设施                                             │  │
│  │  Nitro 服务器 · PostgreSQL（生产）/ PGlite（本地）· Drizzle  │  │
│  │  鉴权与作用域密钥库 · 审计日志 · SSE 实时同步 · 后台任务     │  │
│  └──────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────┘

第二条关键数据流是上下文回灌：UI 在路由变化、选中记录时写入轻量状态键（navigation、__url__、selection），智能体侧用 view-screen 这个 action 把它们水合成真实记录，于是"总结这一个"有了明确指代；反向由智能体发出一次性 navigate 命令驱动 UI 跳转。这套机制让智能体不必去"看屏幕点像素"，而是在类型化的动作上操作。

4.2 分层模块拆解

① Actions 层（框架的原子单位）。 一个 action 由 description（给模型读的用途说明）、schema（Zod/Standard Schema，既校验输入也转成 JSON Schema 给模型）、run(args, ctx)（唯一实现）构成；可选字段还包括 http（改挂载方法/路径或彻底关闭 HTTP 端点）、readOnly（GET 时自动为真，跳过轮询刷新与写审计）、outputSchema 与 outputErrorStrategy（warn/strict/fallback）、parallelSafe（允许与同轮其他工具调用并发）。放在 actions/ 目录里的文件由框架启动时自动发现，无需手写注册。

② 权限与审批（六开关）。 这是整个设计里最"工程化"的部分：agentTool（默认 true，置 false 则模型看不到，但 UI/HTTP/CLI 仍可调用）、mcpTool（默认继承 agentTool，控制是否暴露给外部 MCP/A2A 调用方）、toolCallable（只管扩展 iframe 桥）、publicAgent: { expose: true }（加入公开 MCP/A2A/OpenAPI 面，适合无需鉴权的安全读取）、needsApproval（智能体在调用点暂停，等人批准）、authorize（守卫函数，在每个调用面生效）。此外 ctx.caller 会告诉实现"这次是谁调的"（tool / http / frontend / cli / mcp / a2a），因此同一个 action 可以对人宽松、对智能体收紧，而不必拆成两个实现。

③ 智能体运行时。 循环本体在 packages/core/src/agent/production-agent.ts，基础停止条件只有三个：模型不再请求工具（正常完成）、maxIterations（400 轮）、maxRunInputTokens（2000 万输入 token）。但官方专门写了一篇《Agent run stop conditions》文档，坦承另外还有约 40 个停止条件，分布在六层：L0 进程外 reaper、L1 引擎、L2 智能体循环、L3 恢复包装器、L4 运行管理器、L5 跨调用的回合账本、L6 客户端跟随循环。之所以需要它们，是因为"进程会被杀、传输会撒谎、模型会打转、死进程不会写下结局"：托管环境的前台函数约 57–60 秒就被切断，而一次有意义的智能体回合往往更长，于是必须把回合切片、记录账本、可恢复续跑，并由心跳与 reaper 从外部判定"这次运行已死"。

④ 状态与数据。 生产用 PostgreSQL，本地默认 PGlite（进程内 WASM 版 Postgres，DATABASE_URL=pglite:./data/pglite），托管可选 Neon、Supabase、RDS、Cloud SQL、Azure 等；UI 与智能体使用同一个 getDb() 客户端和同一批表。所有 SQL 必须兼容 PostgreSQL——这是框架明确的约束，也是"后端无关"的边界所在。

⑤ 周边包（monorepo 21 个）。 除 core 外，toolkit 提供协作/分享/团队/可观测等可复用积木，skills 提供技能机制，dispatch 是工作区控制面（保险库、集成、定时任务、跨应用委派），scheduling 负责事件与预约，embedding 把应用/智能体嵌进别的产品，migrate 是可恢复的存量迁移工作台，另有 desktop-app、mobile-app、vscode-extension 与浏览器扩展等。templates/ 下 17 个模板（mail、calendar、clips、design、slides、analytics 等）是可直接部署的产品起点。

4.3 核心机制与算法原理

动作定义。 官方模板里的写法是这样的（含权限与审批字段）：

// actions/reply-to-email.ts
import { defineAction } from "@agent-native/core/action";
import { z } from "zod";
import { getDb, schema } from "../server/db/index.js";

export default defineAction({
  description: "Reply to an email thread in the user's voice.",
  schema: z.object({
    emailId: z.string().describe("The id of the email to reply to."),
    body: z.string().describe("The reply body, in markdown."),
  }),
  needsApproval: true,          // 智能体调到这里会暂停，等人类批准
  http: { method: "POST" },
  run: async ({ emailId, body }, ctx) => {
    const db = getDb();
    await db.insert(schema.replies).values({ emailId, body });
    return { ok: true, caller: ctx.caller };   // ctx.caller: tool/http/frontend/cli/mcp/a2a
  },
});

同一份定义换来六种调用方式：

// React：点击与聊天走同一段实现
const { data } = useActionQuery("hello", { name: "Alex" });
const { mutate } = useActionMutation("reply-to-email");

# CLI：脚本、cron、手工验证
pnpm action reply-to-email --emailId=42 --body="thanks!"
# 框架自动挂载的 HTTP 端点
# POST http://localhost:8080/_agent-native/actions/reply-to-email

自动化（Automations）。 触发分两类：schedule（cron）与事件（如 calendar.booking.created）。中间可以让一个便宜模型做自然语言条件判断——官方示例是"邮箱以 @builder.io 结尾"这类条件交给 Haiku 判定，通过后才由智能体带完整工具权限执行主体，且自动化里的 MCP 访问被限制在显式 mcpTools 白名单内。这是一处很典型的工程取舍：用"条件门"挡住绝大多数无效触发，从而压低成本。

打转防护。 循环层对重复行为有硬性上限：同一工具加同一参数重复 8 次即终止（MAX_IDENTICAL_TOOL_CALLS），同一工具加同一错误重复 3 次即把错误注入回模型（MAX_IDENTICAL_TOOL_ERRORS），跨参数同一错误达到 6 次终止，写工具被打断 2 次终止。另有 90 秒级的"无进展"看门狗（模型流与工具参数准备各一套）、前台首帧 25 秒超时、参数流零字节重启上限 2 次。这些常量的意义在于：智能体最常见的失败不是"想得不够深"，而是在死角里反复摩擦。

长任务的切片与恢复。 由于托管平台会掐断长请求，框架把长回合切块：前台请求在约 40 秒软超时后交还客户端续跑，或者在 Netlify 上启用"持久后台运行"，把回合派发到有 15 分钟预算的独立后台函数（HMAC 派发，前台保留熔断兜底）。这套机制由 AGENT_CHAT_DURABLE_BACKGROUND 开关控制，部署在 Netlify 时默认开启。

4.4 性能优化手段与设计取舍

取舍一：用"少写一套实现"换"框架绑定"。 一个 action 服务所有调用面，收益是逻辑不漂移、权限无旁路；代价是你的能力必须长得像 action，且必须接受框架的 schema、运行时和数据库约定。

取舍二：把复杂度从业务代码搬进运行时。 切片续跑、账本、reaper、多重看门狗让"长回合"可用，但官方自己承认这些停止条件最糟的地方不是存在，而是它们在不同层被陆续加进来、各看各自的时钟，顺序只写在文档里而没有强制。这份自陈是理解该框架成熟度的关键证据：它能跑生产形态的模板，但运行时的"止损体系"仍在收敛。

取舍三：以 PostgreSQL 为唯一状态事实源。 换来 UI 与智能体共享数据、实时同步简单；代价是失去对其他存储形态的适配弹性（README 的"后端无关"指的是托管平台与 Postgres 供应商，而非数据库类型）。

取舍四：模板即产品，而不是脚手架。 17 个模板都是完整应用（含 Drizzle schema、actions、UI），优点是起点可运行、可对照，代价是仓库体积大（约 356 MB）、模板与框架版本需同步维护（官方有 syncing-template-changes 文档）。

4.5 与其他架构路线的差异

CopilotKit 这一派解决 UI 层：它把自己定位成"面向产品的前端智能体 UX 层"，后端智能体来自 Mastra/LangGraph 等，通过 AG-UI 连接（第三方分析亦持此观点）。也就是说它同样关注"智能体进入应用界面"，但动作与状态分散在前后端两侧，需要你自行保持一致性；Agent-Native 的差异是把动作与数据放在同一个定义里，并额外管到数据库、任务与部署。

Mastra / LangGraph 这一派解决智能体侧：记忆、工具、工作流、追踪与评测齐全，但不提供产品界面，也不规定应用能力如何暴露给人类。

Vercel AI SDK 是 SDK 而非框架：UI 与流式能力很强，但持久化、权限、后台任务、协议暴露都要自己搭。

Claude Agent SDK / Codex 这类编码智能体工具面与循环质量很强，但没有产品化 UI 与多租户形态；Agent-Native 的思路近似于把"编码智能体的工作环境"搬进业务应用（仓库里同时存在 .claude-plugin/、.codex/、AGENTS.md、skills/ 等目录，本身就用编码智能体开发）。

五、应用场景

场景一：把"AI 侧边栏"改造成共享动作

痛点：产品里已经有一个聊天助手，但它看不到用户正在看的记录，也无法通过产品自身的接口改数据；同时团队维护着两套能力：给 UI 的 REST 接口和给模型的工具定义。 做法：把核心操作收拢成 actions/*.ts，前端改用 hooks 调用，模型侧自动获得工具定义。

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

// 同一个 action：按钮调用、智能体调用，参数校验与权限完全一致
const { mutate } = useActionMutation("update-task");
await mutate({ taskId: "t_18", status: "done" });

收益与量化：同类操作从"两套实现"降到一套；新增能力的边际成本从"接口 + 工具定义 + 提示词"降为一个文件。官方文档给出的标准 HTTP 挂载点是 /_agent-native/actions/<name>，可直接被脚本或外部系统复用。落地时的稳妥路径是先挑 3–5 个只读 action 试点（如查询列表、读取记录），确认前后端调用一致后再迁移写操作。边界：这是重构而非插件式加装，存量系统需要按 action 重新切分能力；数据库须为 PostgreSQL。

场景二：给高风险操作加"人在环上"审批

痛点：让智能体自动发邮件、改合同状态、删数据，团队普遍不敢开；用提示词写"请先询问用户"在模型层不可靠。 做法：在 action 上声明 needsApproval: true，让智能体在调用点暂停等人批准；用 authorize 守卫限定角色；用 agentTool: false 把某些操作从模型视野里彻底移除（UI 仍可调用）。

export default defineAction({
  description: "Send the drafted reply to the customer.",
  schema: z.object({ replyId: z.string() }),
  needsApproval: true,                       // 人在环上
  authorize: ({ ctx }) => ctx.user?.role === "support_lead",
  run: async ({ replyId }, ctx) => send(replyId, ctx),
});

收益与量化：审批与授权发生在框架层而非提示词层，且守卫在 UI、HTTP、MCP、A2A、CLI 全部调用面生效——不存在"绕过路径"；所有写操作默认进入审计日志（谁、何时、从哪个调用面、哪个对话线程），而审计日志本身又可通过内置 action 查询，合规取数不必另建管道。边界：审批会打断自动化链路，不适合高频低风险操作；needsApproval 的排队与超时体验需自行设计。

场景三：把周期性工作交给事件与定时自动化

痛点：日报、对账、客户跟进这类工作靠人记得做；而传统 workflow 引擎写条件时又要拖拽一堆分支。 做法：用 automations 声明触发（cron 或事件）+ 自然语言条件，条件用便宜模型判定，主体由智能体带工具执行。

事件：calendar.booking.created
条件（自然语言）："来客邮箱以 @builder.io 结尾，且会议时长超过 30 分钟"
主体：调用 lookup-crm 取客户背景 → 生成会前简报 → 写入 briefing 表 → 通知负责人

收益与量化：条件判断下沉到小模型（官方示例用 Haiku），把"绝大多数不该触发的请求"挡在昂贵的智能体回合之前；长回合可走 15 分钟预算的后台函数，避免被前台超时切断。边界：自动化内的 MCP 访问受显式 mcpTools 白名单约束，能力范围需预先声明；定时任务依赖宿主平台的调度能力。

场景四：把应用能力作为 MCP/A2A 工具交给外部智能体

痛点：客户希望在 Claude Desktop、Cursor 或自家智能体里直接操作你的产品；逐个写 MCP server 很重，且要单独做权限。 做法：action 默认就是 MCP 工具（mcpTool 默认继承 agentTool）；只读且无需鉴权的动作可用 publicAgent: { expose: true } 开放；跨应用委派走 A2A，由工作区控制面（dispatch）管理跨应用的目标与凭据。

export default defineAction({
  description: "Read the current inventory levels for a SKU.",
  schema: z.object({ sku: z.string() }),
  readOnly: true,
  publicAgent: { expose: true },   // 加入公开 MCP/A2A/OpenAPI 面
  run: async ({ sku }) => getInventory(sku),
});

收益与量化：一份实现同时服务自家 UI、自家智能体和外部 MCP 客户端，权限与校验不分叉；另一个 Agent-Native 应用也能通过 A2A 发现并调用它，等于把"多应用协作"变成内部调用；仓库内置 mcp-registry/server.schema.json（对齐 modelcontextprotocol 的 2025-12-11 schema）便于登记。边界：公开面等于对外承诺接口稳定性，应只开放只读或低频工具；协议侧安全（鉴权、限流、审计）仍需运维配合。

场景五：从模板克隆一个垂直 SaaS

痛点：小团队想做一个"带智能体的垂直工具"（录屏转写、设计稿生成、演示文稿、内容编辑），但从零搭 UI + 数据 + 任务 + 权限要几个月。 做法：直接以官方模板为起点，保留其可运行形态，再用编码智能体按业务改写（仓库自带 AGENTS.md、CLAUDE.md、skills/ 与 .claude-plugin/，编码智能体能直接读懂项目约定）。

npx --yes @agent-native/core@latest create clips-app --standalone --template clips
# 生产数据库（本地不设则自动用 PGlite）
echo 'DATABASE_URL=postgres://user:pass@host:5432/db' >> .env
pnpm build && pnpm start

收益与量化：模板自带鉴权、持久化会话、实时同步、应用上下文与 actions/ 目录，属于"可部署的产品形态"而非空骨架；官方提供 17 个方向（mail、calendar、analytics、slides、design、content、crm、videos 等）供对照。边界：模板与框架版本之间需要同步（官方有专门的同步文档与工具），自建产品要保持这套同步纪律；模型、数据库、托管都要自带，框架不提供额度。

六、快速上手

# 1) 环境：Node.js >= 22、pnpm >= 10
npx --yes @agent-native/core@latest create my-app --standalone --template chat
cd my-app && corepack enable && pnpm install

# 2) 起开发服务器（默认 8080，被占用会自动递增；本地选 "Continue as local dev"）
pnpm dev

# 3) 连接模型：界面里用 Builder.io 免费额度，或填 Anthropic/OpenAI key，或指向本地 Ollama

# 4) 在聊天里验证动作被模型调用："Call the hello action for Alex."

# 5) 从 CLI 直接调同一个动作（可写进 cron）
pnpm action hello --name=Alex

# 6) 本地数据库默认 PGlite；要指定 Postgres 就设 DATABASE_URL
#    DATABASE_URL=postgres://user:pass@host:5432/db

七、横向对比

维度	Agent-Native	CopilotKit	Vercel AI SDK	Mastra / LangGraph	Claude Agent SDK
定位	全栈 agentic 应用框架	面向产品的前端智能体 UX 层	模型调用与流式 UI 的 SDK	智能体编排框架	编码/通用智能体 SDK
动作与人机共享	一个 defineAction 扇出 UI/Agent/HTTP/MCP/A2A/CLI	前端工具与共享状态（前端侧）	需自行设计	无 UI 概念	无产品 UI 概念
数据与持久化	内置 PostgreSQL + Drizzle、SSE 同步	交由后端框架	无	视框架（Mastra 提供记忆/存储）	无
权限与审批	六开关 + authorize 守卫（全调用面生效）+ 审计	前端工具与人工确认	无	无	权限由宿主提供
长任务	切片续跑 + 15 分钟后台函数 + 账本/reaper	依赖后端	无	视框架	视宿主
许可与成本	MIT（本体免费，自带模型/托管）	MIT，★37,454（2026-09-21 抓取）	★26,877	Mastra ★28,246；LangGraph ★42,097	★8,144（Python 版，2026-09-21 抓取）
生态成熟度	6 个月、0.183 版本，API 漂移期	3 年+，生态与集成更成熟	3 年+，事实标准级 SDK	2–3 年，社区大	1 年+，一线编码体验

对比口径说明：星数均为 GitHub API 于 2026-09-21T22:02Z 抓取的同一时刻快照；CopilotKit 的定位描述引述第三方分析（Developers Digest，2026-05-30）与其官方文档口径。

八、局限、风险与社区观察

非常年轻，API 仍在漂移期。 仓库 2026-03-12 建仓，不到半年内 npm 上出现 1,553 个版本（含 nightly），一天内多个包同时发版。0.x 语义化版本意味着破坏性变更随时可能发生，生产采用必须锁版本并准备跟进成本。

License 元数据存在不一致。 README 写明 MIT，npm 元数据也是 MIT，但 GitHub API 的 license 字段为空、仓库根目录未见 LICENSE 文件（2026-09-21 核查）。这不构成法律障碍的判断依据，但企业合规审查前建议向作者确认（待确认）。

运行时复杂度是官方自陈的痛点。 那篇《Agent run stop conditions》直言：同一类"健康运行被看门狗杀掉"的 bug 在四个月内至少修了六次，问题的根源是停止条件层层叠加、各看各的时钟。这意味着在长任务、边缘网络、Serverless 冷启动等场景下，仍可能遇到"回合被误杀或无法续跑"的问题。

托管相关能力有平台绑定。 15 分钟后台运行的实现目前明确面向 Netlify 后台函数（默认开启、有前台熔断），其他平台要走切片续跑路径；"后端无关"的边界在托管与 Postgres 供应商，而不是数据库类型。

安全面变大。 一旦把 action 暴露为 MCP/A2A 或 publicAgent，产品安全边界就从"浏览器与服务器"扩展到"任何持有凭据的智能体"。框架提供了工具（六开关、守卫、审计、作用域密钥库），仓库里也有 docs/security.mdx 与"受信验收通道"（trusted acceptance lane，用于对具体 PR 在隔离托管环境做验收，目前试点标记为 enabled: false），但默认配置的安全性仍取决于开发者是否收紧。

缺少公开性能基准。 官方没有给出与 CopilotKit、Vercel AI SDK 等的吞吐/延迟基准对比；第三方评测（AgentConn、DEV 社区）以架构解读为主，量化数据有限。任何"更快"的说法都不应脑补，需要自测。

社区与公司动机。 框架由 Builder.io 主导，公司同时提供托管数据库与 Connect Builder.io 的免费额度入口——开源本体与商业化的边界清晰，但"框架路线图服务于公司产品"的可能性需纳入长期判断。

九、小结与行动建议

Agent-Native 的价值不在于"又一个 TypeScript 智能体框架"，而在于它把应用能力的定义权从"前端接口 + 模型工具 + 脚本"三份、收敛成一份 action，并把权限、审批、审计、协议暴露、长任务恢复都挂到这一份定义上。对于"要给产品加一个真正能操作业务的智能体"的团队，这是目前少见的、把这件事做到数据库与部署层的方案。

1. 先做一次能力盘点：把你应用里"人类能做的事"列成清单，标出哪些是安全的只读（适合 publicAgent）、哪些需要审批（needsApproval）、哪些绝不该给模型（agentTool: false）。这份清单比任何代码都重要。
2. 用 chat 模板跑一周再决策：npx --yes @agent-native/core@latest create my-app --standalone --template chat，同时接上真实数据库与真实模型 key，重点验证长回合、断流与续跑在你目标平台的表现。
3. 锁版本 + 建回归：固定 @agent-native/core 版本（避开 nightly），把关键 action 的输入输出写成测试；框架自身在快速演进，升级前先跑你的 action 契约测试。
4. 把审批与审计当验收项：任何会写外部副作用的 action 都要有 needsApproval 或 authorize，并确认审计日志能回答"谁、何时、从哪个调用面、哪个会话线程"。
5. 按需再上协议面：MCP/A2A 与 publicAgent 是加分项而非起步项；先把内部 UI 与自家智能体的共享动作跑顺，再考虑对外开放工具面。

资料来源（抓取日期 2026-09-21 至 2026-09-22）：GitHub Trending daily 页面（2026-09-21 快照）与 GitHub REST API（仓库元数据、packages/templates/docs 目录、Releases）；npm registry（@agent-native/core 版本与发布时间）与 npm downloads API（近 30 天 174,075 次）；仓库内 README.md、PRODUCT.md、DEVELOPMENT.md、docs/environment-variables.md、docs/agent-run-stop-conditions.md、docs/trusted-acceptance-lane.md，以及框架文档 packages/core/docs/content/ 下的 actions-overview.mdx、actions-defining.mdx、actions-access-control.mdx、actions-other-surfaces.mdx、agent-surfaces.mdx、context-awareness.mdx、server-database.mdx、automations.mdx、durable-background-runs.mdx、getting-started.mdx、what-is-agent-native.mdx；官方博客（builder.io：Vishwas Gopinath 2026-05-08 架构文、Steve Sewell 2026-04-21 实践文）；第三方评述（Sébastien Dubois 2026-08-07、DEV 社区 terminalchai 2026-09-20、AgentConn 目录页、Developers Digest 2026-05-30）。凡官方未给基准、或 API 口径不一致处（如 License 字段），文中已标注"待确认"。