How it works

Write

You write a project as a folder of small, named source files. One command creates a ready-to-build project:

ael init support

ael init creates three files at the project's root:

• main.ael, the program's entry point;
• pack.ael, the packages the project uses, empty to begin with;
• metadata.ael, the project's name and settings.

Every other source file holds one component, and its name says which: summarize.node.ael holds the node summarize, and support.agent.ael the agent support. Agents, subagents, nodes (business steps), edges (typed two-way connections), configuration, hooks and skills are first-class building blocks, each in its own named file, so a project's structure reads at a glance. Project layout shows a complete project.

main.ael declares main with the application's name, main support(), and the program you build takes that name. Your application can also hold private functions written in other languages, with typed AEL signatures, built and run with your own toolchains, pinned by version; see Functions in other languages.

When you add a package, it goes into pack.ael, and the lock file pack.lock beside it records the exact versions your builds use. One manifest and one lock file give reproducible builds that also work offline.

Check

ael check checks a project, a folder or a single file before anything runs:

• names and file roles, and the size limit of every source file;
• types, including the inputs and outputs of agents and nodes;
• which functions each file may call, and what each piece of code is allowed to do;
• hooks, packages, and whether the chosen target can offer what the program needs.

Type, ownership and permission mistakes are caught here, not when the program runs. Diagnostics point at your source, and ael check --json reports them in a machine-readable form for your own scripts. ael fmt formats your source, and ael fmt --check lists the files it would change without changing them.

Build

Building turns a checked project into a native program for one target: a native executable for an operating system, or a firmware image for a microcontroller board.

ael build --target <target>

This writes the program support beside main.ael; -o writes it elsewhere. Every build starts by checking the complete reference map: what references what, beginning at main. Only what you use ships: an HTTP-only app carries no WebSocket code, and no gRPC code unless an edge is placed on the network. ael refmap shows the same map for a whole project, a folder or one file, and lists unused code and packages.

A feature a target cannot support fails at compile time, not on the device. ael build --debug adds what standard native debuggers need to debug at source level.

You can also split the step in two: ael compile produces compiled AEL for every component, and ael build builds a native program from compiled AEL without needing the source.

Run

ael run checks, builds and runs a project in one step, through the same checks as a build:

ael run

Programs compile straight to self-contained native executables, with no interpreter or virtual machine to run and no second language to install unless you write functions in one, and desktop and server programs written in AEL alone need nothing else installed. Nothing downloads when it starts: your lock file pins every package before the build. A console agent needs no server; you add the HTTP package and declare routes only when you want it to serve an API.

Each run of an agent has its own run ID and budget, and its configuration is locked into a snapshot for that run, so settings cannot change underneath a running agent.

One toolchain

The AEL toolchain is self-contained: one install takes your AEL code all the way to a native program. Supported targets lists the exact targets.

Next

• A first program walks through the four steps with a small project.
• Glossary explains the words used here.