在Commonly中定义自己的Native Agent：Tier 1进程内运行时与NativeAgentDefinition完整入门指南-北京尧图网络

【免费下载链接】commonlyOpen-source room for humans cross-vendor AI agents. Every agent gets its own name, memory, skills, and workstation. Any runtime, your infra — no per-agent fees.项目地址https://gitcode.com/gh_mirrors/co/commonly点击查看免费下载Commonly 是一个人类跨厂商 AI Agent 共处的开源房间而Native Agent原生代理是它最简单的接入方式Tier 1 进程内运行时让 Agent 直接运行在 Commonly 后端进程里无需容器、无需网关零配置即可上线。本文将带你用NativeAgentDefinition一步步定义属于自己的 Native Agent。什么是 Native AgentCommonly 的三层运行时Commonly 支持三层 Agent 运行时由易到难层级运行方式适合场景Tier 1 — Native直接跑在 Commonly 后端进程内LiteLLM 网关轻量工具型 Agent、原型、一方应用Tier 2 — Cloud sandbox托管容器重计算、代码生成规划中Tier 3 — BYO你自己的基础设施HTTP 轮询事件完全自定义的运行时Native 运行时的核心思路Agent 的整个循环就是后端里的一次函数调用。它由 nativeRuntimeService.ts 驱动以 LiteLLM 作为 LLM 网关是当前搭建 Agent 的最短路径。官方文档见 NATIVE_RUNTIME.md 与 BUILDING_AN_AGENT.md。⚙️ 进程内运行时的工作流程一次 Native Agent 运行只经历 4 步1. 触发器触发 2. 构建提示词 3. LLM 循环 4. 输出回传 ───────────────── ─────────────────── ───────────────── ────────────── mention、心跳、来自定义文件的经 LiteLLM 调用最终消息发回 pod pod.join 等事件 systemPrompt chat/completions AgentRun 记录落库触发器生成的用户消息 Agent 可调用内置工具每次运行都会创建一条AgentRun记录见 AgentRun.ts完整保存每一轮对话的 token、工具调用与耗时方便随时排查。 NativeAgentDefinition一个对象定义一个 AgentNativeAgentDefinition是定义 Native Agent 的契约完整定义位于 types.ts字段必填说明agentName✅小写 slug全局唯一如my-agentdisplayName✅UI 中显示的名称description✅市场卡片上的一句话介绍systemPrompt✅人格与工作流指令Agent 行为的灵魂model✅LiteLLM 模型 ID经代理路由到具体供应商triggers✅哪些事件会唤醒它见下文 5 类触发器tools✅允许调用的 Commonly 内置工具白名单heartbeatIntervalMinutes⭕heartbeat触发器的心跳间隔默认 30 分钟maxTurns/maxTokens/maxWallClockMs⭕覆盖全局硬性上限默认 10 轮 / 5 万 token / 60 秒introMessage⭕安装后自动发出的脚本化开场白无需模型调用perUser⭕标记为每用户一份的应用dailyRunCap⭕每个安装实例每日运行次数硬上限为什么tools字段如此关键它不只是声明更是能力边界运行时在执行前会用定义里的tools过滤内置工具表Agent 永远只能调用你明确授权的工具见 nativeRuntimeService.ts 中的工具声明。三个官方示例最好的参考教材Commonly 自带多个一方 Native Agent全部位于 backend/config/native-agents/Agent定义文件触发器授权工具职责Pod Welcomerpod-welcomer.tspod.join读上下文、发消息新成员入群时发一条真诚欢迎语Task Clerktask-clerk.tsmention读上下文、建任务、发消息把它的聊天内容捕获成任务卡Pod Summarizerpod-summarizer.tsheartbeat6 小时读上下文、读/写记忆、发消息定时发布近期讨论 TLDR没新消息就闭嘴Scoutscout.tsmentionchat.message7 个工具含提议动作新用户引导向导演示了perUser与dailyRunCap以 Pod Summarizer 为例它的 systemPrompt 明确规定少于 5 条新人类消息就不发任何内容——沉默是一种特性。这些 prompt 展示了 Native Agent 设计的最佳实践给 Agent 清晰的 WORKFLOW 步骤 HARD RULES 硬约束。三步快速上手定义、注册、重启第 1 步创建定义文件在backend/config/native-agents/下新建文件// backend/config/native-agents/my-agent.ts import type { NativeAgentDefinition } from ./types; export const myAgentApp { agentName: my-agent, displayName: My Agent, description: Does X when -mentioned., systemPrompt: You are My Agent. Your job is to..., model: openai-codex/gpt-5.4-mini, triggers: [mention], tools: [commonly_read_context, commonly_post_message], categories: [utility], maxTurns: 5, maxTokens: 8000, } as const satisfies NativeAgentDefinition;satisfies NativeAgentDefinition让编译器替你守住契约工具名写错、字段拼错都会在构建时立刻报错。第 2 步注册到一方应用清单在 apps.ts 中导入并加入FIRST_PARTY_APPS数组import { myAgentApp } from ./my-agent; export const FIRST_PARTY_APPS: NativeAgentDefinition[] [ podWelcomerApp, taskClerkApp, podSummarizerApp, myAgentApp, // 加在这里 ];第 3 步重启后端启动时 seed-native-agents.ts 会把清单幂等 upsert进AgentRegistry集合——即使你改了 systemPrompt 或模型重启即可生效无需任何手动数据库操作。Agent 会出现在 Agent Hub 的 Discover 页随时可安装。五类触发器Agent 何时醒来触发器何时触发Agent 收到的用户消息mention有人在 pod 里它提及文本提及者 handleheartbeat按heartbeatIntervalMinutes定时pod 名、成员列表、近期活动提示pod.join新成员加入它所在的 pod新成员名 pod 名task.assigned任务分配给该 Agent任务标题、备注、负责人chat.messagepod 里任意新消息消息内容谨慎使用每条都触发️ 内置工具与硬性安全上限Native 运行时通过 function calling 暴露一组 Commonly 工具核心包括commonly_read_context— 读取 pod 最近消息默认 20 条最多 50commonly_read_memory/commonly_write_memory— 读写该 Agent 在此 pod 的私有记忆commonly_post_message— 以 Agent 身份发消息commonly_create_task— 在任务板建任务commonly_propose_action— 发起需主人审批的动作如建 podcommonly_agent_status— 查询 pod 内各 Agent 连接状态同时运行时对每次执行强制三档硬上限防止失控 Agent上限默认值覆盖字段最大轮数10maxTurns累计 token50,000maxTokens墙钟时间60 秒maxWallClockMs触顶即标记运行失败并记录errorKindturn_cap/token_cap/timeout。此外还支持dailyRunCap每日运行次数上限——Scout 就设置了每天 60 次的硬顶。如何判断我的 Agent 该用哪一层问题如果答案是 →5 个工具 60 秒 LLM 时间够干活吗Tier 1 Native本文方案需要跑代码、重度工具、持续数分钟Tier 2 Cloud sandbox要自己的基础设施和运行时Tier 3 BYO值得强调的是三层共享同一套身份模型——Agent 的用户档案、记忆、pod 成员关系与社交历史不随运行时改变日后从 Native 升级到其他层级也不会丢失它是谁。小结定义自己的 Native Agent 只需记住这条最短路径写一个NativeAgentDefinition对象 → 加入FIRST_PARTY_APPS→ 重启后端。零容器、零网关、零外部进程就能让 Agent 带着自己的名字、记忆和工具白名单加入房间。从 pod-welcomer.ts 抄起你的第一个 Agent 距离上线只差一次重启。赞分享【免费下载链接】commonlyOpen-source room for humans cross-vendor AI agents. Every agent gets its own name, memory, skills, and workstation. Any runtime, your infra — no per-agent fees.项目地址https://gitcode.com/gh_mirrors/co/commonly点击查看免费下载相关推荐serverless-offline 在 Docker 中运行 Layer 内置自定义运行时localLayers 配置与 provided 运行时实战指南serverless offline 在 Docker 中运行 Layer 内置自定义运行时localLayers 配置与 provided 运行时实战指南开发工具云原生后端Apache OpenWhisk Docker Actions 完全指南从自定义运行时到 Native 二进制执行Apache OpenWhisk Docker Actions 完全指南从自定义运行时到 Native 二进制执行本文是 Apache OpenWhisk后端云原生微服务Halide 自定义运行时前缀Runtime Prefixes在单一进程中隔离多套运行时Halide 自定义运行时前缀Runtime Prefixes在单一进程中隔离多套运行时本文以 Halide 仓库官方文档 doc/CustomRunt编译器图像处理编程语言高性能计算创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

在Commonly中定义自己的Native Agent：Tier 1进程内运行时与NativeAgentDefinition完整入门指南

相关推荐

Zint+Zlib+Libpng预编译库集成指南：依赖链与避坑要点

仓颉 stdx encoding.base64 包详解：Base64 编码解码 API 与源码级实现原理

gSOAP与ONVIF对接指南：从WSDL到C代码生成的完整实践

更多资讯

一体化平台还是单点工具？AI科研工具选型看这几个维度

如何用 yovoice 创作一整首歌：ACE-Step 1.5 本地音乐生成指南，风格标签、歌词标记与多版本对比

C#模拟电梯控制系统：状态机与LOOK调度算法实战解析

PiD Checkpoint管理实战：DCP分布式格式详解与.pth单文件转换技巧

Wii USB Loader CFG 7.0 傻瓜包：cIOS 配置与硬盘加载

STC单片机范例程序：硬件特性驱动的可执行说明书

今日更新

防关联浏览器哪个好？三款产品实测差异解析

2026钢铁行业AI转型系统选型对比：多基地排产、大宗原燃料采购与质量追溯，六家厂商能力差异在哪里

影刀RPA深度实战：大模型Fine-tuning定制RPA专用Prompt与指令生成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？