Compiling an agent or a node
In AEL, the Agent Engineering Language, ael agent compile checks one node or one workflow and writes what a Host needs to run it: the typed description of a node, or the resolved manifest of a workflow. With --source-map it also writes a source map, so a failure at run time can be traced to the line of your source it came from.
Usage
ael agent compile triage.node.ael -o triage.json
ael agent compile support.agent.ael -o support.json
ael agent compile support.agent.ael -o support.json --source-map support.map.json
| Argument or option | Meaning |
|---|---|
<file> | A node file (.node.ael) or a workflow file (.agent.ael). |
-o <file> | Where to write the description or manifest. |
--root <dir> | The project the file belongs to. A complete project links the file's callable and its declared configuration. |
--source-map <file> | Also write the source map of the workflow. |
--json | A machine-readable report, with any diagnostics. |
The command runs the checks of ael check first, and writes nothing if the file fails them.
The source map
A source map records, for a workflow and the nodes it uses, where each part is declared in your source:
- the workflow and its ports;
- every instance, with the file that defines it;
- every edge, with where the workflow lists it and where its mapper is declared;
- every node and its ports;
- every hook attached to a function, with the site it attaches at;
- every callback of a factory the project declares.
Each position is a byte range in a numbered snapshot of a source file, and the map names the digest of each file. The map holds no source text and grants nothing, and it is not part of the workflow's digest. A project that declares factories has their callbacks recorded as well; if the check of the factories refuses the project, the map keeps the workflow's origins and the refusal is named on standard error and in the --json report. A workflow file on its own belongs to no project, so no callbacks are recorded for it.
A map says which declaration a part comes from. It never claims machine code: a part the optimizer removed keeps its entry, and a part a build did not link has an origin and no code.
Using the map
ael-host serve and ael-host workflow take the map with --source-map. When a run fails or is refused, the Host prints the declaration the failure came from, with the build and the run that it belongs to: for a node that failed, its instance, its definition and the edges that feed it. Failures are sorted into four groups:
- Current: every source the map names is still the one it recorded.
- Stale: a source has changed or is missing. The recorded range is kept for the record and no line and column is given.
- Unverified: the run is source-free, so there is no source to compare with. The recorded range is given without a line and column.
- Unmapped: the map has no origin for the failure, and the reason is given.
ael build --source-map keeps writing the earlier map of native code, which debuggers use, and records no workflow origins, because a build works from compiled files. See Desktop and server.
Related
- Checking source: the checks that run first.
- Agents, nodes and edges: what a node and a workflow are.
- Reporting, logs and replay: the reports of a run.