Enterprise guide

Build agents for an enterprise fleet

Build an agent, learn the four cards the fleet reads about it (AgentCard, AssetCard, ModelCard, and AppCard), run it on Embabel, Spring AI, LangChain4j, or Micronaut, and bring it under the Bad Monkey console, either by pointing the console at the group it already runs in or by deploying it as a package.

AgentSpaces 0.6.0four cards, each signed and leasedthe console's bma command line, web UI, and API on port 7580two ways in: attach or deploy
aspace://guide/enterprise/fleet

An enterprise fleet and its four cards

This guide is for an engineer who has built an agent, most likely the fulfiller of the quick starts, and now wants to run it in a fleet that the Bad Monkey console manages. It says what to write, what the fleet learns about your agent, and how to bring the agent under the console. The how and the why are in the appendix.

A few words first:

  • A peer is one running process in the fleet. It holds its own key and signs what it writes.
  • A group is the set of peers that work together. Every peer given the same founding text, such as shop-v1, derives the same group id.
  • A space is a named, replicated store inside a group, such as orders. An entry is one typed value in it, such as an Order, and a lease says how long the entry lives.
  • An agent is a class whose methods take or watch entries. The binder reads the agent's annotations, runs its loops, and publishes its card.
  • A card is a signed advertisement with a lease that a peer publishes into its group, so the other members can find what it offers.
  • The console is the Bad Monkey management console. It runs in a group of its own and reaches your group through a bridge, a console peer that joins your group as a member.
  • A tenant is the console's isolation boundary. What a tenant owns is its fleet: the managed groups the console holds and every agent in them. An operator bound to a tenant is a fleet manager.

The four cards in one picture

Four kinds of card describe what a fleet offers. Your agent publishes one of them, the AgentCard, without any code from you. The other three come from connectors, model servers, and the console.

THE FOUR CARDS, AND WHO ISSUES EACHAgentCardan agent and its workgoalsconsumes, producesactions, uiISSUED BYthe binder on youragent's peerttl 15 minAssetCarda data asseturi, shapefreshness, accesscostHintsISSUED BYa connector peer(AssetProvider)ttl 15 minModelCarda model a group may usename, version, tasksengine, residencyserversISSUED BYthe console at admission;a model server for itselfttl from the recordAppCardan application for peoplekind, shape, readsactions, ui, hostorigin, formatsISSUED BYthe console at admission(or AppCardPublisher)ttl from the recordEvery card: signed by its issuing peer, leased by its ttl, refreshed by re-publishing,and gossiped into the ad cache that every peer of the group keepsAgents and plannersfind(AgentCard.class, ...)a card's actions becomeremote actions and toolsThe model gatewaytakes a ModelRequest bytask or model name and routesit to an admitted modelThe consoleshows every card it reads;admits ModelCards andAppCards into the group
The four cards. Each card has one issuer. All four travel the same way, and three kinds of reader use them. An AppCard names the agent that draws its pages and the actions it may request; an agent names no ModelCard, and addresses a model by name in a ModelRequest.
CardWhat it saysWho issues itWhere you define it
AgentCardan agent: what it pursues, the entry types it consumes and produces, its actions, what it can showthe binder on the agent's own peerannotations on your agent class: @AgentSpec, @SpaceAgent, or Embabel's @Agent
AssetCarda data asset: its source URI, its shape, how fresh it is, how to query itthe connector peer that holds the assetan AssetProvider that a ConnectorRuntime runs
ModelCarda model the group may route to: its tasks, engine, licence, residency, and serversthe console when it admits the model, and a model server for itselfthe console's Model Market, the bma model commands, or the model credentials file
AppCardan application people use: how it connects, what it reads, the actions it may request, its UIthe console when it admits the appMETA-INF/bma/app.json in your jar, an agent's Publish, the console's Apps screen, or AppCardPublisher in code

What every card has in common

All four cards travel the same way, so what you learn about one holds for the others:

  • Signed. The issuing peer signs the card with its own identity.
  • Leased. Every card carries issued and ttl. The issuer publishes it again with a new issued before the ttl runs out. A card nobody refreshes ages out of every cache, which is how the fleet learns that an agent or a connector is gone.
  • Gossiped. Every peer keeps an ad cache per group, and gossip fills it. discovery.find(type, predicate) searches the local cache first; remoteFind asks the group's other peers too.
  • Asserted, then enforced by the reader. A card says what its issuer claims. The party that reads it decides what to allow: the console admits an AppCard and enforces what the app may read and request.
Note. None of the four cards has a size cap. A very large AgentCard or AppCard travels as a small stub with its large parts on the content swarm. The appendix explains the spill.
aspace://guide/enterprise/first-agent

Build your first agent

Most readers arrive with the fulfiller: an Order goes into the space orders, and the agent writes back a Shipment. It runs in the group shop, founded from the text shop-v1. This part shows it in Java, then briefly in the other languages, and then what the fleet learns about it.

The fulfiller in Java

With the Spring Boot starter, @SpaceAgent makes a class both a Spring bean and an agent. @SpaceTake marks the method that takes work: its parameter type is the entry it takes, and its return value is the entry it writes back.

// Fulfiller.java
@SpaceAgent(name = "fulfiller", description = "Ships orders and writes a packing note")
public class Fulfiller {
    private final ChatClient chat;

    Fulfiller(ChatClient.Builder builder) {
        this.chat = builder.build();
    }

    @SpaceTake(lease = "2m")
    public Shipment ship(Order order) {
        String note = chat.prompt().user("Write a one-line packing note for: " + order.item()).call().content();
        return new Shipment(order.orderId(), order.item(), note);
    }
}
  • @SpaceTake(lease = "2m") takes one Order under a two-minute lease, calls ship, writes the returned Shipment, and completes the take. If the process dies first, the lease lapses and the order comes back for another worker.
  • The method names no space because the group declares only one. An empty space means the sole space.
  • ChatClient is Spring AI's. The quick start runs it over a stub ChatModel, so it needs no API key.

The configuration names the peer's address and its group:

# application.yml
spring:
  main:
    web-application-type: none   # the fleet is the interface
    keep-alive: true             # nothing else holds the JVM open

agentspaces:
  bind: 127.0.0.1:${shop.port:7701}
  groups:
    - name: shop
      founding: shop-v1
      seeds: ${shop.seeds:}      # empty on the first instance
      spaces:
        - name: orders

The project depends on agentspaces-spring-boot-starter and agentspaces-springai 0.6.0, with the agentspaces-dependencies 0.6.0 BOM imported. There is no @EnableAgentSpaces: the starter dependency and the agentspaces.* properties switch everything on.

Run two instances

Build the jar and start it twice, from two terminals:

mvn -q package
java -jar target/shop-springai-1.0.0.jar
java -jar target/shop-springai-1.0.0.jar --shop.port=7702 --shop.seeds=127.0.0.1:7701 --shop.order=kite

The first instance founds shop on port 7701. The second listens on 7702, dials the first as its seed, writes an order for a kite, and prints the Shipment it reads back. Either instance may take the order.

Both instances run under the starter's default security profile, mtls, which secures every link with TLS. Keep that in mind when you attach the console.

The same agent without a framework

The Jungle Gym tutorial writes the fulfiller as plain Java over FleetRuntime, the host that LangChain4j applications also use. @AgentSpec names the agent, and peer.bind hands it to the binder:

// Step03.java
@AgentSpec(name = "fulfiller", description = "Ships orders")
public static class Fulfiller {

    @SpaceTake(lease = "30s")
    public Shipment ship(Order order) {
        return new Shipment(order.orderId(), order.item(), "fulfiller", "");
    }
}

static void run() {
    FleetRuntime peer = FleetRuntime.start(PropertiesLoader.yaml(Path.of("src/main/resources/peer-a.yaml")));
    peer.bind(new Fulfiller());
    // ...
}

Its peer reads the same agentspaces: YAML as the Spring Boot host, under the dev-local profile:

# peer-a.yaml
agentspaces:
  security:
    profile: dev-local        # signed frames on loopback TCP; production uses mtls
  bind: 127.0.0.1:7701
  groups:
    - name: shop
      founding: shop-v1       # the group id is derived from this text
      spaces:
        - name: orders

The dev-local profile signs every frame over plain loopback TCP: use it on a laptop, never on a shared network.

The same agent in other languages

Every client names the agent and its take the same way, and every one publishes an AgentCard on bind. The Python, TypeScript, and Ruby quick starts dial a seed on port 7700, the Node service host, under dev-local.

# fulfiller.py
@agent("fulfiller", description="Ships orders")
class Fulfiller:
    @space_take("orders", lease="30s")
    def ship(self, order: Order) -> Shipment:
        return Shipment(order.orderId, order.item, "fulfiller")
# ...
Binder(peer, agent=identity.renewing_subordinate("fulfiller", "PT24H")).bind(Fulfiller())
// fulfiller.ts
@agent("fulfiller", { description: "Ships orders" })
class Fulfiller {
  @spaceTake(Order, "orders", { lease: "30s", produces: Shipment })
  ship(order: Order): Shipment {
    return new Shipment(order.orderId, order.item, "fulfiller");
  }
}
# fulfiller.rb
class Fulfiller
  include AgentSpaces::Agent
  agent "fulfiller", description: "Ships orders"

  take Order, space: "orders", lease: "30s", produces: Shipment
  def ship(order) = Shipment.new(order_id: order.order_id, item: order.item, by: "fulfiller")
end
;; fulfiller.clj
(defagent Fulfiller
  {:description "Ships orders"}
  (take ship [^Order order] {:space "orders" :lease "30s"} ^Shipment
    {:orderId (:orderId order) :item (:item order) :by "fulfiller"}))
// fulfiller.groovy
bind agent('fulfiller', description: 'Ships orders') {
    take(Order, space: 'orders', lease: '30s', returns: Shipment) { Order order ->
        new Shipment(order.orderId(), order.item(), 'fulfiller')
    }
}

The Python, TypeScript, Ruby, Clojure, and Groovy guides take each language from install to running examples.

What the fleet learned about your agent

When the binder bound the fulfiller, it built an AgentCard and published it into shop. You wrote no card. The binder derived it:

  • the id aspace://<group id>/agent/<peer id>/fulfiller;
  • the description and goals from @SpaceAgent or @AgentSpec;
  • consumes with shop.Order#v1 and produces with shop.Shipment#v1, the wire names of the two Java records;
  • one action per bound method, here ship, with the space it takes from;
  • a ttl of 15 minutes. Every JVM host (Spring Boot, Micronaut, and FleetRuntime) publishes the card again every agentspaces.card-refresh-millis, five minutes by default.

Any peer of the group can now find the agent by what it does. The Jungle Gym's step 08 finds the fulfiller's card from a second peer:

// Step08.java
AgentCard card = b.context().group().discovery()
        .find(AgentCard.class, c -> c.agent().localName().equals("fulfiller")).get(0);
System.out.println("found card " + card.agent().localName());
System.out.println("  takes " + card.consumes() + ", writes " + card.produces());

The same step goes on to call the card's action as a remote action, which is how planners and model tool loops use your agent without knowing where it runs.

aspace://guide/enterprise/cards

The four cards

Each section below says what the card means, its key fields, where you define it, a real excerpt, and how the console shows it.

AgentCard

An AgentCard describes an agent: the goals it can pursue, the entry types it consumes and produces, cost hints, and the space it takes each input from. The cards of a group act as its routing table. A caller finds who produces a type and writes the input where that agent takes it.

FieldWhat it holds
id, issuer, group, issued, ttlthe envelope every card has; the ttl is 15 minutes
agentthe agent's id; its local name comes from name on @AgentSpec or @SpaceAgent
description, goalsfree text for people, planners, and semantic discovery
consumes, producesthe entry schema names, such as shop.Order#v1
costHintsa free map; Embabel cards carry framework=embabel
spaceBindingseach consumed schema mapped to the space the agent takes it from
actionsone CardAction per bound method: name, description, consumes, produces, space, kind, and an optional contract (pre, post, cost); at most 64
uithe A2UI components the agent can show, from @UiComponent
agentPublicKey, agentCertificatepresent when the agent signs with a key of its own

Where you define it: you never build an AgentCard by hand. The binder derives it from your code.

  • @AgentSpec(name, description, goals) on a plain class, or @SpaceAgent with the same three attributes on a Spring Boot or Micronaut bean.
  • Each binding annotation on a method (@SpaceTake, @SpaceNotify, @OrderedTake, and the rest) becomes one action. Its description attribute becomes the action's description, and pre, post, and cost become its contract.
  • @UiComponent on the class fills ui, so a console can assemble an application from a group's cards.
  • Embabel's @Agent, @Action, and @AchievesGoal produce the card through the Embabel extension, described below.
  • In the other languages, the agent decorator, the agent class macro, or defagent names the agent as @AgentSpec does.

The platform's greeter example shows every piece on one class:

// Greeter.java
@SpaceAgent(name = "greeter", description = "Greets, and answers the simplest questions in the chat: hello, what services are available, help",
        goals = {"every Greeting on the hello lane gets a Reply", "every chat line from a person gets an answer"})
@DataUse(reads = {"hello.Greeting"}, writes = {"ai.badmonkey.bma.example.greeter.Reply"}, source = "space:hello", freshness = "PT1S")
@UiComponent(catalog = "agentspaces-widgets", component = "ChatInput", entry = ChatMessage.class, entryIri = ChatMessage.IRI, role = "control", reads = true, writes = true)
public class Greeter {
    // ...
    @SpaceNotify(space = "conversations", resultLease = "P30D",
            description = "Answers a person's line in this chat with a greeting, the services here, or help")
    public ChatMessage chat(ChatMessage message) {
    // ...
    @SpaceTake(space = "hello", lease = "1m", description = "Answers every Greeting with a Reply in the configured template")
    public Reply greet(Greeting greeting) {
  • The card has two actions, chat (kind notify) and greet (kind take), each with its own description.
  • @UiComponent says the agent can serve the ChatInput component of the open agentspaces-widgets catalog, so ui lists one component.
  • @DataUse is the platform's annotation. It feeds the console's data catalog and is no part of the card.

A package manifest can also list the cards a package will publish, under cards:. The console reconciles that list against the live cards, and it proposes grants from it: a take action proposes SPACE_TAKE on its space.

# bma.package.yaml
cards:
  - agent: ClaimSummarizer
    actions:
      - name: summarize
        consumes: [org.example.claims.RegisteredClaim]
        produces: [org.example.claims.ClaimSummary]
        kind: take
        space: intake

How the console shows it:

  • The group page's Agents tab has one row per card: the agent, its kind, state, replicas, the peer that hosts it, and what it consumes and produces. Two running instances of the fulfiller are two rows.
  • The agent page (#/fleet/agent/<group>/<name>) has a Card panel with Consumes, Produces, and Actions, then Deployment, Its UI (the apps and pages the agent draws), Hints, Data use, and Findings. An agent that the core binder published carries its full card id as its name, aspace://<group>/agent/<peer>/<name>.
  • The group's canvas draws a block per card with its action count, between the peer that runs the agent and the spaces it uses.

AssetCard

An AssetCard is the AgentCard's sibling for a peer that provides data and pursues no goals. A connector joins a group on behalf of a warehouse, a database, a search cluster, a message broker, or a web service, and publishes one AssetCard per asset it holds. Agents find assets the same way they find agents: by structure in the ad cache, or by meaning through semantic discovery.

FieldWhat it holds
assetthe asset's name, unique within the issuing peer
urithe source system's URI, such as postgres://ops/public.orders
descriptionwhat the asset holds, for people and semantic discovery
shapean entry schema name, a table structure, an index mapping, or a message format
freshnessthe update cadence, such as PT5M or daily
costHintssize and cost hints, such as rows
accesshow to reach it: mode=read-only, query=aspace:cap/data-query, and the read and invoke operations it allows

Every field is required. The issuer signs the two maps in their iteration order.

Where you define it: implement the connector interface AssetProvider, one implementation per source system. Its describeAssets(group, issuer, now) returns the cards, and query(asset, parameters) answers one query. A ConnectorRuntime publishes the cards, serves the data-query protocol through a space, and keeps the connector honest about freshness. The stock TableAssetProvider builds its card like this:

// TableAssetProvider.java
@Override
public List<AssetCard> describeAssets(GroupId group, PeerId issuer, Instant now) {
    return List.of(new AssetCard(
            "aspace://" + group.value() + "/asset/" + asset,
            issuer, group, now, Duration.ofMinutes(15),
            asset, uri, description, shape, freshness.toString(),
            Map.of("rows", String.valueOf(rows.size())),
            Map.of("mode", "read-only", "query", "aspace:cap/data-query")));
}

Example 10 runs it as a connector and finds the asset by meaning from another peer:

// DataFleet.java
return new TableAssetProvider("orders", "postgres://ops/public.orders",
        "Customer order history with line items and settlement status",
        "com.example.OrderRow#v1", Duration.ofMinutes(5),
// ...
try (ConnectorRuntime connector = new ConnectorRuntime(connectorPeer.data(),
        connectorPeer.discovery(), connectorPeer.node().identity(),
        "pg-connector", provider, connectorPeer.runtime().id(),
        InstantSource.system(), Duration.ofMinutes(1))) {
    connector.start();
// ...
    var matches = analystA.semantic()
            .remoteQuery("who holds customer order history?", 3,
                    Duration.ofSeconds(2));
    AssetCard card = (AssetCard) matches.get(0).advertisement();
  • connector.start() publishes the cards. Call refreshCards() on the same cadence as your other leased state, because the Spring Boot starter does not wire an AssetProvider bean into a ConnectorRuntime for you.
  • Other providers ship ready: Spring AI's vector-store provider publishes a dataset, and Micronaut's agentspaces.micronaut.service-asset.enabled publishes the service itself as an AssetCard.
  • A content store advertises itself with an AssetCard too, with asset set to content-store:<name> and its capacity and policy in access.

How the console shows it: Data catalog › Assets lists every asset with its group, path, source, shape, sensitivity, freshness, and who declared it. On the console, a source you add under Sources deploys the platform's connector for it, and its assets appear once the connector advertises its cards.

ModelCard

A ModelCard advertises a model a group may route to. An AssetCard cannot say what a model needs said: that someone admitted it, where it may run, and who serves it. A model reaches a group only as an admitted card, and the console signs the card when it admits it.

FieldWhat it holds
name, versionthe name a ModelRequest addresses, and its version
tasksfrom chat, embed, rerank, classify, transcribe, vision
modality, limitssuch as text, and context and output limits
licence, provenancethe licence, and upstream, weightRoot, weightHash, admittedBy
evals, costHintsevaluation results (at most 64), and hints such as pricePerThousandTokens
residencysites, classifications, and releasable
engineprovider, ollama, vllm, or onnx (later values are reserved)
serversthe peers that hold the model

Only the envelope and name are required. The id is aspace://<group>/model/<name>@<version> by convention, and discovery.find(ModelCard.class, predicate) filters by name, task, engine, and residency site.

Where you define it: in the console, never on your agent. There are three ways:

  • Bind a provider. The model credentials file model-auth.edn names a provider (:provider, :api-key, and optionally :models, :base-url). The console reads the file that bma.models.auth-file names, else model-auth.edn in its home, else the one in the directory you start it from, so never start a test console from a directory that holds a real key. The console puts the key in its vault, and binding the provider to a group from the Models screen's Providers card admits one card per model into the group. On a laptop or in tests, bma.models.mock=true binds a provider named mock with the models mock-chat and mock-fast, which needs no key.
  • Fill in the form. Models › Model Market › New model card asks for the model (id, name, version, group), where it runs (engine, tasks, upstream, price), and its licence and residency.
  • Use the command line, which posts the same record to the console's API. Only --id, --name, and --group are required. The version defaults to 1, the engine to provider, and the tasks to chat, and the options you leave out stay empty on the card.
bma model put --id chat-small --name mock-chat --group shop --engine provider --tasks chat \
  --licence Apache-2.0 --sites local --classifications public --price 0 --upstream mock
bma model submit --id chat-small      # goes to Approvals when governance asks for models
bma model admit --id chat-small       # the console signs the card and the bridge carries it into the group

At admission the bridge writes the console's record into the group's models space and publishes the same card as a signed advertisement, so the gateway and every client find it by discovery. The console builds the advertisement this way:

// WriteSetCommands.java
return new ai.badmonkey.agentspaces.api.ad.ModelCard("aspace://" + group.value() + "/model/" + c.name() + "@" + c.version(), issuer.peerId(), group, now,
        ttl.compareTo(Duration.ofDays(30)) > 0 ? Duration.ofDays(30) : ttl, c.name(), c.version(), c.tasks(), c.modality(), strings.apply(c.limits()), c.licence(),

How your agent uses a model: an AgentCard names no ModelCard. An agent writes a ModelRequest into the group's model-requests space, and the group's model gateway takes every request tagged task=<kind> or addressed to the gateway's own model name (gateway by default). The gateway routes it to an admitted model. A package declares the need in its manifest as a dependency of kind model with a task, such as task: chat. Models through the gateway has the settings.

How the console shows it: Models › Model Market lists each card with its group, engine, tasks, licence, state, and servers. A card's page shows its tasks, licence (with a "check the licence" badge when the licence is not permissive), residency, provenance, cost hints, and servers, with the buttons Submit for admission, Admit, and Place on an engine.

AppCard

An AppCard advertises an application that a person uses, joined to a fleet. A console finds it by discovery, admits it, and binds it to the agents that feed it. Three fields answer three questions:

  • kind says how the app connects. It is a closed set: peer (the app is a member), fed (an agent of the group feeds it), gateway (it sits behind the A2A gateway), or assembled (a static app its publisher assembled from extracted data, which reads nothing live).
  • origin names the external system the app came from, such as console for an app the console drafted. It is open.
  • formats lists the media types or vocabulary IRIs the app reads or renders, from 1 to 16 entries. It is open.
FieldWhat it holds
name, owner, versionwhat the app is called, who owns it, and its version (1 by default)
shapeweb, desktop, static, or a2ui
readsthe group/space pairs the app reads
actionsthe action names the app may request; agents' card actions answer them
viewsthe view names it asks of its feed
uifor an A2UI app: the protocol and version, the catalogs, the agent instance that draws it, the transport (views or a2a), and its page ids
hostwhere a host serves the app for people: url, hostAgent, path, signOn (idp or none), publishedBy, status
url, pkg, idpClientwhere it is reached, the package it came from, its identity-provider client

One AppCard points at others. ui.agent names the agent that draws its pages, actions names actions on agents' cards, ui.components copies the components agents declared with @UiComponent, and host.hostAgent names the peer that serves it.

Where you define it, in four ways:

  1. Ship it in your jar as META-INF/bma/app.json. The console reads it when it indexes the package and admits the card into the group when you deploy the package.
  2. Publish from your agent. An agent that draws A2UI writes Surface entries into its group's views space and then a Publish. The group's app host serves the pages, and the console gives the app its card from the Publish.
  3. Register it in the console: Apps › Register an app (id, name, group, kind, shape, owner, origin, formats, URL, reads, actions, views, and the drawing agent), or bma app put followed by bma app deploy.
  4. Publish it in code with the core's AppCardPublisher(identity, runtime, discovery).publish(card). It keeps the full card, issues it again when the group's view changes what the card may carry, and lets it lapse at its ttl after withdraw(id).

The expense desk example ships this card in its jar:

// META-INF/bma/app.json
{
  "id": "app-expense-desk",
  "name": "Expense desk",
  "kind": "peer",
  "shape": "a2ui",
  "owner": "bma-example-expenses",
  "reads": ["views"],
  "actions": [],
  "views": [],
  "ui": {
    "protocol": "a2ui",
    "version": "v0.9.1",
    "catalogIds": ["https://a2ui.org/catalogs/basic", "https://badmonkey.ai/a2ui/catalogs/agentspaces-viz"],
    "agent": "bma-example-expenses/desk",
    "transport": "views",
    "surfaces": ["desk"]
  },
  "ttl": "P1D"
}

Its agent draws the desk page and asks the group's app host to serve it, with the Surfaces helper of agentspaces-a2ui:

// ExpensesBootstrap.java
pen = new Surfaces(group.space("views"), APP, clock, LEASE);
// ...
pen.publish(List.of(SURFACE), TITLE, "", SignOn.wire(body.signOn()));

How the console shows it: the Apps screen opens with Published applications, one row per app a host serves, with its URL, group, host, sign-on, and sessions. An app's page shows its kind and shape, group, owner, URL, reads, actions, origin, formats, and the drawing agent, with Submit, Approve, and Admit into the group. "What this application may show" lists the catalogs and the components that agents declared on their cards.

aspace://guide/enterprise/frameworks

Agent frameworks

The core binder does the work in every framework: it reads the binding annotations on your bean and publishes one AgentCard per group. A framework adds its own way to write the agent and its own way to reach a model. The developer guide covers each one in depth.

Embabel

Embabel is a JVM agent framework with a goal-oriented (GOAP) planner. The extension embabel-agentspaces works in two directions. Outbound, the metadata of every Embabel @Agent bean becomes an AgentCard in every joined group. Inbound, the fleet's cards become a generated Embabel agent whose actions the planner can use.

DependencyVersion
ai.badmonkey.agentspaces:agentspaces-spring-boot-starter0.6.0
ai.badmonkey.agentspaces:embabel-agentspaces0.6.0
com.embabel.agent:embabel-agent-starter1.5.2

The extension reads Embabel reflectively. It builds with no Embabel artifact and switches on only when Embabel is on the application's classpath. It does not install an Embabel platform: automatic deployment of the fleet's actions needs the application's AgentPlatform bean.

The smallest Embabel agent that also takes work from a space adds @SpaceTake to the action:

// EmbabelBinderTest.java
@Agent(name = "spaceWorker", description = "Takes tasks from the work space")
public static class SpaceBoundEmbabelWorker {

    @Action
    @ai.badmonkey.agentspaces.agent.annotation.SpaceTake(space = "work")
    public FindingEntry research(TaskEntry task) {
        return new FindingEntry(task.topic(), "done");
    }
}

How its skills become a card:

  • The @Agent description becomes the card's description, and each @AchievesGoal becomes a goal.
  • Each @Action becomes a card action of kind embabel-action, with the action's description (cut at 512 characters) and its contract from @Action(pre, post, cost).
  • The action's domain parameter types become consumes, and its return type becomes produces. @SpaceTake or @SpaceNotify on the action adds the space binding.
  • The card carries costHints of framework=embabel, and the group's binder adopts it, so it is refreshed with every other card.
  • A bean that is both an Embabel agent and an @AgentSpec or @SpaceAgent gets one card, from the space binder.

The worker loop comes from @SpaceTake on the action. An @Action without it publishes a card and takes no work. The platform's claim summariser is an Embabel agent shipped as an ordinary package:

// ClaimSummariser.java
@Agent(name = "claim-summariser", description = "Summarises a claim's text into one line for the adjuster's queue")
public class ClaimSummariser {
    // ...
    @Action(description = "Summarises one claim")
    @AchievesGoal(description = "every claim in the queue has a one-line summary")
    public ClaimSummary summarise(ClaimText claim) {

The model: an Embabel action reaches its model through Embabel's own configuration. The integration test registers a Spring AI model as an Embabel LLM service and selects it with --embabel.models.default-llm=scripted, because Embabel's own default outranks a builder's default properties.

The planner side: with agentspaces.embabel.remote-actions-enabled (on by default), remote AgentCards become one generated agent with one action per consumed and produced pair, and Embabel's planner can reach a goal through them. Two limits apply. An action that takes OperationContext as a second argument cannot be a bound space method. Embabel's platform has no undeploy, so a vanished remote action stays until the platform restarts.

Spring AI

agentspaces-springai joins Spring AI to the fleet. The fulfiller above is a Spring AI agent: a @SpaceAgent bean with a ChatClient.

DependencyVersion
ai.badmonkey.agentspaces:agentspaces-springai0.6.0
ai.badmonkey.agentspaces:agentspaces-spring-boot-starter0.6.0
org.springframework.ai:spring-ai-starter-model-openai, for a real modelfrom the spring-ai-bom, 2.0.1 in the quick start

How its skills become a card: the library adds nothing between your bean and the core binder, so the card comes from @SpaceAgent and @SpaceTake as in the fulfiller. The library adds the other direction:

  • Fleet tools. Every action on the group's AgentCards becomes a Spring AI ToolCallback named from the agent and the input type (fleet_<agent>_<InputType>). A call writes a leased task into the space and waits for the result.
  • The take lease. The TakeLeaseAdvisor renews the take's lease on every model round trip, so a long model call does not lose its order while the instance lives.
  • The fleet as a model. With agentspaces.springai.model-client.enabled=true, the fleetChatModel bean writes each call as a ModelRequest into the model space, and a model server or the platform's gateway answers it.
Property under agentspaces.springai.model-clientDefaultMeaning
enabledfalseadds the fleetChatModel bean
spacemodel-requeststhe space requests go into
modelemptythe model name a request addresses; empty means the server's default
timeout120show long a call waits

On a node with no model provider, fleetChatModel is the application's ChatModel, so the auto-configured ChatClient calls the fleet. Beside a provider it is injected by name with @Qualifier("fleetChatModel").

LangChain4j

agentspaces-langchain4j runs on agentspaces-runtime, the plain Java host (FleetRuntime) that reads the same agentspaces: YAML as the Spring Boot starter.

DependencyVersion
ai.badmonkey.agentspaces:agentspaces-langchain4j0.6.0
dev.langchain4j:langchain4j-open-ai1.20.0
com.fasterxml.jackson.dataformat:jackson-dataformat-yamlthe runtime reads its configuration with it and does not bring it

The agent is an @AgentSpec class with a LangChain4j ChatModel. The application starts the runtime, builds the model with the fleet's listeners, and binds the agent:

// ShopApp.java
try (FleetRuntime runtime = FleetRuntime.start(PropertiesLoader.yaml(Path.of(args[0])))) {
    LangChain4jFleet fleet = LangChain4jFleet.builder(runtime).build();
    ChatModel model = OpenAiChatModel.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .modelName("gpt-4.1-mini")
            .listeners(fleet.listeners())      // renews the take lease on every model round trip
            .build();
    runtime.bind(new Fulfiller(model));
mvn -q compile exec:java -Dexec.mainClass=shop.ShopApp -Dexec.args="first.yaml"
mvn -q compile exec:java -Dexec.mainClass=shop.ShopApp -Dexec.args="second.yaml kite"
  • The card comes from runtime.bind, through the core binder.
  • fleet.tools() is a LangChain4j ToolProvider whose tools are the catalogue's current actions, named fleet_<agent>_<InputType>, with a JSON Schema from the input record.
  • ModelClient.of("<model>") makes fleet.chatModel() route calls through the space, and fleet.modelServer(...) serves this peer's models. It speaks the same model records as Spring AI.
  • A FleetRuntime host does not serve the core's fleet console. That console is a Spring Boot starter feature.

Micronaut

agentspaces-micronaut enrolls agent beans at compile time with an annotation processor, so a bean needs only a method annotation to join the fleet.

DependencyVersion
ai.badmonkey.agentspaces:agentspaces-micronaut0.6.0
ai.badmonkey.agentspaces:agentspaces-micronaut-processor, on the compiler's annotation processor path0.6.0
parent ai.badmonkey.agentspaces:agentspaces-micronaut-parent, as the quick start uses0.6.0
// Fulfiller.java
@Singleton
public class Fulfiller {

    @SpaceTake(lease = "30s")
    public Shipment ship(Order order) {
        return new Shipment(order.orderId(), order.item(), "fulfiller");
    }
}
# application.yml
agentspaces:
  bind: 127.0.0.1:${shop.port:7701}
  groups:
    - name: shop
      founding: shop-v1
      seeds: ${shop.seeds:}      # empty on the first instance
      spaces:
        - name: orders
mvn -q compile exec:java -Dexec.mainClass=shop.ShopApp
mvn -q compile exec:java -Dexec.mainClass=shop.ShopApp -Dexec.args="--shop.port=7702 --shop.seeds=127.0.0.1:7701 --shop.order=kite"
  • This bean has no @AgentSpec, so the card's agent name defaults to the decapitalized class name. Micronaut's @SpaceAgent is a singleton stereotype that is also an @AgentSpec, for a named card.
  • Keep AOP interceptor bindings (@Retryable, @Cacheable, @Transactional, a custom @Around) off the agent bean. The application fails at startup and says so.
  • agentspaces.micronaut.service-asset.enabled=true publishes the embedded HTTP server as an AssetCard.
  • For a model, agentspaces-micronaut-langchain4j adds a model server on the worker that holds the key and a model client on an orchestrator that holds none. It shares the model records with Spring AI, so a Spring Boot model server answers the same requests.
aspace://guide/enterprise/console

From your agent to the console

There are two ways to bring an agent under the console. Attach when the agent already runs and you keep running it: the console's bridge joins your group and reports what it sees. Deploy when the console should start the process, count its replicas, scale it, and retire it.

ATTACH: THE CONSOLE WATCHES YOUR GROUPDEPLOY: THE CONSOLE RUNS YOUR AGENTThe console (bma up)API and UI on :7580, its own peer on :7700profile mtls, its own group console-locala Watch: tls://127.0.0.1:7711,founding shop-v1, lane ordersreports:roster, lanesA bridgea console peer that joins shop as a memberand reads its cards, members, and lanesGroup shop, as you run itfulfiller on :7711 and :7712founding shop-v1, profile mtlsnothing in your agent changesYour agent keeps running on its own.The console shows it as an existing agent,and you may reference it as a deployment.Your packagethe jar and a signed bma.package.yamlpushed to a registry (or in a bundle)bma catalogue ingestbma deploy --group shopThe catalogue and the deployerthe console checks the signature,then launches java -jar on a targetBMA_GROUP, the seeds,a free bind, the profileGroup shop, founded by the consoleyour agent and the bridgefounding shop-v1, seed: the consolemembership openThe console starts, counts, scales,drains, and retires your agent, and showsits logs beside the deployment row.
Two ways to the console. Attach when the agent already runs and you keep running it. Deploy when the console should start and look after the process.

Before you start

Four facts decide whether the console can see a tutorial agent. Check them first.

  • Ports. The console's own peer binds 127.0.0.1:7700 and its WebSocket listener 127.0.0.1:7701; it also takes 7580 (the API and UI), 7590 (the core's fleet console), and 7788 (its beacon). The Spring AI quick start binds 7701 and 7702, and the Node seed of the Python, TypeScript, and Ruby quick starts binds 7700. Run your agent on other ports, such as 7711 and 7712.
  • The security profile. The console started with bma up runs under the starter's default, mtls, as do the Spring AI, LangChain4j, Micronaut, and Groovy quick starts. The Python, TypeScript, Ruby, Clojure, and Jungle Gym peers run under dev-local. The console and your group must use the same profile.
  • Seeds under TLS. The bridge dials a bare seed such as 127.0.0.1:7711 over plain TCP. Under mtls, give the seed its scheme: tls://127.0.0.1:7711.
  • Founding text. Tutorial groups are founded from text (founding: shop-v1). Such a group holds no signed founding, so the console joins it by its seeds and the same founding text, never by its group id.

To run the console under dev-local for a dev-local group, put agentspaces.security.profile: dev-local in ~/.bma/bma.yaml, the operator's own configuration file, which the console imports at start. The same file moves the console's ports: agentspaces.bind, agentspaces.transport.ws.bind, agentspaces.console.port, and bma.console.beacon-bind.

Start the console and sign in

The console comes as two jars: the console itself (bma-console-all-in-one) and the bma command line (bma-console-cli). From a build of the platform:

alias bma='java -jar bma-console-cli/target/bma-console-cli-0.1.0.jar'
export BMA_CONSOLE_JAR=$PWD/bma-console-all-in-one/target/bma-console-all-in-one-0.1.0.jar
bma up                                   # the API and UI on http://127.0.0.1:7580, its peer on 7700
bma login --user admin --password "$(cut -d: -f2- ~/.bma/admin-password.txt)"
bma status                               # the console's group, its spaces, and its bridges
  • bma up starts the console detached under ~/.bma and prints the API's URL, the fleet console's URL on the port the console reads, and its log. bma down stops it, and the agent processes it launched keep running.
  • bma up --port <port> moves the API and UI; point the other commands at it with BMA_CONSOLE_URL=http://127.0.0.1:<port>. BMA_HOME moves the home from ~/.bma.
  • Sign-in is on by default (bma.identity.mode=local). The first start writes the admin account's password to ~/.bma/admin-password.txt. bma login stores a token for the other commands, and BMA_TOKEN overrides it.
  • For the API, POST /platform/v1/session with {"name","password"} returns {"token": ...}. Send it as Authorization: Bearer <token>; the examples below keep it in $T.
  • The UI is at http://127.0.0.1:7580/ui/. It has two halves: Console (the console's own group and its bridges) and Managed fleet (the groups the console holds and what runs in them).
  • With several tenants, move the session to the right fleet first: bma tenant use --id <tenant>.

To see a managed agent before you bring your own, apply the greeter example from Getting started (one click), with bma example up greeter, or with POST /platform/v1/examples/greeter/apply. It founds its own group, greeter, and deploys the greeter agent with an app host and an app feed beside it.

The example needs the platform's packages in the catalogue: a console installed from a bundle (bma bundle build, then bma bundle install) has them, while one started with bma up from a build starts with an empty catalogue, and GET /platform/v1/examples/greeter lists the packages it misses. bma examples lists every example and where each stands.

Way 1: attach the console to your group

Use this way for an agent you run yourself, such as the Spring AI fulfiller. Nothing in the agent changes.

  1. Run the fulfiller on free ports. Start the first instance on 7711 and leave it running.
java -jar target/shop-springai-1.0.0.jar --shop.port=7711
  1. Start the console and sign in, as in the section above. Both sides now run under mtls.
  1. Preview the group. The console's bridge joins for a moment, reads the members, cards, spaces, and admission, and leaves.
bma group preview --locator method=seeds,seeds=tls://127.0.0.1:7711,founding=shop-v1
  1. Watch it. A Watch is a work order a bridge takes. The bridge joins shop through the seed and the founding text and holds it. Name the spaces whose traffic you want on the request timeline.
bma watch add --group shop --method seeds --founding shop-v1 --seeds tls://127.0.0.1:7711 --spaces orders
  1. Or watch it from the UI or the API. In the UI, open Managed fleet › Groups, press Watch a group, choose How: seeds, and fill in the seeds, the founding string, and the lanes to watch. The wizard previews before it writes. Through the API, the same Watch is one request:
curl -X POST http://127.0.0.1:7580/platform/v1/watches \
  -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"group":"shop","locator":{"method":"seeds","founding":"shop-v1","seeds":"tls://127.0.0.1:7711","spaces":"orders","archive":"true"},
       "grants":["DIRECTIVE_ISSUER:fleet-control","SPACE_WRITE:c2-audit"]}'
  1. Check that a bridge holds it. bma status lists the bridges and the group each one holds ("holds" : "shop"), and GET /platform/v1/bridges answers the same. One bridge holds one group, and the console starts another bridge when a Watch waits, up to 16.
  1. Open the group. In Managed fleet › Groups, shop shows its admission (open), bridge, members, and agents. Its Agents tab has one row per running instance, each named by the instance's card id (it ends in /fulfiller), with the kind existing and the state OBSERVED: an agent that was already in the group. bma existing-agents lists the same rows. An instance you stopped keeps its row until its card's 15-minute ttl runs out.
  1. Send work and follow it. Start the second instance with an order. The request timeline (Observe › Request timeline, or bma timeline --key o-1) joins everything one key touched: the Order entry, the claim, the completion, and the Shipment. It keys on fields such as orderId, and the quick start's order is always o-1.
java -jar target/shop-springai-1.0.0.jar --shop.port=7712 --shop.seeds=127.0.0.1:7711 --shop.order=kite
  1. Optionally, track it as a deployment. Reference it by name, and the console expects an agent called fulfiller in the group. Use the API below, or the Deployments screen (/ui/#/agents/deployments, where the deploy and reference wizards land) and its Reference a running agent button. The row reads EXPECTED, then LIVE once the reconciler's next sweep (every 60 seconds) finds the card, then DEGRADED once no card of that name has been seen for gone-after (10 minutes by default).
curl -X POST http://127.0.0.1:7580/platform/v1/deployments/expected \
  -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"deployment":"ref-fulfiller","group":"shop","agentName":"fulfiller"}'

A deployment id names one row. The wizard proposes dep-<agent name>, so name a reference ref-fulfiller and keep dep-fulfiller for the package you may deploy later. The console refuses a deploy under an id that a reference holds (HTTP 409, "the deployment id ... names a reference to the running agent"), since no row would own the process.

To stop tracking the agent, retire its reference with bma retire --id ref-fulfiller or the row's retire button. The row turns RETIRED at once, and the agent keeps running, since the console never ran it. The agent shows again under Existing agents (/ui/#/agents/existing), where you can reference it again. A scale or a drain of a reference answers HTTP 409, since the console runs no replica for it.

  1. Give the group a name, if you like: bma profile put --group shop --name "Shop" shows "Shop" in place of the id.

The console also raises two quiet findings for the tutorial agent: it produces data without a data-use declaration, and its types travel without a schema fragment. Neither stops anything. The platform's @DataUse annotation answers the first.

Watches survive a console restart, and DELETE /platform/v1/watches/shop ends one. Your agent never depends on the console: stop the console and the fulfiller keeps running.

Or let the console found the group

A second attach shape suits a new group: the console founds it, and you point your agent at the console.

  1. Found the group as open. In the UI, Watch a group with How: found it here founds an open group by default. Through the API, always send "membership":"open": a group founded without it is an invite group, which admits no agent that lacks a credential.
curl -X POST http://127.0.0.1:7580/platform/v1/groups \
  -H "Authorization: Bearer $T" -H 'Content-Type: application/json' -d '{"name":"shop","membership":"open"}'

To follow a lane on the request timeline, found it with the locator form instead and name the lane in spaces:

curl -X POST http://127.0.0.1:7580/platform/v1/groups \
  -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"name":"shop","locator":{"method":"found","membership":"open","founding":"shop-v1","spaces":"orders"},
       "grants":["SPACE_WRITE:c2-audit","SPACE_WRITE:policy"]}'
  1. Run your agent against the console's seed. The group's founding text is shop-v1, the <group>-v1 the console gives every group it founds, so the quick start's own configuration already names it, and the seed is the console's own peer. The Spring AI starter gives a bare seed the profile's scheme, so the plain address works here.
java -jar target/shop-springai-1.0.0.jar --shop.port=7711 --shop.seeds=127.0.0.1:7700
  1. Reference it as in step 9 above, so the console counts it.
Note. Here the console's peer is your agent's only seed. A running instance dials it again after a console restart, but a new instance cannot join while the console is down. List one of your own instances as a second seed, such as --shop.seeds=127.0.0.1:7700,127.0.0.1:7711, when the agent must start without the console.

Way 2: deploy your agent as a package

Use this way when the console should run the process. A package is your jar plus a signed manifest, pushed to a registry. The console's catalogue ingests it, and its deployer launches it into a group.

The steps below turn the Spring AI fulfiller into a package. The changed project is the guide's sample shop-fulfiller-package: the quick start plus one dependency, one bean, a manifest, and a signer. Everything else is the quick start.

  1. Read the group settings from the environment. The deployer sets the join for you, but your application.yml keeps its own group entry, so the entry must read the values the deployer renders. Keep the quick start's values as the defaults, so the same jar still runs by hand:
# application.yml
agentspaces:
  bind: ${AGENTSPACES_BIND:127.0.0.1:${shop.port:7701}}
  security:
    profile: ${AGENTSPACES_SECURITY_PROFILE:mtls}
  groups:
    - name: ${BMA_GROUP:shop}
      founding: ${AGENTSPACES_FOUNDING:shop-v1}
      seeds: ${AGENTSPACES_SEEDS:${shop.seeds:}}
      spaces:
        - name: orders

The platform's greeter (bma-example-greeter) reads the join, membership, and credential placeholders as well, for groups that need them.

  1. Keep the JVM alive. A package with no web server needs spring.main.keep-alive: true. The fulfiller's configuration already has it.
  1. Publish the deployment labels. The deployer puts BMA_DEPLOYMENT, BMA_REPLICA, and BMA_TARGET in the process environment. Your agent must put them on its peer as hints. Without them the console counts no replica: after stale-after (two minutes) the deployment reads "0 of 1 replicas mirrored in shop" and goes DEGRADED. The platform's DeploymentHints does it in one runner bean. Add ai.badmonkey.platform:bma-console-common:0.1.0 to the project, then:
// ShopApp.java
@Bean
ApplicationRunner deploymentHints(AgentSpaces spaces, PeerNode node, @Value("${BMA_GROUP:shop}") String group) {
    return args -> {
        Map<String, String> hints = DeploymentHints.ofThisProcess(System.getenv());
        if (!hints.isEmpty()) {
            DeploymentHints.apply(node, spaces.group(group).id(), hints);
        }
    };
}

Run by hand, the environment has no labels and the bean does nothing.

  1. Write the manifest, bma.package.yaml. The required fields are schemaVersion: 1, name (lower-case letters, digits, and dashes), a semver version, kind: agent, publisher, runtime: spring-boot, and artifacts.jar as sha256:<64 hex> of the jar. Add cards, grants, dependencies, and configuration.env (the names of the secrets the package expects, never their values) as the AgentCard section shows. Without side, the package runs in managed groups only.
# bma.package.yaml
schemaVersion: 1
name: shop-fulfiller
version: 1.0.0
kind: agent
publisher: Acme
description: Ships orders and writes a packing note
runtime: spring-boot
artifacts:
  jar: sha256:0000000000000000000000000000000000000000000000000000000000000000
cards:
  - agent: fulfiller
    actions:
      - name: ship
        consumes: [shop.Order]
        produces: [shop.Shipment]
        kind: take
        space: orders

From this card the catalogue proposes the grants SPACE_TAKE:orders and SPACE_WRITE:orders.

  1. Sign it. The platform's PackageSigner (in bma-package, which bma-console-common brings) signs the canonical JSON of every field but signature with your Ed25519 key. The sample's SignPackage fills in the jar's digest, signs, and prints the multibase publisher key a console trusts:
// SignPackage.java
KeyPair publisher = Ed25519.fromSeed(Files.readAllBytes(seed));
String digest = CanonicalJson.digestOf(Files.readAllBytes(jar));
String yaml = Files.readString(draft).replaceFirst("jar: sha256:[0-9a-f]{64}", "jar: " + digest);
PackageManifest signed = PackageSigner.sign(PackageManifests.parse(yaml), publisher);
Files.writeString(out, PackageManifests.toYaml(signed));
mvn -q package
java -Dloader.main=shop.SignPackage -cp target/shop-fulfiller-1.0.0.jar \
  org.springframework.boot.loader.launch.PropertiesLauncher \
  bma.package.yaml target/shop-fulfiller-1.0.0.jar publisher.seed target/bma.package.yaml

The first run writes the publisher's seed to publisher.seed (mode 0600). Keep it out of version control and in your secret store: whoever holds it can publish as you.

  1. Push it with oras, the jar as the layer and the signed manifest as the config:
oras push <registry>/acme/shop-fulfiller:1.0.0 \
  --artifact-type application/vnd.badmonkey.package.v1 \
  --config target/bma.package.yaml:application/vnd.badmonkey.package.config.v1+yaml \
  target/shop-fulfiller-1.0.0.jar:application/vnd.badmonkey.package.jar
  1. Trust the publisher and ingest. Put the key that SignPackage printed into ~/.bma/bma.yaml and restart the console (bma down, then bma up). The catalogue refuses a package that any other key signed. A registry on plain HTTP, such as one on the loopback, goes under bma.catalogue.plain-http-registries:
# bma.yaml
bma:
  catalogue:
    trusted-publishers:
      zYourPublisherKey: Acme              # the key SignPackage printed
    plain-http-registries: ["127.0.0.1"]   # a registry on the loopback, over plain HTTP

Then ingest it and check what it proposes. bma catalogue list shows the package as SIGNED yes:

bma catalogue ingest --reference <registry>/acme/shop-fulfiller:1.0.0
bma catalogue list
bma catalogue grants --package shop-fulfiller@1.0.0
  1. Found or watch the group first. bma deploy does not found a group, and an agent deployed into a group nobody watches gets no seeds and founds a partition of its own. Found shop as shown above, watch the group you already run as in Way 1, or deploy from the UI, whose wizard founds a new group (open) for you. Into a group the console founded, the replica's seed is the console's peer; into a watched group, it is the Watch's seeds.
  1. Deploy. The target boot-host-1 is the process target on the console's own host.
bma deploy --package shop-fulfiller@1.0.0 --group shop --target boot-host-1 --replicas 1 --id dep-fulfiller

bma deployments shows the row LIVE once the replica's hints arrive, usually within seconds. In the UI, Catalogue › Deploy or Deploy an agent on the Deployments screen asks for the package, the group, the target, and then the replicas, the id, plain environment values, and secret references. bma deploy takes secret references (--env-ref NAME=vault://kv/key) and no plain values, so use the wizard or POST /platform/v1/deployments for those.

  1. Watch it come up. bma deployments shows each row as DESIRED, ROLLING, LIVE, DEGRADED, DRAINING, or RETIRED, and a reference as EXPECTED until its card arrives. GET /platform/v1/commands?outcome=failed lists what failed and why, and the Deployments screen's logs button shows the replica's last lines (also under ~/.bma/deployments/<id>/<replica>/stdout.log).
  1. Run it. bma scale --id dep-fulfiller --replicas 2 starts replica 1 beside replica 0, bma drain --id dep-fulfiller moves the row to DRAINING, and bma retire --id dep-fulfiller stops every replica and marks the row RETIRED.

The deployer sets these for every replica, so your agent needs no join settings of its own:

  • BMA_GROUP, the group it was deployed into;
  • AGENTSPACES_FOUNDING and AGENTSPACES_SEEDS from the group's Watch, with tls:// added to each seed under a TLS profile;
  • AGENTSPACES_SECURITY_PROFILE, the console's own profile;
  • BMA_DEPLOYMENT, BMA_REPLICA, and BMA_TARGET, the labels of step 3, and BMA_CONFIG, the path of the rendered file;
  • a free AGENTSPACES_BIND on the process target;
  • AGENTSPACES_RULES_GATE=true and AGENTSPACES_FLOWS_RECONCILE=true, so the published rules judge its claims and results;
  • a workload identity under the mtls-oidc and zero-trust profiles.
Note. On a host with no registry, bma bundle build --packages <names> finds each jar through BMA_<NAME>_JAR, writes it as the package <name>@0.1.0 signed by the bundle's own key, and bma bundle install sets up a console that trusts that key.

An Embabel agent deploys the same way: the claim summariser is an ordinary package whose application.yaml reads the same environment placeholders.

What the console shows for your agent

Whichever way it arrived, your agent appears in the same places:

  • Groups: one row per group with its layer, admission, bridge, members, agents, deployments, attention, and spend today.
  • The group page: the tabs Canvas, Agents, Peers, Spaces, Stores, and Configurations. The canvas draws the peers, the agents, the cards they publish, and the spaces.
  • The agent page: the card, the deployment, the configuration in force, its UI, its hints, its data use, and its findings.
  • Deployments (/ui/#/agents/deployments, where the deploy and reference wizards land): the rows you deployed or referenced, with their state, the buttons Scale, Pause, Resume, Drain, Retire, and logs, and the deployment targets.
  • Findings and Observe: the request timeline, incidents, alerts, and the audit of every command.

Limits to know

  • Python, TypeScript, and Ruby agents attach. The process target launches JVM jars, so these agents join the console by Way 1.
  • Pause and Resume need a gate. The buttons write a directive into the group's fleet-control space. A worker obeys it only when its code attaches a DirectiveGate (the starter's DirectiveGates bean) to that space and reads paused() and draining(). The fulfiller does neither, so do not rely on these buttons for it.
  • Configurations are for the platform's own agents. The console publishes configuration bodies only for the agent kinds it ships, and it refuses any other kind.
  • **A FleetRuntime host serves no fleet console of its own.** The core's served fleet console (agentspaces.console.enabled, port 7590) is a Spring Boot starter feature. The Bad Monkey console reads any host's cards through its bridge.
aspace://guide/enterprise/practices

Best practices

These practices come from how the console enforces its boundaries. Each one says what to do and where the console helps.

Tenancy and fleet managers

  • Give each organisation a tenant: bma tenant add --id acme --name "Acme fleet". Each tenant gets its own console group, keys, identity realm, and rows that no other tenant reads.
  • Assign fleet managers with the scopes they need: bma tenant managers add --id acme --principal ops --scopes aspace:console:view,aspace:console:operate.
  • The console takes the tenant from the signed-in principal, never from a parameter. Run bma tenant use --id acme (or bma fleet use) before you watch or deploy.
  • A package never sees a tenant. It joins the group it is deployed to and works there.
  • The console refuses a suspended tenant's fleet managers at once, mid-session too, with 403.

Sign-on

  • Local accounts suit a laptop. Elsewhere, use Keycloak (bma idp up, then bma login, or bma login --service-account <client> for pipelines) or an organisation's provider brokered into the realm. Production mode refuses to start without OIDC.
  • For the people who use your apps, bind an identity provider to the tenant, or turn on the console's own issuer with bma.identity.issuer.enabled=true.
  • On the wire an app's sign-on is idp (the host's door asks the identity provider) or none (open). The console's screens call idp by the word tenant.
  • An app that asks for sign-on never opens without it. While no identity provider is online, it answers 503 with Retry-After; the appendix explains why.

Secrets in the vault

  • Keep every secret in the vault: bma vault put --key <key> --value <value> returns vault://kv/<key>, which goes into a deployment's envRefs (bma deploy --env-ref NAME=vault://kv/<key>).
  • A package names the environment variables it needs (configuration.env), never their values.
  • The console checks for a secret in the clear at four doors: it refuses a configuration body that holds one, raises a credential-in-clear finding on a body already in a group's policy, refuses to export the family, and refuses the bundle's file.
  • Join credentials are sealed into the vault, and a Watch keeps only their reference.
  • For a threat model: a replica's spec.json under the deployer's home holds its resolved environment, with mode 0600.

Models through the gateway

  • Bind a model provider once with the credentials file. The console keeps the key in its vault, and the gateway reaches it by reference, so it never lands in the database, an export, a bundle, a log, or an API response.
  • Bind the provider to a group (Models › Providers, or POST /platform/v1/models/providers/bind?group=) and deploy bma-model-gateway into the group.
  • Agents ask the gateway through the group's model-requests space. The gateway takes a ModelRequest tagged task=<kind>, or one whose model is the gateway's model name (gateway by default). For a Spring AI agent, that means agentspaces.springai.model-client.enabled=true, model-client.model set to the gateway's model name, and a model-requests space in the group.
  • Routing (task rules, residency, a price cap), guardrails, and budgets are each one policy per group. Publish them from their screens or with bma routing put, bma guardrail put, and bma budget put.
  • Run tests and laptops on the mock provider (bma.models.mock=true), which spends no tokens.

Rules and guardrails

  • A rule book is sentences in four forms: name a situation, when something happens then, make sure an outcome happens within a time, and a constraint. The console refuses a sentence that names a type the fleet does not move, and names the type.
  • A deployed JVM package gets agentspaces.rules.gate=true from the deployer, so the published rules judge its claims and results. An agent you attach is judged only if you set that property yourself.
  • Guardrail checks run at the gateway (prompts and completions) and at the door (entries written into the spaces the guardrail's configuration names), with refuse, redact, quarantine, or finding as the action.
  • Turn on approvals with the governance wizard where a person must sign off on rule books, models, flows, or configurations.

Production fleets

  • Use invite membership and mtls, or mtls-oidc or zero-trust with workload identities.
  • Narrow agentspaces.security.grants.directive-issuer on worker nodes to the console's peer id, which GET /platform/v1/console-group returns as peer.
  • Deploy signed packages only, and keep the sides apart: console-side packages run in the console's group, and fleet packages in managed groups.
  • Move a busy site's console to PostgreSQL (bma.persistence.kind=postgres). No message broker is needed.
  • The served fleet console on port 7590 answers any process on the host. Keep the host's users to the console's operators.

What to watch

  • The Console page: whether the console works (its group, its database, the reconciler's last sweep, the bridges against the Watches, the identity mode). At the bridge ceiling the bridges check goes red and names the setting to raise.
  • Groups: a group with no bridge or marked stale.
  • The group's Agents tab and Deployments: replicas reported against replicas desired.
  • Findings: stale, degraded, drift, undeclared, and the findings each group's bridge reports. The console is quiet by default: Needs attention counts serious and critical findings and the approvals asked for.
  • Observe: the request timeline, incidents, alerts, and the audit.
  • After a fleet restart: GET /platform/v1/commands?outcome=failed lists what failed. The re-carry sweep writes again, every minute, the rule books, flows, admitted model cards, policies, and configurations a restarted group lost; POST /platform/v1/recarry runs one pass now.
aspace://guide/enterprise/appendix

Appendix: how it works and why

This appendix explains the mechanisms behind the main text: how cards are named and signed, why they are leased, how large cards travel, and why the console behaves as it does at the edges.

Card ids and the wire

Each card's id follows a convention its issuer applies:

CardId
AgentCardaspace://<group>/agent/<peer>/<agent>
AssetCardaspace://<group>/asset/<asset>; a content store adds its name and issuer
ModelCardaspace://<group>/model/<name>@<version>; a model server's own card appends its peer id
AppCardaspace://<group>/app/<issuer peer>/<app id> when the console admits it

The binder builds the AgentCard this way:

// AgentBinder.java
AgentCard card = new AgentCard(
        "aspace://" + group.value() + "/agent/" + identity.peerId().value()
                + "/" + agentId.localName(),
        identity.peerId(), group, issuedAt, Duration.ofMinutes(15),
        agentId,
        spec == null ? "" : spec.description(),
        spec == null ? List.of() : spec.goals(),
        List.copyOf(consumes), List.copyOf(produces), Map.of(),
        Map.copyOf(spaceBindings),

A card's fields travel in record order. Fields added in later protocol versions (the agent key and certificate, actions, ui, spill on the AgentCard; host, origin, formats, spill on the AppCard) are appended and left off the wire when absent, so a card without them encodes exactly as it did before they existed. A reader that meets a value it does not know in a closed field, such as an AppCard kind, treats the whole card as undecodable and drops it. It never substitutes a default.

Signing and the ad cache

  • Every publisher signs its card with the peer's identity. The binder signs the card the spiller prepared, so the signature covers whatever travels, stub or full card.
  • An agent with a key of its own (a subordinate identity, as the Python and TypeScript quick starts use) adds its public key and a certificate that certifies exactly that agent and key, so a reader can require attested agents.
  • discovery.publish admits the signed card to the local cache and gossips it. A card the peer's own cache refuses is never gossiped.
  • Every cache is bounded by count and by bytes: 8,192 cards and 32 MiB by default, four times that on a rendezvous peer. The cache refuses a card that would pass a bound and counts it in adsRefusedCacheFull; anti-entropy offers the card again once room returns, and the cache strikes nobody for it. The Spring Boot keys are agentspaces.discovery.cache.max-entries and max-bytes.

TTL and refresh

Short leases are the fleet's liveness check. A fresh card answers "does this peer still offer this?" with no failure-detection round trips.

CardttlRefreshed by
AgentCard15 minutesevery JVM host, every agentspaces.card-refresh-millis (300000, five minutes)
AssetCard15 minutes from the stock providersyour code calling ConnectorRuntime.refreshCards()
ModelCardthe console's record (P1D by default, at most 30 days); 15 minutes from a model serverits issuer, by publishing it again
AppCardthe record's, P1D in a shipped app.jsonits issuer, by publishing it again

When you unbind an agent, the binder stops refreshing its card, and the card lapses by its TTL. A card that stops refreshing also leaves the planners, because remote actions come from live cards.

The card spill

No card kind has a size cap. Instead:

  • A card whose signed encoding is more than 65,536 bytes travels as a stub. Its large parts (actions and ui on an AgentCard; reads, actions, views, and ui on an AppCard) move into a document on the content swarm, cut into 65,536-byte pieces, and the stub's spill names the document's root, size, and parts.
  • The publisher logs a warning once per card id and size when the encoding passes 57,344 bytes (56 KiB), so you see a card approach the threshold.
  • The publisher spills only while every member of the view reads stubs and a content swarm serves the group. Otherwise it sends the full card and counts it in cardsOversizeInline.
  • find and remoteFind return stubs. A caller that needs ui, actions, reads, or views calls discovery.resolve(card), which fetches the document, checks it, and returns the full card. A reader does not fetch a document larger than 16,777,216 bytes by default.
  • ModelCards and AssetCards never spill, and neither do origin and formats.
// CardSpill.java
public static final int SPILL_THRESHOLD_BYTES = 65_536;
public static final int WARN_THRESHOLD_BYTES = 57_344;
public static final int PIECE_SIZE = 65_536;
public static final long DEFAULT_MAX_FETCH_BYTES = 16_777_216L;

The AppCard level

The AppCard's newer fields (origin, formats, a host that asks for sign-on, and spill) travel only while every member of the view advertises that it reads them. While an older reader is in the view, the publisher strips those fields and counts the card in appCardsDowngraded, so the older reader still decodes the card. The console's Apps screen shows both counts per group, Downgraded and Oversize inline, so you can see a group that still holds an older peer.

Sign-on and the 503 rule

An app host and its feed run one door: the authorization code flow with PKCE against the tenant's identity provider. An app whose sign-on is idp makes the feed refuse every view, page, entry, and file of that app without a live session.

A group can have no identity provider online: none bound yet, a restart before the host learns the binding, or a binding withdrawn. Then such an app answers 503 Service Unavailable with Retry-After and an offline page. It never falls back to serving openly, so an app that asked for sign-on stays closed until the door can check who is asking.

The card still advertises signOn: idp meanwhile, and the Apps row shows an amber pill until a provider comes online. Only none opens an app, and any other value keeps the door shut.

Seeds, profiles, and founding text

  • A group founded from text derives its id from the text alone. Every peer given the same text is in the same group, and nobody holds a signed founding document. A peer that asks to join by group id waits for a member to serve a verified founding advertisement, and against a text-founded group none can. That is why the console joins tutorial groups by seeds and the founding text.
  • The Spring Boot starter dials a bare seed with the profile's own scheme. The console's bridge reads a bare seed as tcp, and under a TLS profile a plain TCP link never registers with an attested node. So a Watch of an mtls group names tls:// seeds, and the deployer adds tls:// itself when it renders seeds for a deployment.
  • dev-local signs every frame over plain TCP on the loopback. It suits one laptop and nothing more.

How the deployer renders a deployment

The process target launches java -jar <jar>. A Spring Boot package also gets --spring.config.additional-location with a small rendered file that names the deployment; Micronaut reads it through MICRONAUT_CONFIG_FILES, and a plain Java main through BMA_CONFIG. The rendered file carries only the deployment, because a list in a higher-precedence file would replace the package's group entry instead of merging with it. The join therefore travels as environment variables, which is why a package's application.yml reads them as placeholders.

The deployment labels come back as peer hints (bma.deployment, bma.replica, bma.target, bma.pid, bma.host). The reconciler counts replicas from them, and a restarted deployer adopts the processes it finds by them.