声明式托管 agent，最需要的是"执行之前先看清"

阿里云百炼把模型、应用、知识库这些能力开放成服务之后，托管 agent 是往上的一层：你声明一份配置，平台按声明把 agent 建起来，让它接着往下干活。

声明式的好处很实在，配置能进版本库、能被评审、能被复现。代价也很实在：写错一处，影响面不是一次失败的调用，而是云上多出一个会自己跑的资源。建出来只要一条命令，收干净要翻好几个地方。

bl managed-agent 这组命令要处理的就是这个代价。它的做法是把"改配置"和"动云上资源"拆成两个动作，中间隔着一个必须由人显式给出的确认参数。不带确认参数，命令只输出将要发生什么，一件远端资源都不创建。

下面按六个能力面讲清它各管什么，再给一条不联网也能走完的上手路径。命令行的安装说明在一条命令装完的 CLI 安装页，资源模型可以先去阿里云百炼控制台对一眼；Key 这一篇用不上，等真要连云了再去领一把密钥。

六个能力面，各管一段

配置生命周期。 agents.yaml 是唯一事实源。init 在空目录生成脚手架，validate 离线校验结构，plan 输出"如果执行会发生什么"的变更面。apply 与 destroy 属高风险远端写，受统一确认闸门保护，必须显式给出确认参数才执行，本篇不涉及。

目录项目与本地版本。 配置从一个文件长成一棵树之后怎么管，这一层给答案。project init 把 agent 和它的资源组织成一个目录项目，自带本地版本库；校验、构建、读版本各有一条命令，构建产出的是一份清单，可以拿去比对两次配置到底差在哪。

定向创建预览。 创建 agent、创建记忆库这类命令都有预览姿势，输出一个自动生成的钥匙名和一份定向计划，说清打算创建什么、依赖是否就绪，全程不碰远端。这是整组命令里最适合反复跑的一层。

会话与记忆库。 记忆库用声明的方式建，和 agent 走同一条预览路径。会话相关的查询属只读查询族，在当前环境的可用性见后面那节边界，本篇不给未经确认的结论。

webhook。 工作空间级的能力，不需要项目文件就能用。在我这个环境里，它是只读查询族中唯一通的一条，确实返回了数据，内容涉及真实资源标识，本篇不贴。

本地账本。 state 记的是这台机器上这份配置跟踪了哪些远端资源，不是云端资源的实时清单。这个区分是整组命令里最该先建立的概念，做清理动作之前尤其要先想清楚。

上手路径：本地五步，零远端写

前三步是声明式配置的最小闭环。

bl managed-agent init

空目录里生成脚手架，接着 validate 离线校验。这一步不发任何网络请求，语法和结构的问题在本地就被拦下来，退出码可以直接当 CI 前置检查的判据。再跑 plan 看变更面；脚手架还没改动的时候，它明说没有任何待执行变更。

改配置、看结构、看变更面，这个循环可以重复任意次，不产生远端副作用。对第一次写 agents.yaml 的人来说，这一段的价值就是把"不知道对不对"变成"本地就有答案"。

第四步是目录项目。project init 这次生成 32 个文件：一个本地版本库、一份 agent 配置，还有技能、文件、密钥、环境四类资源的示例和双语说明。示例默认不启用、不发布，要用需按说明复制出来再配置引用，脚手架不会把示例顺手带进发布面。

这一步有个位置约束：目录项目的校验与构建要在项目目录里跑。在外层目录跑，校验只回一句"目录项目校验失败"，构建则报"这里不是项目根目录"，并把出路写在提示里，要么切进目录，要么把目录位置当参数传进去。站对目录之后两步都是不到一秒返回，校验通过附一个校验号，构建产出清单，本地版本库也读得到。

第五步是定向创建的预览。

bl managed-agent agent create --name 我的第一个agent --model qwen3.8-max --instructions '回答保持简短。' --dry-run

只给名字的时候它当场拒绝，点名缺的是模型和说明这两样，不填默认模型也不猜指令。参数齐了加预览，一秒左右回一个自动生成的钥匙名加一份定向计划，远端资源创建数为零。记忆库创建是同一种形状。

预览与执行之间的那条线

这条线不是靠使用者自觉守的，是命令自己守的。想真执行，就得显式加上确认参数，那是另一次独立的决定。

对托管 agent 这类资源，这个设计的价值比任何教程都大：创建类命令可以被反复跑，只为了看清它到底打算建什么、挂在哪些依赖上、钥匙名合不合 agents.yaml 里的约定。预览离线、可重复、零副作用，评审通过之后要不要执行，由人看过再定。

两条边界，照实写

第一条，只读查询族在当前环境不可用。查 agent、查技能、查部署、查会话这四条一律回 404，补上工作空间参数再跑仍然不行。唯一例外是查 webhook，通，且返回了真实数据。因此"装完先列一下盘点账号里有什么"这条惯常做法，在这组命令上不成立；要验证鉴权与网络连通，webhook 这一条就够。

第二条，本篇不涉及任何远端写。执行、销毁以及任何带确认参数的动作都没有跑，云资源创建数为零，既有资源改动为零。

安全纪律：预览、人工确认、才带确认参数

高风险动作的流程固定成三段。先预览，用 plan 或预览参数，可重复跑，输出拿来评审。再人工确认，由人看过预览内容，确认创建范围、依赖、钥匙名都对。最后才带确认参数执行。

第二段不能被脚本替代。自动化流水线里最容易出的事，是把确认参数写死在模板里，让"人工确认"退化成一个永远为真的开关。

本地账本那句"账本里没有跟踪任何资源"也属于同一套纪律：账本为空不代表云上没有任何资源，账本里有记录也不代表那个远端资源还活着。取消跟踪与删除远端是两条不同的命令，动手前先确认自己要的是哪一种。

适用建议

想在真正执行前把 agents.yaml 与目录项目验一遍，本地五步够用且完全离线，适合放进 CI 的前置检查。想快速看清一次创建到底要建什么，预览给的那份定向计划就是为此设计的。想靠查询族盘点已有资源，在当前环境走不通，别把它当第一步。

从生成脚手架到看完第一份计划，几分钟走完，云上一个字节都不会动。这一点对第一次接触托管 agent 的团队尤其友好：先把配置的正确性问题在本地解决完，再谈资源生命周期。