Deployment plans

In AEL, the Agent Engineering Language, a deployment is two explicit steps: ael deploy plan works out what a deployment changes and shows it for review, and ael deploy apply carries out exactly the plan you reviewed.

Usage

ael deploy plan
ael deploy apply --plan <plan>

Command or option	Meaning
`ael deploy plan`	Build the plan and show it, changing nothing.
`ael deploy apply`	Apply one reviewed plan.
`--plan <plan>`	The plan to apply, as `ael deploy plan` identified it.
`--json`	The plan, or the progress of applying it, in machine-readable form.

What a plan shows

A plan is fixed once it is made. It names:

the programs and firmware images to deploy, and the devices or machines they go to;
the prompts, model bindings, tools and permissions of each agent, by their exact versions;
where each part runs, including what runs on a device and what runs on the AEL Gateway that serves it;
how each device behaves if it loses its connection;
whether each change is compatible with what is deployed now;
the evaluation results of the prompts it deploys.

A change that widens a tool's permissions needs a new, authorized plan: a prompt update alone can never widen them.

What applying does

Checks the plan is still true. If a device, a machine or the deployed version changed since the plan was made, apply refuses the plan rather than deploy something you did not review.
Stages. It puts every new part in place without switching to it.
Checks readiness. It confirms each staged part is ready.
Activates. It switches to the new version in a set order, so a device never starts using a new prompt or tool while the part that serves it still runs an older, incompatible one.

Runs already under way stay pinned to the version they were admitted with, to the end. New runs use the new version.

Rollback and recovery

Rolling back is one step, to the previous compatible version: the last known-good programs, firmware and prompts are kept for it.
Each step of an apply is recorded. If the connection is lost or one part fails, apply finds out what is actually deployed before it retries, and reports a state it cannot determine as unknown, never as done.
A compatible prompt-only change does not need a board to be flashed again. A change of types or permissions may need new firmware and a coordinated update.

Never automatic

Building, testing and evaluating never deploy anything, and a deployment never flashes a board unless its plan says so and you apply it.

Running evaluations and Comparing prompts: the steps before a plan.
Evaluations and prompt releases: promotion and rollback.
Flashing a board: writing firmware by hand.
Deployment and rollback: plans, staging and rollback across programs, gateways and boards.