Bailian managed agent IaC (bl managed-agent)

CRITICAL — Before executing, MUST read the shared protocol in [../bailian-protocol/SKILL.md](../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](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 的 create 命令仍通过 agents.yaml → scoped plan → scoped apply 管理；查询命令和 Session、Event、File、Deployment 运行时动作直接调用 API。 session archive|delete、file delete、deployment run|pause|unpause 也需要先 --dry-run，确认后才传 --yes。

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

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 类型。
• Environment 和 Vault 属于 Session/Deployment 运行时绑定，不是 Agent 创建参数；在 session create|run 或 deployment create 中传入。
• 默认只预览自动 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 只保存 secretvalue: ${PRODAPI_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，避免重复触发。
• initialevents 至少包含一个 user.message 或 system.message；user.defineoutcome 在百炼会被丢弃并产生诊断。
• 本地文件资源在 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 中的 sessionthreadid 暴露；公开 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 正文，并会脱敏凭证类字段。
• 公开 Managed Agents API 没有模型 Catalog，也没有 MCP OAuth Login；CLI 不注册对应命令。

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/](reference/index.md) 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](../bailian-protocol/SKILL.md) — shared protocol (install via bl skill init)
• [reference/](reference/index.md) — command details