Maven Plugin Reference

The astra-maven-plugin adds ASTRA compilation, testing and deployment to a Maven project. Projects created from the ASTRA archetype already configure the plugin through the astra-base parent. See Quick Start to create a project and Building and Deploying ASTRA Programs for a walkthrough.

Goals

Goal	What it does
`astra:compile`	Compiles ASTRA sources from `src/main/astra` as part of Maven’s compile phase.
`astra:test`	Runs ASTRA unit tests as part of Maven’s test phase.
`astra:run`	Starts the configured main agent. Before ASTRA 2.3.0 this goal was called `astra:deploy`; that name still works but prints a deprecation warning.
`astra:debug`	Starts the configured main agent under the debugger, which waits for VS Code (the ASTRA extension) to connect and set its breakpoints. `astra.debug.port` (4711), `astra.debug.wait` (`true`) and `astra.debug.host` (`localhost`) configure it. See Debugging in VS Code.
`astra:gui`	Starts the configured main agent with the ASTRA GUI open. The GUI shows the agents and their state, the trace and its history, a profile, a timeline and a sequence diagram of the system, and the agents’ code, and can include an AI assistant. Closing the window ends the program.

mvn test compiles and runs ASTRA tests when the project uses the standard astra-base configuration. mvn astra:run starts the application directly; the archetype configures clean compile astra:run as the default goal for mvn.

See Using the ASTRA GUI for the GUI, including its options (astra.gui.theme, astra.gui.history, astra.trace.cpu, astra.gui.assistant and astra.env).

Project properties

Set these properties in the POM to select the agent started by astra:run, astra:gui and astra:debug:

Property	Default	Meaning
`astra.main`	`Main`	Fully qualified ASTRA agent class to start.
`astra.name`	`main`	Runtime name assigned to the first agent.

For example:

<properties>
    <astra.main>examples.Main</astra.main>
    <astra.name>coordinator</astra.name>
</properties>

The compile goal uses src/main/astra as its source directory and generates Java files under target/gen/java. The test goal uses src/test/astra and generates Java files under target/gen/test/java; these are managed defaults in the plugin and are not normally changed in a project POM.

Test switches

Maven option	Effect
`-DskipTests`	Compiles tests but skips running them.
`-Dmaven.test.skip=true`	Skips compiling and running tests.
`-Dmaven.test.failure.ignore=true`	Reports ASTRA test failures without failing the Maven build.

By default, ASTRA test failures fail the build. See Testing ASTRA Programs for the test format and sample output.

Tracing agent activity

Set the astra.trace system property to log agent activity to a file:

mvn astra:run -Dastra.trace=target/astra-trace.jsonl

-Dastra.trace=true writes to astra-trace.jsonl. Each line is a JSON object with the time, agent, cycle, event type and details. The events cover agents being created and terminated, state changes, events handled or unhandled, intentions added, completed or failed, beliefs added or dropped, and messages received. Java code can follow the same events by adding a TraceEventListener to astra.trace.TraceManager. No trace events are created unless a listener or the trace file is in use.