企业官网建设流程全解析

从聊天框到能办事的智能体应用：Agent-Native 开发实践

【免费下载链接】agent-nativeA framework for building agentic apps项目地址: https://gitcode.com/GitHub_Trending/ag/agent-native

刚上线的智能体应用，最常见的尴尬是这样的：用户说"帮我约个会"，智能体聊了三轮还没动手；或者它真的约上了，你却说不出它是怎么约的。Agent-Native 是专门用来构建这类智能体应用的框架，模板、执行循环、调度、协作协议都内置在仓库里，以下做法全部来自这个仓库的真实目录结构。

智能体只会聊天、不会办事时

从成熟模板起步，而不是从空白页起步

新项目的第一步不是打开编辑器，而是把 templates/ 里现成的 13 个模板过一遍：chat、calendar、mail、analytics、forms 都在。每个模板都是独立应用，有自己的 package.json、数据库 schema、actions 和 UI。想做日程类功能，先读 templates/calendar/ 是怎么做的再改，比自己从零搭快得多，也不容易写出违背框架设计的代码。

让智能体的每次执行走同一个核心循环

用户问什么，智能体都要经历同一个循环：接请求、选动作、执行、记录结果。这个循环集中在 packages/core/src/agent/：production-agent.ts 组装执行链，run-manager.ts 和 run-store.ts 负责状态管理和失败后的恢复。写应用时别自己另起炉灶做循环，想把"执行失败时通知我"这类逻辑接进去，在这里扩展一次，所有功能都受益。

智能体开始办事之后，防止它"跑偏"

把功能拆成小 action，逐个配测试

"功能"在这里不是一个页面，而是一个个 action 文件。看 templates/calendar/actions/：check-availability.ts 只负责查可用时间，create-event.ts 只负责建事件，每个文件旁边都放着同名 .test.ts。你的智能体应用照这个来：一个 action 只做一件事、单独可测，智能体选到它时就不是黑盒，答非所问也好排查。

让定时任务自己跑起来

"每周一早上提醒我"这类需求靠调度机制，不靠你自己开定时器。packages/core/src/jobs/ 下有 scheduler.ts 和 cron.ts 负责按计划触发，run-history.ts 记录每次运行结果。新写定时功能时，把任务入口挂到这个目录里，运行历史、重试策略都是现成的。

把第三方服务接进统一集成层

不要给 Gmail 写一套调用、给 Google Calendar 再写一套。这个仓库把第三方服务统一收在 packages/core/src/integrations/：catalog.ts 管理可用集成清单，installations-store.ts 记录每个用户授权了哪些服务，adapters/ 目录放各服务的接入协议。

右边是 analytics 模板的数据源面板：Google Sheets、GA4、自定义 API 都从同一个入口接入，智能体查询数据时不用关心背后是哪家服务。

代码越滚越大、没人敢改时

按职责拆包，别让模块互相咬住

应用变大之后，最省心的做法是每个能力一个独立包。packages/ 里 core 是框架本体，scheduling 只管排期，dispatch 是多应用的控制平面，embedding 负责把应用嵌进别的系统，各管各的。拆分依据写在 pnpm-workspace.yaml：每个包有自己的 package.json，只导出自己需要的接口，改 A 包不会连累 B 包。

让数据模型改得动、改不坏

数据库 schema 是最容易改坏的地方。packages/core/src/db/ 的处理方式是：drizzle-migrations.ts 管理迁移链，ensure-additive-columns.ts 只允许加列、禁止删列，ddl-guard.ts 会拦截不合规的 DDL。本地开发默认用 PGlite，不配 DATABASE_URL 也能直接启动。带走这条经验：改 schema 永远走增量迁移，别原地重写现有表。

给失败一个分类清晰的"人话"说明

智能体失败时，用户看到的应该是原因和下一步，不是堆栈。失败分类就定义在 packages/core/src/agent/engine/failure-taxonomy.ts：限流、凭证缺失、超时各是一类，每类对应不同处理策略，能重试的重试，该升级给人的升级给人。写智能体应用时先定义这张"失败词典"，报错措辞和恢复策略就会始终一致。

上线之前，先证明应用靠得住

给踩过的坑各写一个守护脚本

单元测试只保证"代码能跑"，不保证"代码守规矩"。scripts/ 里有一整排 guard 脚本：guard-no-env-credentials.mjs 阻止把凭证写进环境变量，guard-migration-manifest.ts 校验迁移清单一致性，guard-i18n-catalogs.ts 检查翻译完整性。踩到一个坑，就把它写成一条守护规则，下一个人（或下一个智能体）就不会再踩同一个洞。

给第二个智能体留一份交接手册

这个仓库把"代码能被另一个智能体接手"当成正式功能来做。skills/ 目录下每个技能一份 SKILL.md，描述一套完整工作方法：visual-plans 负责画图式规划，visual-edit 负责可视化修改。接手方读一遍手册就能开工，新人上手的成本也跟着降下来。

让智能体跟其他智能体协同

多应用场景下，智能体之间要能互相调用。packages/core/src/a2a/ 实现了 Agent-to-Agent 协议：agent-card.ts 描述一个智能体是谁、能做什么，task-store.ts 管理跨智能体任务的状态，caller-auth.ts 管住谁有资格调用谁。

右边这种工作区就是协同的落点：一个入口统筹 mail、calendar、slides 等多个应用的智能体，而不是让用户在十几个页面之间来回跳。

下一步

第一步就一条命令：

git clone https://gitcode.com/GitHub_Trending/ag/agent-native

进入仓库后安装依赖，安装脚本会自动构建内部依赖的包；想一次看全效果，用 dev:all 脚本把所有模板并行跑起来，各占一个端口。每次推送前，跑一遍 prep 脚本，把格式化、类型检查、测试和守护脚本全部打绿再合。

一个容易踩的坑：用户或组织的凭证不要写进 .env，这个仓库要求用带作用域的凭证存储，守护脚本会专门检查这一条——从第一天就按这个规矩来，上线前才不会返工。

【免费下载链接】agent-nativeA framework for building agentic apps项目地址: https://gitcode.com/GitHub_Trending/ag/agent-native