AEL Docs
Follow updates
Menu
Follow updates
Browse the documentation

Preview documentation for AEL Beta 0.0.1 — launching soon

Deployment and rollback

With AEL, the Agent Engineering Language, a change will reach running programs and devices only through a plan you have reviewed. Deployments will be staged, and you will be able to roll each one back. The optional self-hosted build and run server will add backups, staged deployments and rollback for the programs and devices it manages.

Status

Planned for AEL Beta 0.0.1. AEL is not available yet.

Building will not deploy

A successful build or test will never flash a board, switch a service to a new version or promote a prompt. Each of those will be a separate, explicit step you take.

Planning

ael deploy plan (command names may change before launch) will make a plan, and ael deploy apply will carry out the plan you reviewed:

Preview syntax — may change before launch
ael deploy plan
ael deploy apply --plan <plan>

A plan will be fixed once it is made, and it will name everything that is going to change:

  • the executables and firmware images, by fingerprint, and the boards and devices they go to;
  • which parts run on a device and which run on a gateway or a server;
  • the system prompts, tools and typed inputs and outputs, with a compatibility check for each against what is deployed;
  • the endpoints and model bindings each part uses;
  • the permissions each part will have;
  • what each device does when it loses its gateway or a call times out;
  • the order in which the parts are switched on, and how each step is undone.

A plan for a prompt change will also show its evaluation results; see Evaluations and prompt releases. The format of the file that describes a deployment will be published when it is final.

Applying

  • Exactly what you reviewed. Applying will carry out the plan you reviewed and nothing else. If what is deployed has changed since you made the plan, the stale plan will be refused rather than applied to something different.
  • Staged. New versions will be put in place beside the running ones, checked for readiness, then switched on in the documented order.
  • Pinned runs. Runs already under way will keep the version they started with until they end.
  • Recorded steps. Each step will be recorded. If the acknowledgement of a step is lost, apply will check what is actually running before it tries again, and report an unknown state rather than guessing.
  • Devices and gateways together. A device will never start using a new prompt or tool contract that its gateway does not serve yet.
  • Boards. For a board, applying will write the firmware to the selected, connected device, the way ael flash does, and to no other.

Rolling back

  • Known-good versions will be kept, and rolling back will return to the previous compatible version.
  • Rollback will cover prompt updates on a gateway, desktop and server deployments and supported boards, including a plan that was only partly applied and a device connector that was disconnected.
  • A version that a rollback may still need will never be removed by retention rules.
  • Rolling back will not undo an effect that already happened outside your program, such as a message that was sent or a payment that was made.

What each change needs

ChangeWhat the plan will do
A prompt change that keeps the same typed inputs, outputs, tools and permissionsUpdate the gateway or service, flashing no firmware.
A change to the typed inputs, outputs or tools a device usesFlash new firmware in a coordinated update of the device and its gateway.
A change that widens a tool's permissionsRequire a new, authorized plan. A prompt update alone will never be able to widen them.
New program code for a desktop, server or containerStage a new executable or image, then switch it on.

Where services run

Code will call a typed service, and the deployment will decide whether it runs in the same process, on another machine, over HTTPS or over gRPC. Moving a service will be a change to the deployment, not to your code. The placement will be chosen when you deploy: an agent will not move between machines while it runs.