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.
bma command line, web UI, and API on port 7580two ways in: attach or deployAn 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 anOrder, 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.
ModelRequest.| Card | What it says | Who issues it | Where you define it |
|---|---|---|---|
AgentCard | an agent: what it pursues, the entry types it consumes and produces, its actions, what it can show | the binder on the agent's own peer | annotations on your agent class: @AgentSpec, @SpaceAgent, or Embabel's @Agent |
AssetCard | a data asset: its source URI, its shape, how fresh it is, how to query it | the connector peer that holds the asset | an AssetProvider that a ConnectorRuntime runs |
ModelCard | a model the group may route to: its tasks, engine, licence, residency, and servers | the console when it admits the model, and a model server for itself | the console's Model Market, the bma model commands, or the model credentials file |
AppCard | an application people use: how it connects, what it reads, the actions it may request, its UI | the console when it admits the app | META-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
issuedandttl. The issuer publishes it again with a newissuedbefore thettlruns 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;remoteFindasks 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.
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 oneOrderunder a two-minute lease, callsship, writes the returnedShipment, 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
spacemeans the sole space. ChatClientis Spring AI's. The quick start runs it over a stubChatModel, 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
@SpaceAgentor@AgentSpec; consumeswithshop.Order#v1andproduceswithshop.Shipment#v1, the wire names of the two Java records;- one action per bound method, here
ship, with the space it takes from; - a
ttlof 15 minutes. Every JVM host (Spring Boot, Micronaut, andFleetRuntime) publishes the card again everyagentspaces.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.
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.
| Field | What it holds |
|---|---|
id, issuer, group, issued, ttl | the envelope every card has; the ttl is 15 minutes |
agent | the agent's id; its local name comes from name on @AgentSpec or @SpaceAgent |
description, goals | free text for people, planners, and semantic discovery |
consumes, produces | the entry schema names, such as shop.Order#v1 |
costHints | a free map; Embabel cards carry framework=embabel |
spaceBindings | each consumed schema mapped to the space the agent takes it from |
actions | one CardAction per bound method: name, description, consumes, produces, space, kind, and an optional contract (pre, post, cost); at most 64 |
ui | the A2UI components the agent can show, from @UiComponent |
agentPublicKey, agentCertificate | present 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@SpaceAgentwith 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. Itsdescriptionattribute becomes the action's description, andpre,post, andcostbecome its contract. @UiComponenton the class fillsui, so a console can assemble an application from a group's cards.- Embabel's
@Agent,@Action, and@AchievesGoalproduce the card through the Embabel extension, described below. - In the other languages, the
agentdecorator, theagentclass macro, ordefagentnames the agent as@AgentSpecdoes.
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(kindnotify) andgreet(kindtake), each with its own description. @UiComponentsays the agent can serve theChatInputcomponent of the openagentspaces-widgetscatalog, souilists one component.@DataUseis 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.
| Field | What it holds |
|---|---|
asset | the asset's name, unique within the issuing peer |
uri | the source system's URI, such as postgres://ops/public.orders |
description | what the asset holds, for people and semantic discovery |
shape | an entry schema name, a table structure, an index mapping, or a message format |
freshness | the update cadence, such as PT5M or daily |
costHints | size and cost hints, such as rows |
access | how 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. CallrefreshCards()on the same cadence as your other leased state, because the Spring Boot starter does not wire anAssetProviderbean into aConnectorRuntimefor you.- Other providers ship ready: Spring AI's vector-store provider publishes a dataset, and Micronaut's
agentspaces.micronaut.service-asset.enabledpublishes the service itself as an AssetCard. - A content store advertises itself with an AssetCard too, with
assetset tocontent-store:<name>and its capacity and policy inaccess.
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.
| Field | What it holds |
|---|---|
name, version | the name a ModelRequest addresses, and its version |
tasks | from chat, embed, rerank, classify, transcribe, vision |
modality, limits | such as text, and context and output limits |
licence, provenance | the licence, and upstream, weightRoot, weightHash, admittedBy |
evals, costHints | evaluation results (at most 64), and hints such as pricePerThousandTokens |
residency | sites, classifications, and releasable |
engine | provider, ollama, vllm, or onnx (later values are reserved) |
servers | the 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.ednnames a provider (:provider,:api-key, and optionally:models,:base-url). The console reads the file thatbma.models.auth-filenames, elsemodel-auth.ednin 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=truebinds a provider namedmockwith the modelsmock-chatandmock-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--groupare required. The version defaults to1, the engine toprovider, and the tasks tochat, 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:
kindsays 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), orassembled(a static app its publisher assembled from extracted data, which reads nothing live).originnames the external system the app came from, such asconsolefor an app the console drafted. It is open.formatslists the media types or vocabulary IRIs the app reads or renders, from 1 to 16 entries. It is open.
| Field | What it holds |
|---|---|
name, owner, version | what the app is called, who owns it, and its version (1 by default) |
shape | web, desktop, static, or a2ui |
reads | the group/space pairs the app reads |
actions | the action names the app may request; agents' card actions answer them |
views | the view names it asks of its feed |
ui | for an A2UI app: the protocol and version, the catalogs, the agent instance that draws it, the transport (views or a2a), and its page ids |
host | where a host serves the app for people: url, hostAgent, path, signOn (idp or none), publishedBy, status |
url, pkg, idpClient | where 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:
- 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. - Publish from your agent. An agent that draws A2UI writes
Surfaceentries into its group'sviewsspace and then aPublish. The group's app host serves the pages, and the console gives the app its card from thePublish. - 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 putfollowed bybma app deploy. - 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 itsttlafterwithdraw(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.
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.
| Dependency | Version |
|---|---|
ai.badmonkey.agentspaces:agentspaces-spring-boot-starter | 0.6.0 |
ai.badmonkey.agentspaces:embabel-agentspaces | 0.6.0 |
com.embabel.agent:embabel-agent-starter | 1.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
@Agentdescription becomes the card's description, and each@AchievesGoalbecomes a goal. - Each
@Actionbecomes a card action of kindembabel-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 becomesproduces.@SpaceTakeor@SpaceNotifyon the action adds the space binding. - The card carries
costHintsofframework=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
@AgentSpecor@SpaceAgentgets 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.
| Dependency | Version |
|---|---|
ai.badmonkey.agentspaces:agentspaces-springai | 0.6.0 |
ai.badmonkey.agentspaces:agentspaces-spring-boot-starter | 0.6.0 |
org.springframework.ai:spring-ai-starter-model-openai, for a real model | from 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
ToolCallbacknamed 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
TakeLeaseAdvisorrenews 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, thefleetChatModelbean writes each call as aModelRequestinto the model space, and a model server or the platform's gateway answers it.
Property under agentspaces.springai.model-client | Default | Meaning |
|---|---|---|
enabled | false | adds the fleetChatModel bean |
space | model-requests | the space requests go into |
model | empty | the model name a request addresses; empty means the server's default |
timeout | 120s | how 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.
| Dependency | Version |
|---|---|
ai.badmonkey.agentspaces:agentspaces-langchain4j | 0.6.0 |
dev.langchain4j:langchain4j-open-ai | 1.20.0 |
com.fasterxml.jackson.dataformat:jackson-dataformat-yaml | the 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 LangChain4jToolProviderwhose tools are the catalogue's current actions, namedfleet_<agent>_<InputType>, with a JSON Schema from the input record.ModelClient.of("<model>")makesfleet.chatModel()route calls through the space, andfleet.modelServer(...)serves this peer's models. It speaks the same model records as Spring AI.- A
FleetRuntimehost 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.
| Dependency | Version |
|---|---|
ai.badmonkey.agentspaces:agentspaces-micronaut | 0.6.0 |
ai.badmonkey.agentspaces:agentspaces-micronaut-processor, on the compiler's annotation processor path | 0.6.0 |
parent ai.badmonkey.agentspaces:agentspaces-micronaut-parent, as the quick start uses | 0.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@SpaceAgentis 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=truepublishes the embedded HTTP server as an AssetCard.- For a model,
agentspaces-micronaut-langchain4jadds 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.
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.
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:7700and its WebSocket listener127.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 upruns 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 underdev-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:7711over plain TCP. Undermtls, 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 upstarts the console detached under~/.bmaand prints the API's URL, the fleet console's URL on the port the console reads, and its log.bma downstops it, and the agent processes it launched keep running.bma up --port <port>moves the API and UI; point the other commands at it withBMA_CONSOLE_URL=http://127.0.0.1:<port>.BMA_HOMEmoves the home from~/.bma.- Sign-in is on by default (
bma.identity.mode=local). The first start writes theadminaccount's password to~/.bma/admin-password.txt.bma loginstores a token for the other commands, andBMA_TOKENoverrides it. - For the API,
POST /platform/v1/sessionwith{"name","password"}returns{"token": ...}. Send it asAuthorization: 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.
- 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
- Start the console and sign in, as in the section above. Both sides now run under
mtls.
- 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
- Watch it. A Watch is a work order a bridge takes. The bridge joins
shopthrough 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
- 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"]}'
- Check that a bridge holds it.
bma statuslists the bridges and the group each one holds ("holds" : "shop"), andGET /platform/v1/bridgesanswers the same. One bridge holds one group, and the console starts another bridge when a Watch waits, up to 16.
- Open the group. In Managed fleet › Groups,
shopshows 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 kindexistingand the stateOBSERVED: an agent that was already in the group.bma existing-agentslists the same rows. An instance you stopped keeps its row until its card's 15-minutettlruns out.
- 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: theOrderentry, the claim, the completion, and theShipment. It keys on fields such asorderId, and the quick start's order is alwayso-1.
java -jar target/shop-springai-1.0.0.jar --shop.port=7712 --shop.seeds=127.0.0.1:7711 --shop.order=kite
- Optionally, track it as a deployment. Reference it by name, and the console expects an agent called
fulfillerin 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 forgone-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.
- 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.
- 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"]}'
- Run your agent against the console's seed. The group's founding text is
shop-v1, the<group>-v1the 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
- Reference it as in step 9 above, so the console counts it.
--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.
- Read the group settings from the environment. The deployer sets the join for you, but your
application.ymlkeeps 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.
- Keep the JVM alive. A package with no web server needs
spring.main.keep-alive: true. The fulfiller's configuration already has it.
- Publish the deployment labels. The deployer puts
BMA_DEPLOYMENT,BMA_REPLICA, andBMA_TARGETin the process environment. Your agent must put them on its peer as hints. Without them the console counts no replica: afterstale-after(two minutes) the deployment reads "0 of 1 replicas mirrored in shop" and goes DEGRADED. The platform'sDeploymentHintsdoes it in one runner bean. Addai.badmonkey.platform:bma-console-common:0.1.0to 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.
- Write the manifest,
bma.package.yaml. The required fields areschemaVersion: 1,name(lower-case letters, digits, and dashes), a semverversion,kind: agent,publisher,runtime: spring-boot, andartifacts.jarassha256:<64 hex>of the jar. Addcards,grants,dependencies, andconfiguration.env(the names of the secrets the package expects, never their values) as the AgentCard section shows. Withoutside, 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.
- Sign it. The platform's
PackageSigner(inbma-package, whichbma-console-commonbrings) signs the canonical JSON of every field butsignaturewith your Ed25519 key. The sample'sSignPackagefills 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.
- 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
- Trust the publisher and ingest. Put the key that
SignPackageprinted into~/.bma/bma.yamland restart the console (bma down, thenbma up). The catalogue refuses a package that any other key signed. A registry on plain HTTP, such as one on the loopback, goes underbma.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
- Found or watch the group first.
bma deploydoes not found a group, and an agent deployed into a group nobody watches gets no seeds and founds a partition of its own. Foundshopas 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.
- Deploy. The target
boot-host-1is 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.
- Watch it come up.
bma deploymentsshows each row as DESIRED, ROLLING, LIVE, DEGRADED, DRAINING, or RETIRED, and a reference as EXPECTED until its card arrives.GET /platform/v1/commands?outcome=failedlists 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).
- Run it.
bma scale --id dep-fulfiller --replicas 2starts replica 1 beside replica 0,bma drain --id dep-fulfillermoves the row to DRAINING, andbma retire --id dep-fulfillerstops 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_FOUNDINGandAGENTSPACES_SEEDSfrom the group's Watch, withtls://added to each seed under a TLS profile;AGENTSPACES_SECURITY_PROFILE, the console's own profile;BMA_DEPLOYMENT,BMA_REPLICA, andBMA_TARGET, the labels of step 3, andBMA_CONFIG, the path of the rendered file;- a free
AGENTSPACES_BINDon the process target; AGENTSPACES_RULES_GATE=trueandAGENTSPACES_FLOWS_RECONCILE=true, so the published rules judge its claims and results;- a workload identity under the
mtls-oidcandzero-trustprofiles.
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-controlspace. A worker obeys it only when its code attaches aDirectiveGate(the starter'sDirectiveGatesbean) to that space and readspaused()anddraining(). 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
FleetRuntimehost 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.
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(orbma 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, thenbma login, orbma 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) ornone(open). The console's screens callidpby the wordtenant. - 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>returnsvault://kv/<key>, which goes into a deployment'senvRefs(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-clearfinding on a body already in a group'spolicy, 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.jsonunder 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 deploybma-model-gatewayinto the group. - Agents ask the gateway through the group's
model-requestsspace. The gateway takes aModelRequesttaggedtask=<kind>, or one whosemodelis the gateway's model name (gatewayby default). For a Spring AI agent, that meansagentspaces.springai.model-client.enabled=true,model-client.modelset to the gateway's model name, and amodel-requestsspace 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, andbma 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=truefrom 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, ormtls-oidcorzero-trustwith workload identities. - Narrow
agentspaces.security.grants.directive-issueron worker nodes to the console's peer id, whichGET /platform/v1/console-groupreturns aspeer. - 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
bridgescheck 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=failedlists 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/recarryruns one pass now.
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:
| Card | Id |
|---|---|
AgentCard | aspace://<group>/agent/<peer>/<agent> |
AssetCard | aspace://<group>/asset/<asset>; a content store adds its name and issuer |
ModelCard | aspace://<group>/model/<name>@<version>; a model server's own card appends its peer id |
AppCard | aspace://<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.publishadmits 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 areagentspaces.discovery.cache.max-entriesandmax-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.
| Card | ttl | Refreshed by |
|---|---|---|
AgentCard | 15 minutes | every JVM host, every agentspaces.card-refresh-millis (300000, five minutes) |
AssetCard | 15 minutes from the stock providers | your code calling ConnectorRuntime.refreshCards() |
ModelCard | the console's record (P1D by default, at most 30 days); 15 minutes from a model server | its issuer, by publishing it again |
AppCard | the record's, P1D in a shipped app.json | its 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 (
actionsanduion an AgentCard;reads,actions,views, anduion an AppCard) move into a document on the content swarm, cut into 65,536-byte pieces, and the stub'sspillnames 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. findandremoteFindreturn stubs. A caller that needsui,actions,reads, orviewscallsdiscovery.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
originandformats.
// 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 anmtlsgroup namestls://seeds, and the deployer addstls://itself when it renders seeds for a deployment. dev-localsigns 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.