EIS Environments

The Environment Interface Standard (EIS) connects agents to environments through a common Java interface. Environments expose entities that agents can control, actions they can perform and percepts describing their state.

ASTRA integrates EIS through the EIS module. This guide targets ASTRA 2.6.1 and assumes you have completed the Quick Start. Choose astra-eis-0.5 or astra-eis-0.7 to match the API version required by your environment; do not add both adapters to the same project because both supply astra.lang.EIS.

Concepts

Concept	Meaning	ASTRA interface
Environment	An EIS implementation loaded from a JAR	`eis.launch(id, jar)`
Registration	An agent participates in the environment	Launching registers the creator; `eis.join(id)` registers another agent
Entity	Something in the environment an agent can control	`eis.link(entity)`
Action	An operation defined by the environment	`eis.perform(entity, action(...))`
Percept	State received from an associated entity	`eis.check(entity, percept(...))`
Management event	Environment state or entity availability changes	`$eis.event(...)`

ASTRA combines EIS’s agent and management interfaces in one module. Each module instance connects to one environment. The environment service is shared within the JVM, while registration and entity associations belong to each agent. Percepts are held by the adapter and queried through check; they are not ordinary beliefs inserted into the agent’s belief base.

Project setup

Keep the astra-base parent and Maven plugin from the Quick Start. Add the adapter matching your environment:

<dependency>
    <groupId>com.astralanguage</groupId>
    <artifactId>astra-eis-0.7</artifactId>
    <version>2.6.1</version>
</dependency>

For EIS 0.5, use astra-eis-0.5 instead. Obtain the environment JAR and any required dependencies using that environment’s instructions. Paths supplied to launch are resolved from the application’s working directory. Adding the ASTRA adapter does not install an environment.

Use the environment

Create src/main/astra/Main.astra:

agent Main {
    module EIS eis;
    module Console console;

    plan +!main(list args) {
        eis.launch("demo", "environments/MyEnvironment.jar");
        eis.init();
        console.println(eis.allEntities());
        eis.link("robot");
        eis.start();
        console.println("environment state = " + eis.getState());
    }
}

This is a template for an installed environment, not a bundled runnable example. Replace the JAR path and robot with values supported by that environment. If it requires initialization parameters, use a list of single-argument function terms, for example eis.init([width(10), mode("demo")]);. Parameter names and acceptable values are defined by the environment.

Launch once, initialize, link to the intended entity and start the environment when its lifecycle permits. The launching agent is already registered: do not call join on that same module. link() without an argument uses the agent’s name as the entity name. Each successful link sets the module’s default entity, so use explicit entity names when controlling several entities.

Build and run with:

mvn clean compile astra:run

The environment must define the actions you perform. For example, if it offers a move action accepting a direction:

eis.perform("robot", move("north"));

Equivalent forms are eis.perform("robot", "move", ["north"]); and, for the default entity, eis.perform(move("north"));. Action arguments in these adapters are primitive values: numbers become EIS numerals and other primitive values become identifiers. Do not assume nested function or list arguments are supported.

Observations and events

If the environment publishes a position percept with integer coordinates, wait for or query it as follows:

wait(eis.check("robot", position(int X, int Y)));
query(eis.check("robot", position(int CurrentX, int CurrentY)));
console.println("position = " + CurrentX + ", " + CurrentY);

Use the percept names and types defined by your environment. check(position(...)) queries the default entity; check("robot", position(...)) identifies the entity explicitly. Perception updates are asynchronous, so an action completing does not establish that its resulting percept is already available.

Add plans to react to additions and removals:

plan +$eis.event(string Entity, position(int X, int Y)) {
    console.println(Entity + " is at " + X + ", " + Y);
}

plan -$eis.event(string Entity, position(int X, int Y)) {
    console.println(Entity + " no longer reports " + X + ", " + Y);
}

The first argument identifies the entity. The one-argument form, such as +$eis.event(position(int X, int Y)), matches percept events without restricting the entity.

Management events omit the addition/removal symbol and entity argument:

plan $eis.event(state(string State)) {
    console.println("environment changed to " + State);
}

plan $eis.event(newEntity(string Entity)) {
    console.println("new entity: " + Entity);
}

The adapter also emits deletedEntity(string Entity) and freedEntity(string Entity). Registered agents receive these management notifications; entity percepts require an entity association. State strings come from EIS’s environment-state representation.

Results and failures

Use try/recover around actions that may fail:

try {
    eis.perform("robot", move("north"));
} recover {
    console.println("the environment action failed");
}

perform returns failure to the intention for EIS action and missing-environment exceptions. Some management methods log underlying errors without propagating failure: for example, start() returns success even if the service’s start request fails. Check getState() and resulting percepts when confirming readiness or an effect.

Call dumpState() to inspect the connected environment and cached percepts. For missing percepts, check registration, entity association, environment state and argument types. The adapter’s reset overloads currently call initialization rather than an EIS reset operation; do not rely on them to restore a running environment. sensorBlocking(false) disables the sensing path implemented in these adapters; keep its default true for normal perception.

API reference

Declare module EIS eis;. Actions are statements; terms return values; formulae are queried in guards, query(...) or wait(...).

Kind	Call	Purpose
Action	`launch(string id, string jar)`	Load a named environment and register this agent.
Action	`join(string id)`	Register with a service already launched in this JVM.
Action	`init()` / `init(list parameters)`	Initialize with no parameters or single-argument function terms.
Action	`link()` / `link(string entity)`	Associate the agent with an entity and select it as default.
Action	`start()`	Request that the environment start.
Action	`reset()` / `reset(list keys, list values)`	Currently invokes initialization; parallel key/value lists must have matching lengths.
Action	`perform(funct action)` / `perform(string entity, funct action)`	Perform a function-term action on the default or explicit entity.
Action	`perform(string action)` / `perform(string entity, string action)`	Perform an action without arguments.
Action	`perform(string action, list args)` / `perform(string entity, string action, list args)`	Perform an action with an argument list.
Formula	`check(funct percept)` / `check(string entity, funct percept)`	Match a cached percept.
Formula	`check(string predicate, list args)` / `check(string entity, string predicate, list args)`	Match a percept using its name and argument list.
Term	`id()`	Connected service identifier as a string.
Term	`freeEntities()` / `allEntities()`	Lists of free or all entity names.
Term	`getEntityType(string name)`	Entity type as a string.
Term	`getState()`	Environment state as a string.
Action	`sensorBlocking(boolean enabled)`	Control the implemented sensing path.
Action	`dumpState()`	Print cached percepts and connection details.

Percept events use +$eis.event(Entity, percept(...)) and -$eis.event(Entity, percept(...)). Management events use $eis.event(event(...)), as shown above.