Trying functions in other languages
In AEL, the Agent Engineering Language, your application can hold private functions in other languages. ael foreign lists the ones a project declares and calls one of them on its own, so you can try a function with real arguments before any AEL code calls it.
Usage
ael foreign list PROJECT
ael foreign list PROJECT --json
ael foreign call PROJECT FUNCTION --arg 21
ael foreign call PROJECT FUNCTION --arg '"AEL"' --timeout 10
PROJECT is a project folder with main.ael, pack.ael and metadata.ael. Both commands build the project's functions first, with the toolchains you installed, and refuse a project that declares none.
Listing
ael foreign list prints one line for every function: its language, the file that declares it, its name, the number of parameters, its mode, its version pin, and the toolchain that was found, with its version and its digest. It calls nothing.
Calling
ael foreign call runs one function and prints its result.
| Option | Meaning |
|---|---|
--arg VALUE | One argument as a JSON value, once for each parameter, in order. Each value is checked against the type the signature declares before anything runs. |
--owner FILE | The file that declares the function, needed when two files declare the same name. |
--timeout SECONDS | The longest the call may run, from 1 to 3600. |
--memory MIB | The most memory the call may use, from 1 to 65536. |
--mode sandbox | Run the function in a sandbox even when it declares the default mode. |
--env KEY=VALUE | Give the function one environment variable. Only the names the function lists in its own env option, and the few variables every function receives, are accepted. |
--kernel-layers require | Refuse to run unless the host can apply every isolation layer of the sandbox. With record, the default, the report says which layers were applied and which were not. |
--report-channel NAME | Also print the figures of this call (calls, time, output bytes, child processes, the effects that are unknown) in the form a server channel with that name sends beside its report. NAME is one of the reporting channels, such as cli or http; a channel that is switched off says so. Model tokens are always reported as unknown. |
--json | The report in machine-readable form. |
What a call guarantees
- The pinned toolchain. The function runs with the runtime its language needs, at the version it pins. A missing runtime, another version or a missing sandbox fails the call before the function starts.
- Typed in, typed out. Arguments are passed as typed values and are never spliced into a command line or into the text of a script. The result is decoded into its AEL type; a result that does not decode is reported as a decode failure, never as a value. The exit status of the function is never read as its result.
- A clean environment. The function starts with an empty environment that holds only the few variables every function receives and the ones you named. The values of the variables you named are removed from any error output the report shows.
- Limits and cancellation. The time and memory limits apply to the function and to every process it starts. A passed time limit or a cancellation stops all of them.
- A report. The result comes with the toolchain that ran, the limits that applied and the charge the call made to the run's budget. For a function in sandbox mode, the report lists each isolation layer and whether it was applied.
- Your hooks. A hook attached to the entry of the function runs before it, sees the declared parameters and can stop the call; a hook attached to its exit runs after it and sees the outcome, and the result when the call succeeded. The hooks and the call are charged to the same budget. Hooks run only where the agent component is installed: without it a project with hooks is refused, never run unguarded.
Where it runs
Isolation layers need Linux. On other hosts the report says that a layer is not available, and --kernel-layers require refuses the call. Supported targets names the Linux target where the sandbox runs.
Related
- Functions in other languages: how to write them, their options and the languages you can use.
ael check: checks the whole project, including these signatures.ael fmt: formats the signatures of these functions with the rest of the project.