Running Agency code

To compile and run an Agency file in one step:

agency run foo.agency

This compiles the file and then executes its main node.

This is also the default if no command is specified:

agency foo.agency

Note: This compiles the file to JavaScript and immediately executes it under the same Node binary that's running the CLI. You can also pass --resume <statefile> to resume a previously saved execution, or --trace [file] to write an execution trace.

Options

• --resume <statefile> — resume execution from a saved state file. This is what you'd use to continue a run that paused at an interrupt, after writing the user's responses into the state file. work in progress
• --trace [file] — write an execution trace as the program runs. If you don't pass a filename, the trace is written to <input>.trace. See traces and bundles for what you can do with a trace file.

A note on global installs

If you have installed agency globally, you should be aware of a classic node gotcha. A global install means that the agency CLI will be available everywhere. However, the agency-lang package can't be imported everywhere. This matters because when you compile your agency code into js, the js code imports the agency-lang package.

This means you may run into some very annoying behavior, where compiling the code is just fine

agency compile foo.agency

But when you try to run it

node foo.js

you get an error that looks something like this:

node:internal/modules/package_json_reader:316
  throw new ERR_MODULE_NOT_FOUND(packageName, fileURLToPath(base), null);
        ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'agency-lang' imported from /Users/foo/hello.js
    at Object.getPackageJSONURL (node:internal/modules/package_json_reader:316:9)
    at packageResolve (node:internal/modules/esm/resolve:768:81)
    at moduleResolve (node:internal/modules/esm/resolve:858:18)
    at defaultResolve (node:internal/modules/esm/resolve:990:11)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:737:20)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:714:38)
    at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:293:38)
    at #link (node:internal/modules/esm/module_job:208:49) {
  code: 'ERR_MODULE_NOT_FOUND'
}

If you're in an NPM project, simply install the agency-lang package locally, and this problem will go away, but if you are trying to run an agency agent as a script, just use the run command. The run command will tell node how to find the globally installed agency-lang package.

tl;dr if compile-then-run doesn't work:

agency compile foo.agency
node foo.js

Use the run command instead:

agency run foo.agency

You can also use pack to produce a standalone script that has no dependencies at all. It inlines the agency package instead of importing it, so it will run anywhere with just Node installed.