A first program

This walk-through creates a project in AEL, the Agent Engineering Language, writes a program that prints a line, adds a helper function, and then checks, runs and builds the program.

The project

One command creates a ready-to-build project:

ael init hello

ael init creates a folder named hello with three files at its root. It never overwrites files that already exist.

hello/
  main.ael        # the program's entry point
  pack.ael        # the packages the project uses; none at first
  metadata.ael    # the project's name and settings

metadata.ael records the name you gave:

metadata {
    schema = 1;
    name = "hello";
}

pack.ael starts with no packages. It stays in the project even when it is empty:

pack {
    schema = 1;
    dependencies = [];
}

A project name is an AEL identifier: letters, digits and _, not starting with a digit, not a keyword, not main, and at most 64 characters.

The entry point

Every program starts in main.ael, which declares exactly one main, followed by the name in metadata.ael:

# main.ael
main hello() {
    print("Hello from AEL");
}

The name after main is the application's: it must equal name in metadata.ael, and main main() is refused. A main without a result type returns nothing, and the program exits successfully when main finishes. A comment starts with # and runs to the end of the line.

A helper function

A function declared with fn is a helper function. It is private to the file that declares it and that file's extension files: no other file can call it.

# main.ael
main hello() {
    let price: i64 = 1200;
    let total: i64 = with_tax(price);
    print(total);
}

fn with_tax(amount: i64) -> i64 {
    return amount + amount / 5;
}

let binds a name to a value; here each binding writes its type after the name. A binding does not change unless it is declared with let mut.
i64 is a 64-bit signed integer. Integers have fixed widths, and AEL never converts between them silently.
Arithmetic is checked: if amount + amount / 5 overflows, AEL reports the overflow, never silently ignores it.

To share a function between files, you write it as a global or a reusable function in a file of its own. Project layout describes both.

Checking and running

From inside the hello folder, you check and run the program:

ael check
ael run

ael check checks the whole project without running anything. Its diagnostics point at the exact place in your source, and ael check --json reports them in a machine-readable form.

ael run checks, builds and runs the program in one step.

Building

To build the program without running it, choose a target:

ael build --target <target>

<target> names what the program runs on: an operating system and processor, or a microcontroller board. Supported targets lists the exact targets. The program takes the application's name: this build writes hello beside main.ael, and -o writes it elsewhere, as in ael build --target <target> -o build/hello.

For a desktop or server target, the result is a self-contained native executable, with no interpreter or virtual machine to run and no second language to install unless you write functions in one. Desktop and server programs written in AEL alone need nothing else installed. Building a program describes every build option.

Formatting

ael fmt formats every source file the same way, and ael fmt --check lists the files it would change without changing them:

ael fmt

A first agent adds a system prompt, a node and an agent.
Project layout shows the files of a larger project.
How it works describes the four steps from source to a running program.