Home/bailian-managed-agent

bailian-managed-agent

>-

by modelstudioai in cliGitHub ↗
Installs8.9Kdeduplicated source total
8-week historyLatest recorded total per week
GitHub stars—source repository
UpdatedOct 05, 2026normalized snapshot

SKILL.md

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 的 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：

ResourceCommand
Agentbl managed-agent agent create
Environmentbl managed-agent environment create
Custom Skillbl managed-agent skill create
Empty Vaultbl managed-agent vault create
Credential in a Vaultbl managed-agent vault credential create
Deploymentbl managed-agent deployment create
  • 用户只提供资源 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 只保存 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)

IntentCommand
Create + send + stream in one stepbl managed-agent session run
Send a message to an existing sessionbl managed-agent session send
Create / inspect / list sessionsbl managed-agent session create / get / list
List session event historybl managed-agent session events
Delete a sessionbl managed-agent session delete

规范路径是 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

IntentCommand family
Discover agents and versionsagent list, agent get, agent search, agent versions
Discover environmentsenvironment list, environment get, environment search
Discover skills and download a versionskill list, skill get, skill search, skill versions, skill download
Inspect vault envelopesvault list, vault get, vault search
Inspect deployments and run historydeployment list, deployment get, deployment search, deployment runs list, deployment runs get
Run or pause deploymentsdeployment run, deployment pause, deployment unpause
Manage session metadata/lifecyclesession list, session get, session search, session update, session archive, session delete
Work with raw eventssession event send, session event list, session event stream
Diagnose/export a sessionsession debug, session export
Work with filesfile upload, file list, file get, file search, file download, file delete
  • 所有 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

IntentCommand
Inspect tracked resourcesbl managed-agent state list / show
Adopt an existing remote resource to statebl managed-agent state import
Untrack only (do not destroy remotely)bl managed-agent state rm
  • 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