Multi-Agent Microservices (MAMS)

The current release is MAMS 2.5.9, aligned with ASTRA 2.7.12. The walkthroughs below retain their explicitly verified dependency versions.

Multi-Agent Microservices (MAMS) is an architectural style for integrating multi-agent systems into microservice applications. It lets agents expose resources through HTTP and consume resources offered by other services. A service’s clients can use its web interface without knowing ASTRA or an agent communication language.

MAMS is also the name of a reference implementation built with ASTRA and CArtAgO. This section introduces the architectural style and shows how to use that implementation with MAMS 2.4.1 and ASTRA 2.6.1, using Java 17 or later.

Learn to build a service

Read the six chapters in order on your first pass. Start with a greeting resource, learn resource contracts and request policies, then build a delivery service with cooperating agents. Each chapter has Further Details for the existing reference material, optional representations and complete example sources.

Chapter	What you will learn
Publish your first service	Expose an item, use HTTP and observe a replacement.
Manage resources	Create collections, own state and create custom artifacts directly.
Decide how requests are handled	Choose passive or active management and implement a policy.
Connect services	Make requests, follow resource identities and subscribe to changes.
Build a cooperating service	Coordinate delivery work and publish progress and failure.
Test and deploy	Verify contracts, package a service and reason about its lifecycle.

The main path uses Java-Types resources and the downloadable examples. HAL, Hydra, WebSub and custom-artifact details remain available beneath their relevant chapters. The architectural background below explains why these mechanisms fit together.

Where agents fit in a microservice application

MAMS distinguishes Plain-Old Microservices (POMS) from Agent-Oriented Microservices (AOMS). A POMS implements its capability with conventional service code. An AOMS uses one or more agents to implement its capability, including proactive behaviour: pursuing goals, monitoring changes and deciding when to act.

For example, a delivery application might retain ordinary services for orders and stock while an agent service monitors delivery requests, chooses couriers and revises assignments when circumstances change. Both kinds of service participate in the same application through agreed web interfaces.

The delivery service exposes MAMS resources to clients and to the order and stock services. Either a POMS or the AOMS can initiate an HTTP request to the other: ordinary services can read or update the agent service’s resources, and the agent service can call their web interfaces. The bidirectional HTTP arrows show these two possible directions of interaction. Its agents coordinate internally through ASTRA messages. The enclosing box represents the service boundary.

An AOMS can contain several agents. Some may expose web resources; others may perform internal reasoning or coordination using ASTRA messages. Choose the service boundary around the business capability, then decide which agents and resources implement it. An agent does not need its own process or container.

The brain, body and integration layer

A MAMS agent combines three parts:

Part	Purpose	ASTRA–CArtAgO implementation
Brain	Maintains beliefs, pursues goals and chooses actions	An ASTRA agent
Body	Exposes a hierarchy of web resources	CArtAgO resource artifacts
Integration layer	Makes resource state and requests available to the brain, and lets it change the body	CArtAgO operations, observations and signals, wrapped by MAMS agent classes

The upward path keeps the brain informed about resource state and incoming requests. The downward path lets the brain inspect or change resources and decide whether an active request may proceed. External services interact with the body through HTTP.

The body’s root is the resource base. Its URI identifies the agent, for example http://localhost:9000/main. Attached resources have paths beneath it, such as /main/hello or /main/orders. The name main is the running agent’s name, rather than its ASTRA class name Main.

Clients interact with these resources through HTTP. The agent receives observations or events and can perform further work. For example, a client creates a delivery request, and the agent subsequently assigns a courier and updates the request’s state. The HTTP response and completion of the agent’s business task are separate steps.

The architectural style does not require ASTRA or CArtAgO. They provide the brain and body in this reference implementation. Its web server and REST client artifacts are shared within an application; each exposed agent creates its own resource base.

Choose how resources are managed

Passive resource management lets the resource implementation process supported HTTP requests directly. The agent observes state and receives notifications of changes. Use it when clients can create or update data without waiting for a decision from the agent.

The passive diagram follows a successful PUT. The response and notification are separate outcomes of the update; their relative delivery and the agent’s subsequent work are not synchronised by the HTTP response.

Active resource management intercepts supported HTTP requests and notifies the agent before they are processed. The agent can inspect the request and accept or refuse it. Use it when access to a resource depends on the agent’s current state or a decision it must make.

The active diagram shows two alternative decisions for one supported PUT request. Acceptance invokes the resource’s handler, which updates the resource and still notifies the agent of that change. The request decision is an additional step before processing, not a replacement for observing the update. Acceptance does not mean the agent has completed all related business work. In the current Java-Types implementation, the inherited handler accepts by default, so an application must override it to apply its own policy.

These choices describe resource management, not whether an agent is proactive. A proactive agent can use passive resources. An application can also combine resource types and management strategies.

Start with Java-Types resources

The Java-Types library uses a Java class to describe resource data. Its fields become observable properties, and its state is represented as JSON. It provides individual items, collections and items belonging to collections. This is a useful starting point for learning the lifecycle of a MAMS service.

Follow Your first MAMS service to publish an item and react to an HTTP update. Continue through Manage resources, Request policies and Connect services. The resource detail page retains the operation and HTTP explanations.

The MAMS example projects extend this walkthrough with the collection, client-agent, ping-pong, sum, active resource and HAL scenarios from mams-guide. Each comes with a downloadable project adapted for the versions used here.

For an application that combines request submission, courier assignment, progress and failure recovery, follow Build a delivery service. The resource API reference distinguishes the goals, beliefs, signals and operations used by these examples.

MAMS 2.4.1 also offers optional Hydra/JSON-LD representations for existing resources. Since 2.4.0, resources can carry custom headers and links, and agents can follow resources on other services with WebSub. Other implementation modules cover JSON Schema, HAL, RDF/Jena and ActiveMQ integration. REST resources are the focus of this walkthrough; consult the corresponding modules for their representation and messaging APIs.

Versions and source material

The upstream example guide identifies its examples as MAMS 1.0.10 and uses older ASTRA dependencies. The examples in this section use ASTRA 2.6.1 with MAMS 2.4.1. Source verification targets MAMS commit 280367e, which updates the ASTRA dependency to 2.6.1.

Examples here follow the current implementation where older descriptions differ. In particular, the current Java-Types active agent has a default handler that accepts requests; extending it alone does not install a refusal policy. See Active request handling.

The architectural introduction follows the chapter draft Integrating MAS with Microservices, especially its sections on the MAMS architectural style, agent anatomy and reference framework. The public repositories provide further examples and implementation details:

• MAMS guide and example projects

• MAMS reference implementation

• ASTRA CArtAgO integration

Moving from MAMS 1.1.1 to 2.x

Update all MAMS dependency versions to 2.4.1, including any optional representation modules. The ASTRA examples use the astra-cartago-base:2.6.1 parent and a Java 17 target. Existing mams.javatypes.Passive and mams.javatypes.Active goals, resource notifications, default active acceptance and the 30-second decision timeout are unchanged by this release.

Hydra is optional: add mams-cartago-hydra:2.4.1 to the service’s runtime dependencies and request application/ld+json. Existing JSON and HAL clients continue to use their current representations. Hydra discovery adds the reserved hydra/context and hydra/api-documentation routes beneath supported resources; avoid treating hydra as an application child path.

The historical mams-cartago-javatypes-old source tree has been removed. Use the current mams-cartago-javatypes artifacts. Supported command-based HAL compatibility classes remain available. The upstream mams-test-* projects have moved to the MAMS test examples repository; the downloadable examples in this guide remain self-contained.

Source verification rebuilds the pinned release in an isolated Maven repository. A separate check resolves published 2.4.1 dependencies without installing source artifacts; compilation alone does not prove that a published JAR is byte-for-byte identical to a source build.

See Deploying a MAMS Service for Java and container launch instructions, and Verifying the MAMS Examples for automated checks.