bailian-managed-agent

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:

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

API-oriented commands do not replace IaC. The create commands for Agent / Environment / Skill / Vault / Deployment are still managed through agents.yaml → scoped plan → scoped apply management; query commands and Session, Event, File, Deployment runtime actions call the API directly. session archive|delete、file delete、deployment run|pause|unpause also requires first --dry-run, and only after confirmation is --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

Directory projects, Workbench, and local versions

Intent	Command
Create or convert a directory project	`bl managed-agent project init`
Validate and Build directory source	`bl managed-agent project validate` / `build`
Publish the current immutable Build	`bl managed-agent project publish --yes`
Launch project resource editing	`bl managed-agent project workbench`
Launch one Agent Session Preview	`bl managed-agent playground --agent <id>`
Enable/disable project versions	`bl managed-agent project version enable` / `disable`
Inspect local version state and history	`bl managed-agent project version status` / `list`
Preview or restore project source	`bl managed-agent project version preview` / `restore`

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. / The four types of resource examples for new projects are disabled and unpublished by default; follow the README to copy them outside _examples/ before configuring references, and do not write real secrets into the 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 moves plaintext secrets from the Agent's local or shared vault.json into the project root .env, then writes back environment variable references; existing references and variables are retained, and a suffix is generated on name conflicts. Preview does not write files or output secrets..env does not enter version snapshots and is not encrypted; back it up yourself and add it to Git ignore rules.
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

The following commands all first construct agents.yaml declarations, then create remote resources through the SDK's targeted Plan/Apply, without bypassing State:

Resource	Command
Agent	`bl managed-agent agent create`
Environment	`bl managed-agent environment create`
Custom Skill	`bl managed-agent skill create`
Empty Vault	`bl managed-agent vault create`
Credential in a Vault	`bl managed-agent vault credential create`
Deployment	`bl managed-agent deployment create`

The user only provides the resource name; the CLI automatically generates a stable YAML logical key, and resources with the same name coexist with incrementing suffixes. Credentials are appended to the specified Vault and do not generate a separate key.
agent create --skill <id> directly binds an existing remote Skill and does not require a top-level skills declaration; by default it is written as type: custom, and platform Skills explicitly add --type official. All --skill in the same command share that type.
agent create --skill-dir <path> accepts repeatable local Skill directories or ZIPs: the CLI reads the name from the SKILL.md within them, automatically generates a top-level skills.<key> declaration, and writes that key into the Agent's skills list; targeted Apply first uploads the custom Skill, then creates the Agent.--type only applies to --skill <id>and does not change the custom type of the local Skill.
Environment and Vault belong to Session/Deployment runtime binding and are not Agent creation parameters; pass them in session create|run or deployment create .
By default only previews automatic keys and targeted plans;--dry-run is fully offline, and only explicit --yes writes YAML and creates remote resources.
The targeted flow only refreshes the target resource and its transitive dependencies; unrelated resources are not checked for Drift, do not produce actions, and do not block.
The target resource must be create, and related dependencies must already be in no-op; project-level Drift and deletion are still handled by full plan/apply .
When remote creation fails, the YAML declaration is retained; after fixing the related dependency or Provider error, repeating the same command reuses the pending creation key.
skill create accepts a local directory, ZIP, or a single SKILL.md; remote URLs still need to be manually declared in YAML, then a full Apply is executed.

Credential secret input

vault credential create --secret-env <ENV_NAME> The parameters in are variable names, not plaintext Secrets. Secrets can come from Shell export, CI Secret injection, or an optional .env; the CLI automatically loads the nearest .envupward from the current directory, so users do not need to create that file.

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 only stores secret_value: ${PROD_API_TOKEN}, and outputs, diagnostics, and State do not store plaintext.
Do not commit .env; if using .env, first confirm that the project's .gitignore already ignores it.
After previewing, retry with --yes . When subsequently performing a full Apply, the environment variable with the same name must also be provided.

For specific flags, usage, and examples, refer to reference/ or the corresponding command's --help .

Deployment as IaC

Deployments, like Agents, are declared in agents.yaml and reuse the same validate → plan → apply → destroy IaC pipeline; deployment create you can append a declaration and perform a targeted Apply; the CLI does not provide Deployment create/update/delete that bypasses state. Minimal configuration:

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

apply will create a native Deployment in Bailian;destroy will archive a tracked remote Deployment.
schedule will be executed by the Bailian server after apply . If the old process already has an external cron / CI, first check planto avoid duplicate triggers.
initial_events must contain at least one user.message or system.message；user.define_outcome will be discarded in Bailian and generate diagnostics.
Local file resources are uploaded at apply ,mount_path must be located in /mnt, and must not be duplicated after normalization.
The state of an old simulated Deployment may record an empty remote_id; after upgrading, plan will show a materialize update; after confirming, then apply。

Session interaction (chat with a deployed managed agent)

Intent	Command
Create + send + stream in one step	`bl managed-agent session run`
Send a message to an existing session	`bl managed-agent session send`
Create / inspect / list sessions	`bl managed-agent session create` / `get` / `list`
List session event history	`bl managed-agent session events`
Delete a session	`bl managed-agent session delete`

The canonical path is session event list|send|stream；session events retained as session event list compatible alias. Managed Agents' subthreads are exposed through the session_thread_id in Events; the public API currently has no independent Thread resource CRUD, do not construct session thread list|get|archive|events commands.

API-oriented resource commands

Intent	Command family
Discover agents and versions	`agent list`, `agent get`, `agent search`, `agent versions`
Discover environments	`environment list`, `environment get`, `environment search`
Discover skills and download a version	`skill list`, `skill get`, `skill search`, `skill versions`, `skill download`
Inspect vault envelopes	`vault list`, `vault get`, `vault search`
Inspect deployments and run history	`deployment list`, `deployment get`, `deployment search`, `deployment runs list`, `deployment runs get`
Run or pause deployments	`deployment run`, `deployment pause`, `deployment unpause`
Manage session metadata/lifecycle	`session list`, `session get`, `session search`, `session update`, `session archive`, `session delete`
Work with raw events	`session event send`, `session event list`, `session event stream`
Diagnose/export a session	`session debug`, `session export`
Work with files	`file upload`, `file list`, `file get`, `file search`, `file download`, `file delete`

All Cursors are opaque strings: only pass back next_page, and must not convert to numeric page numbers.
Client-side search scans at most 10 pages by default; when a wider range is needed, explicitly pass --page-limit. Deployment search maps directly to the server-side keyword。
Download must provide --output-file; by default existing files are not overwritten, and only after user confirmation may --force。
session export be added. Only diagnostic metadata is exported, without File body text, and credential-type fields are redacted.
The public Managed Agents API has no model Catalog, nor MCP OAuth Login; the CLI does not register corresponding commands.

Local state management

Intent	Command
Inspect tracked resources	`bl managed-agent state list` / `show`
Adopt an existing remote resource to state	`bl 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

Soft hand-off (by skill name; if installed, Read, otherwise --help / prompt 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