Embabel, Embabel Worlds, and AgentSpaces
Embabel gives an agent goals, typed actions, and a planner that finds its own way. Embabel Worlds gives a business one living picture of itself, extended by realms. AgentSpaces carries both across a fleet of peers. This guide shows an Embabel agent joining a fleet, the four cards it meets there, and what a realm's parts become in a group.
Why Embabel and AgentSpaces together
This guide is for Java and Kotlin engineers who build agents with Embabel and want those agents to work in a fleet: many processes on many machines, sharing work and data. It also shows how a realm, the way an Embabel world learns about a system, becomes the shared vocabulary of that fleet. The how and the why are in the appendix.
Each project does its own job well, and the jobs fit together:
- Embabel gives an agent its goals, its actions, and a planner that finds the path between them. In the words of its README, "Plans are dynamically formulated by the system, not the programmer."
- Embabel Worlds gives a business one living picture of itself. Rod Johnson's launch post introduces it as "our innovative context layer built on the JVM, on top of the Embabel agent framework," and calls it "a layer above your business that understands it and exposes it to however you want AI to work with it." Realms extend a world; in the Worlds guide's words, "A realm is how your world learns about a system you already run."
- AgentSpaces carries agents, and the meaning a realm describes, across a fleet of peers. Peers share typed, leased entries in spaces and publish signed cards that say what each offers. No broker sits in the middle.
AgentSpaces takes its coordination model from Jini and JavaSpaces: typed entries, leases, and take, in the tuple-space tradition of Linda. Embabel gave it its first host and its design language:
- The specification names an Embabel extension as its first delivery target.
- Its entries are plain records matched by type, following Embabel's domain-model philosophy.
- Its action contract carries Embabel's
pre,post, andcostonto a card. - An AgentSpace generalizes Embabel's blackboard, the typed state of one agent process, into a shared, leased blackboard that every member of a group replicates.
A few words first
From Embabel:
- An agent (
@Agent) is a class whose methods are actions (@Action): typed steps that take domain objects and return one. - A goal (
@AchievesGoal) marks an action whose result is what the agent is after. - Conditions say when an action may run and what it makes true. In the README's words, "most conditions result from data flow defined in code, allowing the system to infer pre and post conditions": an action's input and output types are its first conditions.
preandposton@Actionname further conditions, which@Conditionmethods evaluate, and an action may name acostand avalue. - The planner chains actions toward a goal by their types. GOAP is the default, and Utility AI, Hybrid, and Supervisor planners are there too. Embabel replans after every action.
- The blackboard holds the domain objects of one agent process. The AgentPlatform runs agents and deploys new ones.
From Embabel Worlds:
- A world is, in Embabel's words, "a governed, living knowledge graph of your business, derived from the systems you already run and owned by you."
- A realm is a set of declarative files that teaches a world about one system: its types, where each object comes from, its APIs, its apps, and more.
- A world runs on an appliance you install, and it answers through doors such as MCP, REST, SQL, and an OpenAI-compatible model endpoint.
- A Worlds agent is, in the Worlds guide's words, "a named colleague that does work in your world." It has a job and a sponsor, the person who answers for it, and it holds the routines that do the work. It is off duty, on duty observing, or on duty, and a changed routine does nothing different until its sponsor signs.
From AgentSpaces:
- A peer is one running process. A group is the set of peers that work together. A space is a named, replicated store of typed entries inside a group, and every entry has a lease that says how long it lives.
- A card is a signed, leased advertisement of what an agent, an asset, a model, or an app offers.
- A remote action is another peer's card action seen from your peer: write the input entry, wait for the result entry.
- An import reads a realm and drafts what a group needs from it. A person approves the drafts before any of them reach the group.
@Agent, a Worlds agent, and an AgentSpaces peer's agent with its AgentCard. Our AgentCard is a signed, leased AgentSpaces record. It is not the A2A protocol's agent card, though our A2A gateway serves one as the other.Three projects, one picture
| Embabel Agent Framework | Embabel Worlds and its realms | AgentSpaces | |
|---|---|---|---|
| Answers | how does this agent reach its goal? | what does this business hold, and where does it come from? | who in the fleet does the work, and on which peer? |
| Unit | an @Agent and its actions | a world, extended by realms | a group of peers and its spaces |
| State | the blackboard of an agent process | the world's knowledge graph | leased entries every member replicates |
| Reached through | the AgentPlatform, and goals exported over MCP | MCP, REST, SQL, GraphQL, OData, webhooks, an OpenAI-compatible model | signed cards found by discovery, and remote actions |
Names and ownership
A few names, used the way their owners use them:
- Embabel Worlds is the product, and realms extend a world. Worlds is commercially licensed, and Rod Johnson's launch post says "it will be free for individual use."
- The Embabel Agent Framework is the open-source
embabel-agentproject, Apache 2.0. In its README's words it is "Written in Kotlin but offers a natural usage model from Java," and "From the creator of Spring." Rod Johnson is the founder of Embabel and the creator of the Spring Framework. - Embabel owns the realm format and its specification, a living draft at worlds.embabel.com/spec/realms. The specification is, in its notice's words, "authored and governed by Embabel," and "Embabel decides what it contains." The names Embabel and Virtual Cypher are Embabel's.
- The realms themselves belong to their authors. The same notice says: "Realms and applications you author are yours."
- AgentSpaces does not implement the realm specification. An import reads a realm's declared parts and drafts records from them. Embabel's notice lists, among the things anyone may do freely, "Build applications, tools, agents or services that read realms or call an appliance." Our pages make no compatibility or conformance claim for the import.
- AgentSpaces itself reads no realm. A group receives ordinary entry types and cards.
A realm and a group
A realm and a group answer different questions, and an import joins them. This part shows the split, who owns each piece, and the one thing both sides share: the names of the types.
What each side answers
- The parts of a realm an import reads (types, producers, APIs, and apps) answer the question: what are the objects, and where do they come from? A realm can also bring agents, routines, and apps that run in a world, and that work stays in the world. A realm knows nothing of a fleet's peers, leases, or takes.
- A group answers another: who works on the objects, and how? Its spaces hold the work, its cards say who offers what, and its flows shape the work. It knows nothing of a producer's SQL or an API's token until a configuration tells one of its agents.
- An import joins the two. It reads the realm, drafts what the group will need, and carries what a person approves into the group.
Data moves one way, from the realm into the group. Nothing writes back into a realm, so the realm stays the source of meaning.
Who owns what
| Concern | The realm's authors own, in Embabel's format | AgentSpaces owns |
|---|---|---|
| Types | names, descriptions, properties (an identity property among them), parents, spines, and the realm's own label | entry type IRIs, as data it never interprets |
| Producers | the kind, and the operation, query, or other source it reads | the AssetCard a connector publishes for what it serves |
| APIs | the OpenAPI documents and the operations they allow | the FlowManifest a group's reconciler applies |
| Apps | the pages and their titles | the AppCard: kind, shape, origin, formats, ui, host |
| Prompts | prompt contributions, such as examples.md for a world's chat | nothing |
| The format | nothing: Embabel owns its structure, realm.ts and the legacy YAML | the registered origin system realm |
What each part becomes
Each realm part reaches the group as an ordinary AgentSpaces record, once a person approves its draft:
| Realm part | What reaches the group |
|---|---|
realm (name, version, commit, namespace) | origin on each app card, and the namespace of every entry type IRI |
types | entries whose schema name is the type's IRI, the namespace followed by the type name |
producers of kind remote or api | an AssetCard per operation, from an OpenAPI 3.x and REST connector |
producers of kind sql | an AssetCard per query, from a SQL connector |
| producers of any other kind | the AgentCards of a fleet package that serves the agent kind <realm>/<producer> |
apis | a FlowManifest with one code stage per listed operation, on a lane named after the API |
prompts | the group's prompt set, carried as a configuration |
apps | an AppCard with owner the realm, origin realm, the realm's namespace in formats, and the app link app://<realm>/<app> |
- A realm names no spaces of its own. The lanes come from the flows its APIs become.
- One import targets one group and creates no group.
- A realm ships no code to the fleet, so a fleet package serves the producer kinds no connector serves.
The realm site's mapping page says how an import runs, and its worked example imports one realm end to end.
One vocabulary: the type names
Both sides meet in the type names. In a world, a realm's types are graph labels, and every node a realm owns also carries the realm's own label. A fleet names entry types by IRI, so the import document gives the realm a namespace IRI such as https://acme.example/realm/claims-ops#. That pairing is ours: realm.yml has no namespace field, and in a world the realm's own label qualifies its type names.
The import names each entry type by that namespace and the type name, so the realm's Claim becomes https://acme.example/realm/claims-ops#Claim in the group. A planner's goal, a flow's cue, and a worker's take then name the same thing.
On the JVM, a SchemaRegistry gives a record class that name on the wire. Declare one as a bean, and the starter's spaces and the Embabel cards share it. The extension's test shows an Embabel agent's card named through one; the test sets the registry on the group directly rather than through a bean:
// EmbabelBinderTest.java String ns = "https://example.org/test#"; SchemaRegistry shared = NamespaceSchemaRegistry.of(Map.of("ai.badmonkey.agentspaces.test", ns)); spaces.group("fleet").schemaRegistry(shared); AgentCard card = binder.bind(new TwoActionDesk()).orElseThrow(); assertThat(card.consumes()) .containsExactlyInAnyOrder(ns + "TaskEntry", ns + "FindingEntry");
NamespaceSchemaRegistry.of(...)maps a Java package to an IRI namespace. Every record in the package is named<namespace><SimpleName>.- When the application declares a
SchemaRegistrybean, every space the starter builds and every group's binder use it, so a card names exactly what the spaces write. - On the reading side, the remote-action registry resolves an IRI on another peer's card back to your local class, so a remote action is typed with your own records.
- Map your Embabel domain package to the realm's namespace, and your actions speak the realm's names.
An Embabel agent in a fleet
The extension embabel-agentspaces works in two directions. Outbound, each Embabel @Agent bean becomes an AgentCard in every group the application joins. Inbound, the actions other peers advertise become typed actions for Embabel's planner. Nothing in your agent's code changes for either.
The dependency
| 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, for an application that plans | 1.5.2 in our integration test |
com.embabel.agent:embabel-agent-api, for an application that only advertises | 1.5.2 in the bakery sample |
Embabel's current release is 1.5.4, of 2026-10-28. Our integration test pins 1.5.2, and it also passes against 1.5.4 (run on 2026-11-10 with -Dembabel-agent.version=1.5.4).
There is no @EnableAgentSpaces. The extension switches itself on when Embabel is on the classpath:
// EmbabelAgentSpacesAutoConfiguration.java @AutoConfiguration @ConditionalOnClass(name = "com.embabel.agent.api.annotation.Agent") public class EmbabelAgentSpacesAutoConfiguration {
- The condition names Embabel's
@Agentby its class name, so without Embabel the configuration never loads and the dependency stays one-directional. - The extension reads Embabel's annotations reflectively, by name. It builds with no Embabel artifact and reads whatever attributes the application's Embabel version has. It is tested with 1.5.2, and passes with 1.5.4.
The smallest Embabel agent in a group
An Embabel action can be a fleet worker at the same time. The bakery sample's baker is an ordinary Embabel agent whose action also carries @SpaceTake:
// EmbabelBaker.java @Agent(name = "baker", description = "Bakes a cupcake for every order") public class EmbabelBaker { @AchievesGoal(description = "A cupcake for the order") @Action @SpaceTake(lease = "15s", pollTimeout = "500ms") public Cupcake bake(Order order) throws InterruptedException { Thread.sleep(8_000); return new Cupcake(order.id(), order.flavor(), "embabel"); } }
@Actionmakesbakea step Embabel's planner can use, and@AchievesGoalsays its result is a goal.@SpaceTakemakes the same method a worker. It takes oneOrderunder a 15-second lease and writes back theCupcakeit returns. If the process dies first, the lease lapses and the order comes back for another baker.- In the bakery sample this class was bound through the core binder, with no Embabel platform started, so it has one card.
- Under the Spring Boot starter the same class gets two AgentCards today. The starter binds the take and publishes the core binder's card, named by the decapitalized class name (
.../embabelBaker). The extension publishes a second card, named by@Agent(name)(.../baker). Other peers' planners then see bothembabelBaker_Orderandbaker_Order, and an@Agentwith no name gives the two cards one id. See what to know today.
The application around an agent is ordinary Spring Boot. Party Bus, under its -Pembabel profile, configures the starter and the extension in one file:
# application.yml agentspaces: keystore: ./partybus-keys bind: 0.0.0.0:7700 # ... groups: - name: partybus founding: partybus-v1 spaces: - { name: trip } - { name: research } # ... embabel: remote-actions-enabled: true remote-action-timeout-millis: 60000 remote-agent-name: partyBusFleet # ... embabel: models: default-llm: gpt-4.1-mini # as Tripper's researcher; the plan itself deserves a better one
- The starter joins each group named under
agentspaces.groupsand builds its spaces. agentspaces.embabelconfigures the extension. Here the generated agent ispartyBusFleet, and each fleet action waits up to 60 seconds for its result.remote-actions-enabled: falsemakes an application an advertiser only. It publishes its cards and builds no planner bridge, which suits an application that runs no Embabel platform. Such an application needs onlyembabel-agent-api.embabel.models.default-llmis Embabel's own setting, and the extension leaves it alone.
What the fleet learns
The extension's binder turns each @Agent bean into one AgentCard per configured group, and each group's binder adopts the card so it is refreshed with every other card:
// EmbabelBinder.java return new AgentCard( "aspace://" + group.id().value() + "/agent/" + identity.peerId().value() + "/" + agent.name(), identity.peerId(), group.id(), clock.instant(), Duration.ofMinutes(15), agentId, agent.description(), agent.goals(), List.copyOf(consumes), List.copyOf(produces), Map.of("framework", "embabel"), spaceBindings, null, declared(actions));
- The agent's name is the
@Agentname. When that is blank, Embabel itself uses the class's simple name (EmbabelBaker), and the extension the decapitalized simple name (embabelBaker). The card's description is the@Agentdescription. - Each
@AchievesGoaldescription becomes one of the card'sgoals. - Each
@Actionbecomes a card action of kindembabel-action, with its own description (cut at 512 characters), the entry types it consumes and produces, and its contract from@Action(pre, post, cost). - Other peers treat an
embabel-actionas invocable, so it becomes a remote action on their side. It is answered only when something takes from its space:@SpaceTakeor@SpaceNotifyon the same method, or another worker. - Embabel's own parameter types, such as
OperationContext, are not entries, and neither are strings or primitives. They stay off the card. costHintscarriesframework=embabel, so a reader can tell where the card came from. Thettlis 15 minutes, and the card is published again every five minutes.
The contract travels as written. From the binder's test, an action with conditions and a cost:
// EmbabelBinderTest.java @Action(description = "Researches one topic", pre = {"topic-chosen"}, post = {"findings-ready"}, cost = 2.0) public FindingEntry research(TaskEntry task) { // ... assertThat(research.contract().pre()).containsExactly("topic-chosen"); assertThat(research.contract().post()).containsExactly("findings-ready"); assertThat(research.contract().cost()).isEqualTo("2.0");
- The test checks that the value is carried through as written. Embabel types
costandvalueasZeroToOne, from 0 to 1, so a real action would say something likecost = 0.2. - The card carries
costas text, and an action at Embabel's default cost of 0 carries none.
The fleet's actions in your planner
The other direction is where the two systems do the most together. Embabel's README names the aim of its platform abstraction: "running locally while potentially offering higher QoS in production without changing application code." A fleet is one way to do that. The agent's code stays the same, and some of its steps run on other peers.
Every action other peers advertise becomes one typed @Action method on a generated Embabel agent, so Embabel's planner matches a fleet skill by its types, exactly as it matches a local action. An agent that plans over both local and generated actions can chain a local action into another peer's skill and back.
Embabel plans over Actions in an agent's scope, and annotations are one way to declare them. The extension generates an annotated class so that it never links against Embabel's API: Embabel's own AgentMetadataReader turns it into an agent, the same path a hand-written agent takes. Embabel also lets code build actions directly, as its experimental embabel-agent-remote module does with AbstractAction and DynamicType.
// EmbabelRemoteActions.java for (Map.Entry<String, RemoteAction> entry : byMethod.entrySet()) { RemoteAction action = entry.getValue(); var method = builder.defineMethod(entry.getKey(), action.outputType(), Visibility.PUBLIC) .withParameters(action.inputType()) .intercept(MethodDelegation.to(interceptor)) .annotateMethod(AnnotationDescription.Builder .ofType(actionAnnotation).build());
- Each method is named
<agent>_<InputType>, takes the card's input type, and returns its output type. The card's goals become the method's@AchievesGoal. - The extension deploys the generated agent onto your
AgentPlatformthrough Embabel's ownAgentMetadataReader, and deploys a new generation whenever the fleet's set of actions changes. - Calling a generated method writes the input as a leased entry where the other agent takes it, and waits for the result entry. No result within the timeout is an
IllegalStateException, which Embabel's retry decision treats as not retryable, so the action fails at once and the planner treats it as failed.
The integration test runs this against the real Embabel platform, 1.5.2 as pinned and 1.5.4 as well. A worker on a plain AgentSpaces peer advertises Brief in and Summary out. The Embabel application has no action of its own, and its planner still reaches the Summary goal, through the fleet:
// EmbabelFleetPlanningTest.java @AgentSpec(name = "summarizer", description = "Summarizes briefs", goals = {"produce a summary"}) public static class Summarizer { @SpaceTake(space = "work", pollTimeout = "PT0.2S") public Summary summarize(Brief brief) { return new Summary(brief.topic(), "summary of " + brief.topic()); } } // ... // Embabel's planner plans Brief -> Summary and runs the fleet action. Summary summary = AgentInvocation.create(platform, Summary.class) .invoke(new Brief("tuple spaces")); assertThat(summary.text()).isEqualTo("summary of tuple spaces");
@AgentSpecand@SpaceTakeare AgentSpaces annotations. The worker is a plain AgentSpaces peer with no Embabel on it.- The Embabel side runs a real Spring Boot application with Embabel's own platform, and a scripted model the test never calls.
In the Superfriends example the chain is longer. The local agent can open an inquiry, wait for the analysts' decision, commission a dossier, and brief a verdict, but it cannot write the dossier itself. GOAP finds open, awaitDecision, commission, report_ReportRequest, brief, where report_ReportRequest is a report service on another peer. The seat asks the platform for one agent over every deployed action (platform.createAgent), so GOAP can chain HallPlanner's actions with the generated agent's:
// HallPlanner.java @Action(description = "Commissions the research dossier on a decided inquiry") public ReportRequest commission(Decided decided) { return new ReportRequest(decided.inquiryId(), decided.ticker()); } // ... @AchievesGoal(description = "A verdict on the question: the hall's position and a one-paragraph summary") @Action(description = "Briefs the verdict from the dossier and the decision") public Verdict brief(Dossier dossier) {
Party Bus applies the same idea to Embabel's own travel planner, Tripper. In its README's words, "Tripper planned your trip. Party Bus brings the friends." It keeps Tripper's domain model and planner and hands the research to a fleet of specialists, each a generated action the planner can chain.
- Under its
-Pembabelprofile, the real GOAP planner plans across the fleet. - Without Embabel, a small breadth-first planner stands in. Its README says plainly that the Embabel profile is the one part of the project the default build does not verify.
Choreography, not RPC
A remote action is not a remote procedure call. The "call" is an ordinary signed, leased entry that any qualified agent may answer, and the caller holds no channel to any particular peer. The card names who advertised the skill; the space decides who serves each request.
- A worker that dies mid-task lets its take lease lapse, and the task comes back for another worker. So a failed remote action means no one in the fleet could serve it in time, not that one peer crashed.
- The remote step is still a typed action the planner chose by its types. What changes is where it runs.
- Large values travel too. With the content swarm on (
agentspaces.content.enabled=true), a take's input or a result above 4 MiB moves as a content-swarm artifact and arrives whole on the planner's side.
Settings
Property under agentspaces.embabel | Default | Meaning |
|---|---|---|
remote-actions-enabled | true | builds the bridge from the fleet's cards to a generated agent |
auto-deploy | true | deploys the generated agent onto the application's AgentPlatform bean |
deploy-poll-millis | 2000 | how often the deployer looks for a changed set of actions |
remote-action-timeout-millis | 30000 | how long a generated action waits for its result |
remote-agent-name | remoteFleet | the generated agent's name on the platform |
remote-agent-description | Capabilities other fleet members advertise through AgentCards | its description |
Embabel's API jar carries its own embabel.models.default-llm in a properties file it loads, and Spring Boot ranks that above SpringApplicationBuilder.properties(...), which are only default properties. Pass yours as a command-line argument, as the integration test does with --embabel.models.default-llm=scripted.
What to know today
These are limits of our bridge, stated plainly:
- Two cards for a worker. Under the Spring Boot starter, an
@Agentwhose@Actionalso carries@SpaceTakegets the core binder's card and the extension's card, as the baker shows. Callers see the action twice, under two agent names. - An advertised action needs a worker. An
@Actionwithout@SpaceTake(or@SpaceNotify, or another worker on its space) is advertised but served by nobody, and callers time out. - The first group. The default bridge covers the first configured group. Define your own
EmbabelRemoteActionsbean to route several spaces, as the Superfriends planner does. - One entry parameter. A bound space method takes exactly one entry parameter, so an action that also takes
OperationContextcannot carry@SpaceTake. Keep the worker method to its one entry, and keep the actions that use the context as plain@Actionmethods. - Deploy only. The bridge deploys each new generation and removes none. When a fleet action goes away, the next generation leaves it out, and the earlier generation stays registered until the application restarts. Calling a vanished action times out, which the planner treats as the action failing.
- No UI declaration yet. A card the extension derives carries no
uiand no agent key of its own. - Local types. A remote action's types must resolve to classes on your classpath, directly or through the schema registry. Embabel's
DynamicType, whichembabel-agent-remoteuses, is a way the bridge could lift this. - Assets are not actions yet. The remote-action registry lists asset operations, but the Embabel bridge generates planner actions from agent cards only.
- The contract travels out, not back in. A generated
@Actioncarries the card's types and goals, but no description,pre,post, orcost. Embabel's planner therefore sees every fleet action at cost 0, with only its type conditions. Our card'scostis free text (a number, a duration,low), where Embabel's is 0 to 1. - Value and dynamic cost are not carried. Cards carry a static
costbut notvalue,costMethod,valueMethod,canRerun, orreadOnly. Utility AI planning, which weighs value, sees none of it for a fleet action. - Annotated agents only. The binder reads
@Agentclasses and their@Actionand@AchievesGoalmethods. Actions on@EmbabelComponentclasses,@Stateclasses, Kotlin DSL agents, and agents deployed by code are not carded, and@Conditionmethods stay local. Reading the platform's own agent model (AgentPlatform.agents()) would cover them all.
The four cards, seen from Embabel
The developer guide introduces the four cards for any agent. Here they are again, from where an Embabel developer and a realm author stand. Every card is signed by its issuer, leased by its ttl, and gossiped into the ad cache of every peer in the group. A card says what its issuer claims, and the party that reads it decides what to allow.
| Card | In Embabel's terms | Who issues it | Where it is defined |
|---|---|---|---|
AgentCard | an @Agent: its description, its goals, and each @Action with its types and its pre, post, and cost | the extension's binder, on the agent's own peer | your annotations, read by EmbabelBinder |
ModelCard | an LLM Embabel picks by name, by role (embabel.models.llms.<role>, LlmOptions.withRole), or by ModelSelectionCriteria; in a fleet, a model the group may route to | the party that admits the model, or a model server for itself | ModelCard in agentspaces-api, filled in by its issuer |
AssetCard | what a realm's remote, api, and sql producers serve, through a shipped connector | the connector peer that holds the source | a connector's AssetProvider |
AppCard | a realm's app, with origin realm, or a page an agent draws with A2UI | the issuer that ran the import, or the app host for a Publish | a realm import, a Publish, or AppCardPublisher |
AgentCard: an agent's actions and goals
Of the four, the AgentCard is the one an Embabel application writes with no code at all. The card is the fleet's routing table: a caller finds who produces a type, and writes the input where that agent takes it.
| From Embabel | Onto the AgentCard |
|---|---|
@Agent(name); when blank, Embabel uses the simple class name and the extension the decapitalized one | the agent's local name, and the card id aspace://<group>/agent/<peer>/<name> |
@Agent(description) | description |
each @AchievesGoal(description) | one entry of goals |
each @Action method | one entry of actions, kind embabel-action, at most 64 |
@Action(description) | that action's description |
| the action's domain parameter and return types | consumes and produces, for the action and for the card |
@Action(pre, post, cost) | that action's contract |
@SpaceTake or @SpaceNotify on the action | spaceBindings, so callers route with no configuration |
Producers of other kinds have no connector. In Embabel's specification a world's own engine serves them: compute is an in-process function over keys, vector a semantic search, and jar reads a Java jar's classes as data. An import runs none of them. It drafts a configuration addressed to an agent kind named <realm>/<producer>, which a fleet package may choose to serve, and that package's agents publish AgentCards like any other. A realm itself ships no code to the fleet.
The record is AgentCard in agentspaces-api. The developer guide's cards section shows how a peer finds and reads it.
ModelCard: the models Embabel chooses
Embabel takes model choice seriously. Its reference guide says "Embabel encourages you to think about LLM choice for every LLM invocation," and its README advises: "try to find the best LLM for a given task, rather than automatically choose a familiar provider." A ModelCard is the fleet's side of that choice: a model a group may route to, signed by its issuer, with its tasks, engine, licence, residency, and the peers that serve it.
Today the two meet at different places:
- An Embabel action reaches its model through Embabel's own configuration, an LLM service and
embabel.models.default-llm. The Superfriends planner wraps its own Spring AI model:
// EmbabelPlannerApp.java @Bean SpringAiLlmService superfriendsLlm(ChatModel plannerChatModel) { return new SpringAiLlmService(LLM, "superfriends", plannerChatModel); }
- A fleet agent reaches a model through the gateway. It writes a
ModelRequestinto the group'smodel-requestsspace, and the gateway routes it to a model the group may use. An AgentCard names no ModelCard. - The meeting point is the fleet's chat model.
FleetChatModelis a Spring AIChatModelwhose provider is the fleet. Embabel uses Spring AI as its default LLM connector, behind its ownLlmMessageSenderabstraction, and itsSpringAiLlmServicewraps any Spring AIChatModel. So an Embabel application that addsagentspaces-springaican wrapFleetChatModelinSpringAiLlmService, and its actions then reach the fleet's models with no API key on that peer. This path is designed and not yet tested: no test in our repository pairs the two. - A second path. Embabel's own
LlmMessageSenderinterface is another way in. Embabel's guide covers implementing it "for providers not otherwise supported by Embabel," and Embabel's lead pointed us to it in Discussion #2149. A sender over the gateway'smodel-requestsspace is not built. - A world is a model too. Embabel Worlds answers as an OpenAI-compatible model, and Embabel's site shows an Embabel agent configured with its world as the default LLM. An Embabel agent in a fleet can do the same: the fleet carries the action, and the world grounds the answer. We have not run that in a fleet yet.
The developer guide's model cards section shows how a peer finds a ModelCard.
AssetCard: what a realm's producers serve
An AssetCard advertises data that stays at its source. Embabel's realm specification describes each producer as "a Repository over an external store (the Spring Data analogue: one Repository abstraction, different stores underneath)." An AssetCard is the fleet's side of the same idea: a connector peer holds the source and publishes one card per asset, and agents find assets the way they find agents. In the realm mapping:
- a producer of kind
remoteorapibecomes an AssetCard per operation, from an OpenAPI and REST connector; - a producer of kind
sqlbecomes an AssetCard per query, from a SQL connector; - a producer of any other kind becomes a configuration for a fleet package that serves it.
Which producer kinds have connectors is our own choice. Embabel's specification defines the fields of every kind.
A connector builds its cards through the AssetProvider interface of agentspaces-connect-core:
- A REST connector publishes one card for each operation the API's OpenAPI document allows. A
GEToperation is a readable asset, and the card lists every other operation as an invocation. - The connector applies the API's security scheme with the configured credential, which never appears on a card or in a log. Realms work the same way: in the specification's words, "Realms carry credential references, never values."
- The card's
shapenames the operation and its response schema, so a reader knows what a query returns. - A world could be a source too. Its SQL door speaks the Postgres wire protocol, so a SQL connector that serves a realm's
sqlproducers is a natural first try. We have not pointed a connector at a world yet; a fleet beside a running world shows where it would fit.
AppCard: realm apps and agent pages
The AppCard is the newest card, and the place where Embabel Worlds and AgentSpaces meet most directly. Worlds has apps: Rod Johnson's launch post lists "Custom UIs that users can safely vibe code on our infrastructure," and a realm can ship HTML apps of its own. An AppCard lets a fleet find and serve applications for people, and say where each one came from. Three fields answer three questions:
kindsays how the app connects. It is a closed set:peer,fed,gateway, orassembled.originnames the external system the app came from, such asrealm, and the app's id there. It is open.formatslists the media types and vocabulary IRIs the app reads or renders, such astext/htmland a realm's namespace. It is open too.
// AppCard.java public static final List<String> KINDS = List.of("peer", "fed", "gateway", "assembled"); public static final List<String> SHAPES = List.of("web", "desktop", "static", "a2ui"); public static final List<String> TRANSPORTS = List.of("views", "a2a");
A realm's app. An import drafts an AppCard for each app of a realm, and the card reaches the group once a person approves it. For the claims-desk app of the claims-ops realm, the card holds:
| Field | Value |
|---|---|
owner | claims-ops |
origin | system realm, ref claims-ops/claims-desk, version 0.2.0, the realm's own semver |
origin.attrs | realm.format (the form read and the Embabel commit the reader follows), realm.namespace, realm.digest (the SHA-256 of the import document), realm.commit (the realm's own commit), and realm.reads of Claim,Payment |
url | app://claims-ops/claims-desk, Embabel's app link |
formats | text/html, then https://acme.example/realm/claims-ops# |
- A member that understands the realm's vocabulary finds every app that speaks it with
card.handles(namespace), and every app of one realm withcard.fromOrigin("realm", "claims-ops/*"). - The issuer signs that it read the import document and that the app, version, namespace, commit, and type names are that document's own. The card makes no claim that the realm's authors approved the publication. A reader can check the card against the realm itself through
realm.commitandrealm.digest. - An import writes kind
fedtoday. The protocol ties no kind to an origin, and the choice does not match how Embabel defines a realm app. In the specification a realm app runs inside a world: it calls the world's tool gateway (fetch('/api/v1/tools/{name}')) and its lenses, "in the user's authenticated session," and it carries the Embabel badge (#embabel-badge). So no agent of the group feeds it. - The link
app://<realm>/<name>follows Embabel's app address, which a world that installs the realm serves at/apps/<realm>/<name>.html. The realm'surlstays its source or documentation link, and no app link uses it.
The realm site's app card page lists every field the card must carry.
An agent's A2UI page. A2UI is an open, Apache 2.0 protocol for agents that compose user interfaces as data: the agent sends components, and a renderer the host trusts draws them in its own look. AgentSpaces carries A2UI through spaces. An agent writes Surface entries into its group's views space, reads SurfaceAction entries back, and asks the group's app host to serve the pages for people. The agentspaces-a2ui example draws a decision card with an Acknowledge button:
// SurfaceDeskExampleTest.java Surfaces pen = new Surfaces(deskViews, "desk", InstantSource.system()); pen.create("decision-77", null) .data("decision-77", "/", Map.of("id", "77", "verdict", "approve")) .components("decision-77", List.of( Surfaces.card("root", "col"), Surfaces.column("col", List.of("title", "verdict", "ack")), Surfaces.text("title", "Decision 77", "h3"), Surfaces.bound("verdict", "/verdict", "body"), Surfaces.button("ack", "Acknowledge", "acknowledge", Map.of("decision", "77"), "primary")));
Then the pen asks the group's app host to serve the pages:
// Surfaces.java public Publish publish(List<String> surfaces, String title, String host, String signOn) { Publish p = new Publish(Publish.VERSION, app, "", surfaces, title, host, signOn, Map.of(), clock.instant()); views.write(p, Lease.of(lease), Map.of("app", app, "kind", "publish")); return p; }
Surfacesis a plain helper over aSpace. It writes the A2UI v0.9.1 envelopes in order and hands back each action a person takes. The A2UI project has since published v1.0.- Two open catalogs ship with
agentspaces-a2ui:agentspaces-viz(charts, tables, maps, graphs, timelines, forms, and more) andagentspaces-widgets(ChatInput, FileShare, ApprovalCard, and TimelineStrip). A host adds its own catalogs beside them. publish(...)writes aPublishentry into theviewsspace. The app host serves the pages and fills the card'shost: the address people open, andsignOnofidp(the default) ornone.- The agent draws the page, and the host serves it.
From an Embabel action. Embabel already models a person in the loop: an action returns WaitFor.formSubmission(...), and the agent process waits in WAITING until the answer comes back. An A2UI page is a natural way to draw that form for a person anywhere in a fleet. Surfaces takes a Space, so an Embabel action can hold a pen the way any Spring bean holds a collaborator. No example does this yet, and the card the extension derives carries no ui today.
A realm in a running fleet
The realm site's worked example imports the claims-ops realm of the example company Acme Insurance (acme.example). This part says what that import gives a group, and how an Embabel agent then works on the realm's types.
The claims-ops example
The realm holds three types, four producers, one API with three operations, and two apps. Once a person approves the import's drafts, the group holds:
- three entry types,
Policyholder,Claim, andPayment, each named by the namespacehttps://acme.example/realm/claims-ops#; - AssetCards for the operations
listClaimsandgetPayment, from a REST connector, and one for thepaymentsLedgerquery, from a SQL connector; - a configuration for the agent kind
claims-ops/riskScore, which a fleet package may choose to serve; - the FlowManifest
realm-claims-ops-claims-api, with the stageslistClaimsandgetPayment. The API'soperation-ids, in Embabel's words an "ExactoperationIdallowlist," leaves outorderPayment; - two AppCards, for the apps
claims-deskandledger-view; - the prompt
claims-ops/triage, from thetriageagent's prompt file.
An import reads a realm's declarations, never its data. As Embabel's guide puts it, "A realm is not an import": nothing is copied into a mirror, and the same holds in a fleet, where connectors read each source when asked. A second import drafts new versions of the same records, and nothing in force changes until a person approves it.
The import reads the legacy YAML form of a realm, folded by hand into one import document. In Embabel's specification, "realm.ts is the preferred realm definition format; the host reads it directly," and "YAML receives no new features." The realm site's mapping page says how an import runs, and its worked example shows the import document.
An Embabel agent on the realm's types
Once the realm's types are the group's entry types, an Embabel agent can plan over them. Three things line up:
- Name your records by the realm's namespace. Declare a
SchemaRegistrybean that maps your domain package, for examplecom.acme.claims, tohttps://acme.example/realm/claims-ops#, as in the vocabulary section. YourClaimrecord is thenhttps://acme.example/realm/claims-ops#Claimon the wire and on your card. - Write actions over those records. The extension's card advertises the realm's names, and the actions on other peers' cards resolve back to your classes.
- Make a realm type your goal. An
@AchievesGoalaction that returns aPayment, say, is reached through local actions and fleet actions alike, when the agent you run plans over both, as the Superfriends seat's agent does throughplatform.createAgent.
Each piece is tested on its own: a registry naming an Embabel card, the cards an import makes, and Embabel's planner reaching a goal through the fleet. No example runs the whole chain yet.
Going further together
Embabel and AgentSpaces are both moving fast, and toward the same place: agents that plan over typed steps, wherever those steps run. This part says what each side brings, how Embabel describes its own road, and the ways the two teams can work together.
What each side brings
Embabel brings:
- a planner that finds its own path over typed actions, replans after every action, and lets the same actions run under GOAP, Utility AI, or Supervisor planning;
- a domain model in plain, strongly typed code, with Spring's component model and testability "from the ground up";
- in Embabel Worlds, a context layer built on the framework: a world that knows the business, extended by realms you pick from the Realm Store or make your own with your coding agent, and reached through MCP, REST, SQL, and model doors.
AgentSpaces brings:
- a fleet with no broker: groups of peers, typed entries under leases, and signed cards that say what each peer offers;
- remote actions that any planner can chain, with a take lease, so a crashed worker's task goes to the next;
- connectors that serve a realm's sources as assets, app hosts that serve pages for people, and A2UI pages drawn as data;
- an import that carries a realm's parts into a group once a person approves them.
A platform built on AgentSpaces can add guardrails, rules, and flows to a fleet.
Some design choices the two already share:
- Nothing in the middle. The Worlds guide says: "There is no Embabel server in the path of anything you do." A fleet has no broker.
- A person signs. A Worlds agent runs the version its sponsor signed. Every AgentSpaces card is signed by its issuer, and every draft of a realm import waits for a person's approval, much as Worlds puts "approval gates exactly where you want them."
- Data stays where it is. A world copies nothing into a mirror, and Rod Johnson's post "The Graph Is a View, Not a Database" says: "The answer is federation." An AssetCard keeps its data at the source too.
Rod Johnson's year-end post sets Embabel's direction plainly: "Given our goal of being the agent framework for enterprise, we're focused on minimizing nondeterminism and integrating with existing business systems." AgentSpaces tries to keep that line. A remote step is still a typed action the planner chose, and a realm's systems arrive as cards that connectors serve.
A fleet beside a running world
A fleet and a world could also work side by side, each where it is strongest. Every arrow below is a path we have not tried yet. Each one uses a door a world already opens, or a kind of connector a fleet already has:
- The SQL door. A world's SQL door speaks the Postgres wire protocol, with saved views as tables, and has been verified with JDBC. A Postgres connector could serve those views to a fleet as AssetCards.
- The model door. A world answers as an OpenAI-compatible model, so an Embabel action in a fleet could use its world as its LLM.
- The MCP door. An MCP connector could turn a world's tools into cards with take actions, and its resources into assets.
- A world's apps. An AppCard could link to an app where its world serves it.
- The publisher. Once the Realm Publishing Protocol is released, a fleet service could publish itself to a world as a new realm.
Every door signs in with the credentials its client sent. In the Worlds guide's words, "Your login is forwarded, never held," so what a client reads is what that user may read. A realm declares no sign-in client of its own: in Embabel's specification, client credentials belong to the deployment. On the fleet's side, an app card's host.signOn says whether the app asks for sign-on, idp, or not, none.
Embabel's own road to federation
Federation is on Embabel's own map. Its README says: "Embabel agent systems will also support federation, both with other Embabel systems (allowing planning to incorporate remote actions and goals) and third party agent frameworks." Its reference guide adds: "We'll soon be seeing not just agents running on one system, but federations of agents." Its open mode already points that way: there, the README says, "the platform is capable of finding novel paths that were not envisioned by developers, and even combining functionality from multiple providers."
Embabel is building that road itself:
@AchievesGoal(export = @Export(remote = true))publishes a goal for remote callers, as an MCP tool.embabel-agent-a2a, an incubating module, serves an application's goals as skills on an A2A agent card.embabel-agent-remote, an experimental module in embabel-agent-experimental, "enables external servers to register actions that are eligible for participation in planning and execution," through a small REST contract.
A2A is common ground today. The AgentSpaces A2A gateway (agentspaces-a2a, experimental) serves a fleet's AgentCards as A2A agent cards. In the other direction, a connector that reads a remote A2A agent's skills or an MCP server's tools could let an Embabel application that exports its goals with @Export(remote = true), or serves them over A2A, join a fleet from outside, with no AgentSpaces code inside it. We have not tried this yet.
AgentSpaces is one more road to the same place, and the shapes are close, though not the same:
- Embabel's remote action metadata carries a name, a description, typed inputs and outputs,
pre,post,cost,value, andcan_rerun. An AgentSpaces card action carries a name, a description, the types it consumes and produces, and a contract ofpre,post, and acostthat is free text. - Embabel's remote server returns its types from
/api/v1/typesasDynamicTypedefinitions (a name, its properties, its parents), so a planner can plan over types it has no class for. Our bridge needs local classes. - Embabel executes a remote action with a synchronous
POST /api/v1/actions/execute. A fleet's call is a leased entry that any qualified worker may take.
A bridge between the two looks within reach. One sketch is a fleet peer that answers /api/v1/actions, /api/v1/types, and /api/v1/actions/execute from its group's cards, in the shape embabel-agent-remote already defines. It is one of the ways to work together.
Embabel Worlds points the same way. It is built on the agent framework, and its realm specification says of a realm's actions: "The host's planner picks them by their declared input / output types and runs them as GOAP actions." A fleet's actions reach an Embabel planner by their declared types too. Typed steps that a planner chains are Embabel's central idea, and the one AgentSpaces was built to carry.
Ways to work together
We would welcome the Embabel team's view, or involvement, in any of these:
- Talk with us. The conversation about AgentSpaces and Embabel is open in Embabel's GitHub Discussions, and Embabel's Discord is where its community meets.
- Run the proof. The integration test
embabel-itbuilds a real Spring Boot 4.1 application with a real Embabel platform and watches GOAP reach a goal through another peer. From the AgentSpaces repository,mvn -Pspring-it -pl integration-tests/embabel-it -am testruns it. It needs no model key. - Read the mapping. The realm site walks the mapping and the worked example, and its mapping page says how an import runs and what each realm part becomes.
- Shape the bridge. A fleet peer that answers
embabel-agent-remote's contract from its group's cards, in the shape that suits Embabel. - Try a world beside a fleet. The SQL door through a Postgres connector is the first path we would try.
- Build the next example. A realm imported into a group, an Embabel agent planning over its types, and an A2UI page for the person who answers its
WaitFor: each piece exists, and no example joins them yet.
Links
Embabel
- Embabel Agent Framework on GitHub, and the release 1.5.4
- The Embabel Agent reference guide, 1.5.4
- Embabel Hub, where you can talk to the docs
- Embabel examples, the Java agent template, and the Kotlin agent template
- Tripper, Embabel's travel planner
- DICE, Domain-Integrated Context Engineering, an incubating Embabel library for knowledge graphs over a typed domain
- Embabel Agent Experimental, home of
embabel-agent-remote - Embabel on GitHub, Embabel on Medium, and Embabel's Discord
- InfoQ: Embabel Agent Framework Reaches 1.0, 2026-08-03
Embabel Worlds
- Embabel Worlds, in early access
- The Worlds guide, its concepts, and its clients
- The realm specification, and its repository embabel-worlds/realm-spec
- The appliance, and the publisher
- Embabel Worlds on GitHub, with its realms, and the Worlds blog
AgentSpaces
- The developer guide: Embabel integration, the fleet's skills as planner actions, data in a fleet: realms and the two worlds, and the four cards
- The realm site: the mapping, an app card from a realm, how an import runs, and the worked example
- The architecture guide and the workflow guide
- The language guides: Python, TypeScript, Ruby, Clojure, Groovy, and Rust
- AgentSpaces on GitHub, Party Bus, and AgentSpaces at Bad Monkey
Appendix: how it works and why
This appendix explains the mechanisms behind the main text: how the extension reads Embabel, how the generated agent is built and kept current, how a remote action finds its space, and what a realm's app card promises.
How the extension reads Embabel
- The extension refers to Embabel's annotations by their fully qualified names (
com.embabel.agent.api.annotation.Agent,Action, andAchievesGoal) and reads their attributes reflectively. An attribute a version lacks reads as absent, so the extension reads whatever attributes the application's Embabel version has. It is tested with 1.5.2, and passes with 1.5.4. - Because it never links against Embabel, the module builds with no Embabel artifact. Its unit tests use small stand-ins for Embabel's annotations and its platform.
- The proof against the real framework is the integration test
embabel-it, which runs Spring Boot 4.1.1 with Embabel 1.5.2 (and passes with 1.5.4) and deploys through Embabel's ownAgentMetadataReader. - A bean that is also an
@AgentSpecor a@SpaceAgenthas chosen the core binder's card, so the Embabel binder skips it rather than publish a second card for it. A bean with only@SpaceTakeor@SpaceNotifybindings is not skipped, which is why a worker action gets two cards under the starter.
The generated agent
- The bridge reads the live set of remote actions: one per action and type pair on every foreign AgentCard whose types resolve to local classes. A card that stops being refreshed ages out of the set by itself.
- It generates one annotated class, so the module never links against Embabel's API. The class is named
RemoteFleetAgentwith a suffix, in the packageai.badmonkey.agentspaces.embabel.generated, annotated@Agentwith the configured name and description. Each remote action becomes a public@Actionmethod, with@AchievesGoalholding the card's goals joined by semicolons. - Every generated method delegates to one interceptor, which runs the remote action and waits for its result:
// RemoteActionInterceptor.java return action.invoke(input, timeout).orElseThrow(() -> new IllegalStateException( "the fleet produced no " + action.outputType().getSimpleName() + " for " + action.name() + " within " + timeout));
- The deployer catches the
AgentPlatformbean as Spring creates it and polls the action set on a virtual thread. It deploys a new generation only when the set changes, keyed on the issuer, the agent, and the input and output types, so a card that is merely published again redeploys nothing. - Deployment goes through Embabel's
AgentMetadataReaderand the platform'sdeploy, the same path an annotated agent takes. To deploy by hand, setauto-deploytofalseand callbridge.deployTo(platform)on your own cadence. Party Bus calls it once its cards are in.
How a remote action finds its space
A remote action writes its input entry into the space the other agent takes from. The registry picks the space in this order:
- an explicit route set with
route(type, space); - the space named on the card's action, when it is a space of this group;
- the card's own space binding for the consumed type;
- the group's only space, when it has exactly one.
Results are awaited in the input's space unless resultsIn(type, space) names another, matching @SpaceTake's own default. The Superfriends planner routes its requests into tasks and reads its dossiers from reports this way.
What a realm's app card promises
The protocol registers realm as an origin system, and an AppCard whose origin.system is realm must carry:
origin.refof<realm>/<app>, where each part matches[A-Za-z0-9._-]+;origin.versionof the realm's own semver, theversionof itsrealm.yml(0.0.0when it names none);origin.attrswithrealm.format(the form read and the Embabel commit the reader follows) andrealm.namespace,realm.digestwhere it can (the SHA-256 of the import document), and optionallyrealm.readsandrealm.commit(the realm's own commit);urlofapp://<realm>/<app>, Embabel's app link;ownerof<realm>, andformatswithtext/htmlfirst for an HTML page, then the namespace.
A reader that relies on a realm origin verifies it in four steps:
- Verify the card as any card: the issuer's signature, an unexpired
ttl, and an issuer that belongs to the group. - Check that the group trusts that issuer to publish imports.
- Check that
ownerequals the first part ofref, thaturlisapp://followed byref, and thatformatsholds the value ofrealm.namespace. - Where it needs the realm's own word, obtain the import document from the realm's owner, check its SHA-256 against
realm.digest, and compare the name, the app entry, the version, the commit, and the namespace.
A mismatch leaves the card an app of its kind with an unverified origin. The protocol never refuses a card for its origin.
While any member of the group reads only older AppCards, the publisher strips origin and formats, so the older reader can still decode the card. Neither field ever moves into a card's spill, so discovery by origin and by format reads a stub as it reads a full card.
Why a realm moves one way
- The realm stays its authors'. They own its meaning, and Embabel owns its format. In Rod Johnson's launch post, "realms can be provided by us, third parties or authored by any user." An import that wrote back would make two sources of truth for one domain.
- Nothing runs unapproved. An import only drafts, so a person sees everything one import proposes before any of it runs in a group.
- Import is repeatable. A second import drafts new versions and changes nothing in force, so a build can import a realm every time it runs.
- Retiring is quiet. When a person retires an app, its issuer stops publishing the card, and the card lapses at its
ttl.