Bailian managed agent IaC (bl managed-agent)

CRITICAL — Before executing, MUST read the shared protocol in ../bailian-protocol/SKILL.md: High-risk operation confirmation, Version & updates (pre-flight checklist), and CLI errors: report an issue. Command details are authoritative in reference/managed-agent.md and bl managed-agent --help — do not guess flags. If that protocol file is missing, stop and run bl skill init; do not guess auth/consent.

Safety guardrail (the most important rule)

apply / destroy and single-resource create --yes mutate persistent remote resources:

1. For agents.yaml resource changes, always run bl managed-agent plan first and show the diff to the user.
2. A single-resource create command previews its scoped plan when --yes is absent; show that preview before retrying it with --yes.
3. Only after explicit user confirmation, retry apply / destroy / single-resource create with --yes.
4. Never add --yes on your own initiative before the user has confirmed.

API-oriented commands do not replace IaC. Agent / Environment / Skill / Vault / Deployment / Memory Store 的 create 命令仍通过 agents.yaml → scoped plan → scoped apply 管理；查询命令和 Session、Event、File、Deployment 运行时动作直接调用 API。 session archive|delete、file delete、deployment run|pause|unpause、memory-store memories create|update|delete 和 memory-store versions redact 也需要先 --dry-run，确认后才传 --yes。 Webhook 是工作空间级 API 资源，不写入 agents.yaml 或 State。webhook create|update|delete|enable|disable|test|reset-secret 都是高风险操作：先展示 --dry-run 的目标和请求，用户确认后才加 --yes；test 会向接收端投递事件。

state rm, session archive|delete, file delete, deployment run|pause|unpause, and future risk: high commands follow the shared protocol: show the risk message and exact scope, then wait for explicit confirmation before re-running with --yes.

IaC lifecycle

1. Init      bl managed-agent init          # scaffold agents.yaml
2. Validate  bl managed-agent validate      # offline, no network calls
3. Preview   bl managed-agent plan          # show the pending change diff
4. Confirm   show the plan and ask the user # no automatic --yes
5. Apply     bl managed-agent apply --yes   # only after explicit confirmation
6. Destroy   bl managed-agent destroy --yes # separate explicit confirmation

Directory projects, Workbench, and local versions

• Bailian CLI and Workbench use the same .openagentpack/versions/project store and enable switch. Git is not required.
• Directory projects always use Bailian. project.json does not declare a Provider; Build supplies the Bailian Provider configuration automatically.
• Fresh project init includes complete Skill/File/Vault/Environment examples with bilingual README files under agents/assistant/<resource-type>/_examples/. They are not linked in agent.json and are excluded from Build discovery, Workbench declarations, and remote Publish. Copy a resource outside _examples/ and configure its Agent reference to use it. Examples remain local versioned source; never put real secrets into them. / 新项目的四类资源示例默认不启用、不发布；请按 README 复制到 _examples/ 外再配置引用，不要向示例写入真实密钥。
• project init, validate, build, and version commands are local-only. Publish and Workbench resolve credentials from Bailian CLI flags, shell environment, or the active Profile; project initialization does not write credentials into the project directory.
• Build is local-only. Publish never runs Build implicitly and consumes only a current .openagentpack/build/agents.yaml plus manifest.
• Build moves literal Vault secret_value / access_token values from Agent-local or shared vault.json into project-root .env, replacing them with generated environment references. Existing references and .env entries are preserved; conflicts receive suffixed variable names. Preview/dry-run never write or print secrets. Publish and Workbench read the selected project's root .env as a fallback to inherited environment variables, even when invoked elsewhere. .env is private plaintext storage, excluded from local versions but not automatically ignored by Git; keep it backed up securely.
• Build 会将 Agent 本地或共享 vault.json 中的明文密钥移入项目根目录 .env，再写回环境变量引用；保留已有引用和变量，重名时生成后缀。预览不写文件或输出密钥。.env 不进入版本快照，也不加密；请自行备份并加入 Git 忽略规则。
• Agent-local File and Skill content supports Build-time association. A File may be copied directly into agents/<agent>/files/, or placed in agents/<agent>/files/<id>/ when that directory contains exactly one content file; Build generates file.json and a /mnt/<filename> entry in agent.json.files. A directory under agents/<agent>/skills/<id>/ containing SKILL.md generates skill.json and its agent.json.skills entry. Explicit JSON always wins; shared root resources remain explicit. Resources referenced by multiple Agents are promoted to the corresponding root shared directory during Build.
• A successful Publish versions the canonical YAML and the complete project source tree, including Skill scripts/assets and binary files. Remote State is never versioned or restored.
• project version restore restores source files to the working directory, invalidates Build, and does not move version history or remote State.
• managed-agent playground remains the standalone agents.yaml Session Preview path; directory Workbench is only under managed-agent project workbench.

Scoped single-resource create

以下命令都先构造 agents.yaml 声明，再通过 SDK 的定向 Plan/Apply 创建远端资源，不绕过 State：

• 用户只提供资源 name；CLI 自动生成稳定的 YAML 逻辑 key，同名资源用递增后缀并存。Credential 追加到指定 Vault，不单独生成 key。
• agent create --skill <id> 直接绑定已存在的远端 Skill，不要求顶层 skills 声明；默认写为 type: custom，平台 Skill 显式增加 --type official。同一次命令中的全部 --skill 共用该类型。
• agent create --skill-dir <path> 接收可重复的本地 Skill 目录或 ZIP：CLI 从其中的 SKILL.md 读取 name，自动生成顶层 skills.<key> 声明，并把该 key 写入 Agent 的 skills 列表；定向 Apply 会先上传 custom Skill，再创建 Agent。--type 只作用于 --skill <id>，不改变本地 Skill 的 custom 类型。
• agent create --environment <key> / --vault <key> 把已声明的顶层 Environment / Vault key 写入 Agent 声明，作为默认运行时绑定；百炼 Agent API 不接收这两个字段，session create|run 与 deployment create 未显式传入时才使用它们，显式传入则覆盖。引用的资源必须先用对应的 create 命令创建，未声明的 key 直接报用法错误。
• agent create --mcp <server-code> 接收可重复的 MCP 市场服务 code（来自 bl mcp list），写入 mcp_servers（type: official）与对应的 tools.mcp，默认启用全部工具；如需按工具开关，修改 YAML 中的 tools.mcp[].configs 后执行全量 apply。
• 默认只预览自动 key 和定向计划；--dry-run 完全离线，只有显式 --yes 才写 YAML 并创建远端资源。
• 定向流程只刷新目标资源及其传递依赖；无关资源不检测 Drift、不产生 action，也不阻塞。
• 目标资源必须是 create，相关依赖必须已经处于 no-op；项目级 Drift 和删除仍由全量 plan/apply 处理。
• 远端创建失败时保留 YAML 声明；修复相关依赖或 Provider 错误后，重复相同命令会复用待创建 key。
• skill create 接受本地目录、ZIP 或单个 SKILL.md；远程 URL 仍需手工声明到 YAML，再执行全量 Apply。

Credential secret input

vault credential create --secret-env <ENV_NAME> 中的参数是变量名，不是 Secret 明文。Secret 可来自 Shell export、CI Secret 注入或可选的 .env；CLI 会从当前目录向上自动加载最近的 .env，用户不必创建该文件。

export PROD_API_TOKEN="..."
bl managed-agent vault credential create \
  --vault production \
  --name api-token \
  --secret-name API_TOKEN \
  --secret-env PROD_API_TOKEN

• YAML 只保存 secret_value: ${PROD_API_TOKEN}，输出、诊断和 State 都不保存明文。
• 不要提交 .env；若使用 .env，先确认项目 .gitignore 已忽略它。
• 预览后再带 --yes 重试。后续执行全量 Apply 时也必须提供同名环境变量。

具体 flags、usage 和 examples 以 reference/ 或对应命令的 --help 为准。

Deployment as IaC

Deployment 与 Agent 一样声明在 agents.yaml 中，并复用同一条 validate → plan → apply → destroy IaC 链路； deployment create 可追加一条声明并走定向 Apply；CLI 不提供绕过 state 的 Deployment create/update/delete。最小配置：

deployments:
  daily-report:
    agent: assistant
    initial_events:
      - type: user.message
        content: "Generate today's report."

• apply 会在百炼创建原生 Deployment；destroy 会归档已跟踪的远端 Deployment。
• schedule 会在 apply 后由百炼服务端执行。若旧流程已有外部 cron / CI，先检查 plan，避免重复触发。
• initial_events 至少包含一个 user.message 或 system.message；user.define_outcome 在百炼会被丢弃并产生诊断。
• 本地文件资源在 apply 时上传，mount_path 必须位于 /mnt，且归一化后不能重复。
• 旧版模拟 Deployment 的 state 可能记录空 remote_id；升级后 plan 会显示 materialize 更新，确认后再 apply。

Session interaction (chat with a deployed managed agent)

规范路径是 session event list|send|stream；session events 保留为 session event list 的兼容别名。 Managed Agents 的子线程通过 Event 中的 session_thread_id 暴露；公开 API 当前没有独立 Thread 资源 CRUD， 不要构造 session thread list|get|archive|events 命令。

API-oriented resource commands

• 所有 Cursor 都是不透明字符串：只回传 next_page，不得转换为数字页码。
• 客户端搜索默认最多扫描 10 页；需要扩大范围时显式传 --page-limit。Deployment 搜索直接映射服务端 keyword。
• 下载必须给出 --output-file；默认不覆盖已有文件，只有用户确认后才可加 --force。
• session export 只导出诊断元数据，不含 File 正文，并会脱敏凭证类字段。
• session create|run --environment_variables KEY=VALUE injects variables into this Session only. Repeat the flag for multiple variables; the last value for a key wins. Empty values and values containing = are allowed. Dry-run and diagnostic exports redact values. / 环境变量仅用于本次 Session，不写入 YAML 或 State；可重复传入，允许空值和包含 = 的值，预览和诊断导出会脱敏变量值。
• deployment create --environment_variables KEY=VALUE declares runtime variables under deployments.<key>.environment_variables as a string map. With --yes, the scoped create writes YAML and creates the Deployment. YAML + apply also manages this field; changing values updates the Deployment, and removing the field or setting {} clears it. Create and plan previews omit values; YAML stores them. / Deployment 环境变量以字符串键值对象声明；创建命令使用 --yes 后写入 YAML 并定向创建，也可直接用 YAML + apply 管理。修改值会更新部署，删除字段或设置 {} 会清空变量。预览输出不展示变量值，YAML 会保存这些值。
• 公开 Managed Agents API 没有模型 Catalog，也没有 MCP OAuth Login；CLI 不注册对应命令。

Memory Stores and Session mounts

• Store lifecycle stays in agents.yaml: create with memory-store create, and preview changes with plan before apply. There are no direct Store update, archive, or delete commands. / 记忆库生命周期统一走 IaC，变更先预览再确认。
• Memory Store names are display labels and need not be unique. State records the remote ID; create a new store when no ID exists, and import a known ID explicitly to adopt an existing store. / 按 ID 识别记忆库，不按同名匹配。
• entries initialize new stores only. Existing, imported, or adopted stores keep their runtime content. Set entries_mode: sync explicitly when declared paths must continue to follow YAML; removing a declared entry does not delete its remote file. / 默认只初始化新库，持续同步必须显式启用。
• Store reads, memory content, and version APIs use the workspace API Key directly through the SDK. Their --store-id is a remote ID; they do not require YAML or State. --content and --content-file are exclusive and allow empty content. Updates can use --expected-content-sha256 to detect concurrent edits. / 正文 API 使用远端 ID，空正文有效。
• session create|run --memory-stores retains the comma-separated YAML key shorthand. Repeatable --resource <json|@path> supports { "type": "memory_store", "memory_store": "notes", "access": "read_only", "instructions": "..." }. Explicit resources override the same shorthand mount while retaining other mounts. Duplicate explicit references are rejected; at most eight Memory Stores may be mounted. / resource 使用逻辑 key，可指定权限和说明。
• Deployment currently supports File Resources only. An effective Memory mount, including one inherited from the Agent, is rejected. / Deployment 本期仅支持 File，不能继承或直接挂载记忆库。
• Preview memory writes with --dry-run, then obtain confirmation before adding --yes. Version redaction permanently removes that version's content. / 版本擦除不可撤销，必须先预览并确认。

bl managed-agent memory-store create --name Notes --dry-run
bl managed-agent memory-store memories list --workspace-id ws-example --store-id memstore-example --view full
bl managed-agent session create --agent assistant \
  --resource '{"type":"memory_store","memory_store":"notes","access":"read_only"}' \
  --dry-run

Command fields and pagination are authoritative in reference/managed-agent.md and command help; return next_page unchanged. / 参数以生成手册和 help 为准，分页游标原样传回。

Workspace Webhooks

• Webhook commands use the CLI API Key, Base URL, and workspace settings directly through the SDK. They do not need agents.yaml, a project Build, or local State. / Webhook 命令直接使用 CLI 鉴权与工作空间配置，无需创建项目文件。
• Select the workspace with --workspace-id or the configured environment/Profile. Explicit flags take precedence over environment variables, then the selected Profile. Check webhook <command> --help for the available request fields.
• webhook events uses --limit (1–100) and the opaque --page cursor; pass next_page back unchanged. / 事件分页游标保持原样传回，不转换成数字页码。
• Successful create and reset-secret responses can contain signing_secret. Store that response securely for signature verification; do not paste it into logs, issue reports, or source files. Verbose diagnostics and errors must not expose secrets. / 创建或重置密钥的成功响应可能包含签名密钥；请安全保存，不写入日志或代码。

bl managed-agent webhook list --workspace-id ws-example --output json
bl managed-agent webhook create \
  --workspace-id ws-example \
  --url https://example.com/agent-events \
  --event session.updated \
  --dry-run

Review the preview and obtain confirmation before removing --dry-run and adding --yes. Event names are passed to the service as supplied; use the event types supported by your endpoint. / 预览并确认后再执行写操作；事件名以服务端支持的事件类型为准。

Local state management

• Always make the difference clear to the user: state rm only edits the local state file, while destroy deletes the remote resource.

Flags, usage, and examples: see reference/ or bl <command> --help — do not guess flags.

Common hand-offs

软 hand-off（按 skill 名；已安装则 Read，否则 --help / 提示 bl skill init）：

• Call an already published Bailian app/assistant → bailian-app-call, or skill bailian-cli (bl app list / call; fallback: bl app --help).
• Choosing the model referenced in agents.yaml → bailian-model-recommend.
• Deployment quota / billing questions → skill bailian-cli (fallback: bl quota / bl usage --help).

references

• bailian-protocol — shared protocol (install via bl skill init)
• reference/ — command details