AEL Docs
Follow updates
Menu
Follow updates
Browse the documentation

AEL 1.0.0

Deployment and rollback

With AEL, the Agent Engineering Language, a change reaches running programs and devices only through a plan you have reviewed. Deployments are staged, and you can roll each one back.

On servers you operate, your application has health checks for the storage, databases and models it declares, and a new version is switched on only once it reports ready. Self-hosting your application describes those checks.

Building does not deploy

A successful build or test never flashes a board, switches a service to a new version or promotes a prompt. Each of those is a separate, explicit step you take.

Planning

ael deploy plan makes a plan, and ael deploy apply carries out the plan you reviewed:

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

A plan is fixed once it is made, and it names everything that the deployment changes:

  • 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 AEL 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 has;
  • 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 also shows its evaluation results; see Evaluations and prompt releases.

Applying

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

Rolling back

  • Known-good versions are kept, and rolling back returns to the previous compatible version.
  • Rollback covers prompt updates on a gateway, desktop and server deployments and supported boards, including a plan that was only partly applied and a device that was disconnected while it was applied.
  • Rolling back does 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 does
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 can never widen them.
New program code for a desktop, server or containerStage a new executable or image, then switch it on.

Where services run

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

Edges follow the same rule: the same edge runs in one process, between processes or over the network, as your deployment places it, with no change to your source, and over the network it uses AEL's built-in gRPC-compatible transport with TLS. Communication between agents describes edges.