Skip to content

Running and configuration FAQ

First identify whether a failure occurs during checking, building or execution. These are common problems encountered while following the tutorials.

aalc cannot be found

Run tutorial commands inside the AAL source repository. Cargo starts the compiler, so a global aalc installation is not required:

cd Agent-Assembly-Language
cargo run --locked --bin aalc -- --help

Use Rust 1.85 or later. Prepare additional environments according to the chosen model or tool adapter's instructions.

The lock no longer matches after a change

The project lock records source and dependency contents. Confirm that the changes are intentional, then update and check:

cargo run --locked --bin aalc -- lock /tmp/aal-composition/app
cargo run --locked --bin aalc -- check /tmp/aal-composition/app

Do not edit digests manually to bypass checks. Ordinary single-file programs need no project lock.

Why can't two Account types with identical fields be exchanged?

left.Account and right.Account come from different packages and are different types. Check which object the parameter expects. For a conversion, explicitly read fields and construct the destination type.

In the account example, left_balance requires left.Account, so pass a from the left call, not b from the right.

Why didn't the result increase on the next run?

The same invocation ID resumes or replays the same request. Use a new ID for a new operation, and retain --state-dir to preserve account memory.

cargo run --locked --bin aalc -- run /tmp/aal-composition/app --agent Main --ability run --args '{}' --state-dir /tmp/aal-composition/state --invocation composition-2

A second new invocation with the same state directory continues accumulating balances. For initial values, use a new directory instead of deleting data that might still be in use.

think compiles but fails to execute

Compilation checks structure, types and effects. Executing think also needs an available model Host. First run a model-free introductory example to check the local compiler, then configure the chosen model adapter.

To test decision logic alone, pass an explicit score and use a conditional expression. See conditions and pattern matching.

Why can't contract agent run by itself?

A contract declares inputs and outputs, not an implementation. The host must supply placement and invocation configuration. A declared name is not an already connected service address. See external capabilities.

Which programs fit native executable packages?

aal.native.v1 supports local computation, memory, linked Agent calls and workflows. Programs using external models, tools or unbound remote contracts need corresponding Host configuration and cannot be packaged as dependency-free programs.

A new execution image uses isolated state during upgrades. There is currently no automatic business-state migration command. Plan an explicit migration before changing versions when historical data must be retained.