Embabel guide

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.

Embabel Agent Framework 1.5, pinned at 1.5.2 and also passing on 1.5.4Embabel Worlds in early accessAgentSpaces 0.6.0four signed, leased cardsno broker
aspace://guide/embabel/together

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, and cost onto 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. pre and post on @Action name further conditions, which @Condition methods evaluate, and an action may name a cost and a value.
  • 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.
Note. In this guide "realm" always means a realm of Embabel Worlds.
Note. "Agent" means three things here: an Embabel @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

THREE PROJECTS, EACH WITH ITS OWN JOBEmbabel's sideAgentSpacesEmbabel Agent Frameworkan agent's goals, actions, and plans@Agent, @Action, @AchievesGoalconditions from types; pre, post, costGOAP, Utility AI, Hybrid, Supervisora typed domain model in plain codethe AgentPlatform runs and deploys agentsEmbabel Worlds and its realmsa context layer, built on the agent frameworka world: a governed, living knowledge grapha realm: how a world learns a systemtypes, sources, APIs, apps, and moreVirtual Cypher, views, agents, appsdoors: MCP, REST, SQL, OpenAI-compatiblecards outfleet actions inembabel-agentspacesa realm, imported one wayan import drafts; a person approvesAgentSpaces: a fleet of peers, with no brokergroups of peerseach peer signs what it writesspaces of entriestyped, leased, replicatedfour signed cardsagent, asset, model, appremote actionstyped steps planners chainWhat all three share: typed domain objects. A realm's type, an Embabel record, and a fleet'sentry can carry one name; in a fleet an import makes it an IRI such as https://acme.example/realm/claims-ops#Claim
Three projects, each with its own job. Embabel's framework gives an agent its goals and plans, and Embabel Worlds gives a business its meaning. AgentSpaces carries both across a fleet: the extension in both directions, a realm one way through an import a person approves.
Embabel Agent FrameworkEmbabel Worlds and its realmsAgentSpaces
Answershow 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?
Unitan @Agent and its actionsa world, extended by realmsa group of peers and its spaces
Statethe blackboard of an agent processthe world's knowledge graphleased entries every member replicates
Reached throughthe AgentPlatform, and goals exported over MCPMCP, REST, SQL, GraphQL, OData, webhooks, an OpenAI-compatible modelsigned 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-agent project, 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.
aspace://guide/embabel/two-worlds

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.

WHAT AN IMPORT READSthe parts of a realm it understandsAN IMPORTdrafts the parts; a person approvesA GROUPwho works on the objects, and howrealm.ymlname, version (semver), urlorigin + namespace IRIrealm:<name>; the IRI is oursorigin and namespaceon app cards and typestypes/types, properties, parentstype draftsnamed by the namespaceentry typesnamespace + name: an IRIproducers/remote, api, sqlconnector draftsfor REST and SQL connectorsAssetCardsone per operation or queryproducers/compute, vector, jar, and othersconfig draftsfor <realm>/<producer>AgentCardsif a fleet package serves itapis/OpenAPI documentsflow draftsrealm-<realm>-<api>a FlowManifesta stage per operationapps/pages over the objectsapp draftsrealm-<realm>-<app>AppCardsorigin realm, formatsprompts/examples.md for a world's chatprompt draftsorigin realm:<name>the prompt setcarried as a configurationOne way import to down-select what goes to the fleet. Configurations, flows, prompts, and apps waitfor a person's approval. AgentSpaces itself reads no realm: the group gets entry types and cards.
A realm and a group. An import turns each part of a realm into a draft, and each approved draft becomes something the group runs on. The realm stays the source of meaning.

Who owns what

ConcernThe realm's authors own, in Embabel's formatAgentSpaces owns
Typesnames, descriptions, properties (an identity property among them), parents, spines, and the realm's own labelentry type IRIs, as data it never interprets
Producersthe kind, and the operation, query, or other source it readsthe AssetCard a connector publishes for what it serves
APIsthe OpenAPI documents and the operations they allowthe FlowManifest a group's reconciler applies
Appsthe pages and their titlesthe AppCard: kind, shape, origin, formats, ui, host
Promptsprompt contributions, such as examples.md for a world's chatnothing
The formatnothing: Embabel owns its structure, realm.ts and the legacy YAMLthe 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 partWhat reaches the group
realm (name, version, commit, namespace)origin on each app card, and the namespace of every entry type IRI
typesentries whose schema name is the type's IRI, the namespace followed by the type name
producers of kind remote or apian AssetCard per operation, from an OpenAPI 3.x and REST connector
producers of kind sqlan AssetCard per query, from a SQL connector
producers of any other kindthe AgentCards of a fleet package that serves the agent kind <realm>/<producer>
apisa FlowManifest with one code stage per listed operation, on a lane named after the API
promptsthe group's prompt set, carried as a configuration
appsan 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 SchemaRegistry bean, 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.
aspace://guide/embabel/agent

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

DependencyVersion
ai.badmonkey.agentspaces:agentspaces-spring-boot-starter0.6.0
ai.badmonkey.agentspaces:embabel-agentspaces0.6.0
com.embabel.agent:embabel-agent-starter, for an application that plans1.5.2 in our integration test
com.embabel.agent:embabel-agent-api, for an application that only advertises1.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 @Agent by 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");
    }
}
  • @Action makes bake a step Embabel's planner can use, and @AchievesGoal says its result is a goal.
  • @SpaceTake makes the same method a worker. It takes one Order under a 15-second lease and writes back the Cupcake it 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 both embabelBaker_Order and baker_Order, and an @Agent with 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.groups and builds its spaces.
  • agentspaces.embabel configures the extension. Here the generated agent is partyBusFleet, and each fleet action waits up to 60 seconds for its result.
  • remote-actions-enabled: false makes 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 only embabel-agent-api.
  • embabel.models.default-llm is 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 @Agent name. 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 @Agent description.
  • Each @AchievesGoal description becomes one of the card's goals.
  • Each @Action becomes a card action of kind embabel-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-action as invocable, so it becomes a remote action on their side. It is answered only when something takes from its space: @SpaceTake or @SpaceNotify on 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.
  • costHints carries framework=embabel, so a reader can tell where the card came from. The ttl is 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 cost and value as ZeroToOne, from 0 to 1, so a real action would say something like cost = 0.2.
  • The card carries cost as 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.

ONE PLAN, TWO PEERS: THE SUPERFRIENDS HALL PLANNEREmbabel's sideAgentSpacesopenawaitDecisioncommissionreport_ReportRequestbriefVerdictGOAP chains five typed actions to the goal: four are the local agent's own, and report_ReportRequest is another peer's skill.YOUR EMBABEL APPLICATION (ONE PEER)THE GROUPANOTHER PEERHallPlanner (@Agent) on the platformopen, awaitDecision, commission, brief;the seat's agent: platform.createAgentover every deployed actionspaces hold typed entriesunder leases; every memberreplicates themany peer of the group, inany language AgentSpacesspeaksremoteFleet (generated @Agent)report_ReportRequest(ReportRequest) returns a Dossier, backed by another peer's cardspace tasksReportRequest, leasedspace reportsDossierreport service@SpaceTake on a methodthat takes a ReportRequestand returns a Dossier1234EmbabelBinderpublishes hall-planner's AgentCardad cacheevery peer's cardsits AgentCardReportRequest in, Dossier out51 the generated action writes a leased ReportRequest; 2 the worker takes it under a lease; 3 it writes the Dossier;4 the result returns to the plan; 5 the ad cache's cards become the generated agent's actions. A crashed worker's request comes back.
One plan, two peers. The planner sees the fleet's skill as one more typed action. Under it, the step is a leased round trip through two spaces, so a crashed worker hands the request on.

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 AgentPlatform through Embabel's own AgentMetadataReader, 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");
  • @AgentSpec and @SpaceTake are 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 -Pembabel profile, 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.embabelDefaultMeaning
remote-actions-enabledtruebuilds the bridge from the fleet's cards to a generated agent
auto-deploytruedeploys the generated agent onto the application's AgentPlatform bean
deploy-poll-millis2000how often the deployer looks for a changed set of actions
remote-action-timeout-millis30000how long a generated action waits for its result
remote-agent-nameremoteFleetthe generated agent's name on the platform
remote-agent-descriptionCapabilities other fleet members advertise through AgentCardsits 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 @Agent whose @Action also carries @SpaceTake gets 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 @Action without @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 EmbabelRemoteActions bean 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 OperationContext cannot carry @SpaceTake. Keep the worker method to its one entry, and keep the actions that use the context as plain @Action methods.
  • 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 ui and 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, which embabel-agent-remote uses, 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 @Action carries the card's types and goals, but no description, pre, post, or cost. Embabel's planner therefore sees every fleet action at cost 0, with only its type conditions. Our card's cost is 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 cost but not value, costMethod, valueMethod, canRerun, or readOnly. Utility AI planning, which weighs value, sees none of it for a fleet action.
  • Annotated agents only. The binder reads @Agent classes and their @Action and @AchievesGoal methods. Actions on @EmbabelComponent classes, @State classes, Kotlin DSL agents, and agents deployed by code are not carded, and @Condition methods stay local. Reading the platform's own agent model (AgentPlatform.agents()) would cover them all.
aspace://guide/embabel/cards

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.

WHAT EMBABEL AND A REALM BRING, AND THE CARD EACH BECOMESEmbabel's sideAgentSpaces@Agent, @AchievesGoalname, description, goals@Actiontypes in and out; pre, post, costa realm producer no connector servesa configuration a fleet package may servethe model an action usesembabel.models, an LLM servicea realm producer: remote, api, sqlan API operation or a querya realm appa page over the realm's typesa page an agent drawsA2UI, through a Surfaces penAgentCardgoals, consumes, produces, spaceBindingsactions: kind embabel-action, a contractISSUED BY EmbabelBinder, on the agent's peerModelCardname, tasks, engine, residency, serversthe gateway routes model requestsISSUED BY its admitter; a model serverAssetCardasset, uri, shape, freshness, accessdata stays at its sourceISSUED BY a shipped connector peerAppCardkind, shape, origin, formats, ui, hostpeople use it; members find itISSUED BY an import's issuer; an app hostthrough the fleet:designed, not yet testedEvery card is signed by its issuer, leased by its ttl, and gossiped into the ad cache of every peer in the group.
The four cards, seen from Embabel. Warm boxes come from Embabel or from a realm. The AgentCard comes straight from your annotations; the other three come from whoever admits a model, a connector, an import, or an app host.
CardIn Embabel's termsWho issues itWhere it is defined
AgentCardan @Agent: its description, its goals, and each @Action with its types and its pre, post, and costthe extension's binder, on the agent's own peeryour annotations, read by EmbabelBinder
ModelCardan 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 tothe party that admits the model, or a model server for itselfModelCard in agentspaces-api, filled in by its issuer
AssetCardwhat a realm's remote, api, and sql producers serve, through a shipped connectorthe connector peer that holds the sourcea connector's AssetProvider
AppCarda realm's app, with origin realm, or a page an agent draws with A2UIthe issuer that ran the import, or the app host for a Publisha 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 EmbabelOnto the AgentCard
@Agent(name); when blank, Embabel uses the simple class name and the extension the decapitalized onethe 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 methodone entry of actions, kind embabel-action, at most 64
@Action(description)that action's description
the action's domain parameter and return typesconsumes and produces, for the action and for the card
@Action(pre, post, cost)that action's contract
@SpaceTake or @SpaceNotify on the actionspaceBindings, 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 ModelRequest into the group's model-requests space, 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. FleetChatModel is a Spring AI ChatModel whose provider is the fleet. Embabel uses Spring AI as its default LLM connector, behind its own LlmMessageSender abstraction, and its SpringAiLlmService wraps any Spring AI ChatModel. So an Embabel application that adds agentspaces-springai can wrap FleetChatModel in SpringAiLlmService, 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 LlmMessageSender interface 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's model-requests space 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 remote or api becomes an AssetCard per operation, from an OpenAPI and REST connector;
  • a producer of kind sql becomes 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 GET operation 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 shape names 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 sql producers 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:

  • kind says how the app connects. It is a closed set: peer, fed, gateway, or assembled.
  • origin names the external system the app came from, such as realm, and the app's id there. It is open.
  • formats lists the media types and vocabulary IRIs the app reads or renders, such as text/html and 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 APPAN AGENT'S A2UI PAGEapps/claims-desk.htmlan app of the claims-ops realmimported; a person approves itAppCard realm-claims-ops-claims-deskkind fed, shape staticowner claims-opsorigin realm, claims-ops/claims-deskformats text/html, https://acme.example/realm/claims-ops#url app://claims-ops/claims-deskmembers find it by discoveryAny member of the groupcard.fromOrigin("realm", "claims-ops/*") every app of one realmcard.handles(<the realm's namespace>) every app that speaks its typesAn agent with a Surfaces penwrites createSurface, updateComponents,updateDataModel; reads actions backSurface entriesSurfaceActionspace viewsin the groupapp hostserves the pagesa person's browserthe host's renderer draws ita person actsserves ita Publish sets hostAppCard (shape a2ui)ui: a2ui v0.9.1, the catalogs, the drawing agent, its pageshost: url, signOn idp or noneAn agent draws a page, and a host serves it. Members find every app by discovery, by origin, and by format.
Two ways to an AppCard. A realm's app arrives through an import and keeps its origin. An agent's A2UI page is drawn as data, served by the group's app host, and answered as entries.

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:

FieldValue
ownerclaims-ops
originsystem realm, ref claims-ops/claims-desk, version 0.2.0, the realm's own semver
origin.attrsrealm.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
urlapp://claims-ops/claims-desk, Embabel's app link
formatstext/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 with card.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.commit and realm.digest.
  • An import writes kind fed today. 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's url stays 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;
}
  • Surfaces is a plain helper over a Space. 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) and agentspaces-widgets (ChatInput, FileShare, ApprovalCard, and TimelineStrip). A host adds its own catalogs beside them.
  • publish(...) writes a Publish entry into the views space. The app host serves the pages and fills the card's host: the address people open, and signOn of idp (the default) or none.
  • 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.

aspace://guide/embabel/walkthrough

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.

FROM A REALM TO A RUNNING GROUP: THE CLAIMS-OPS EXAMPLEEmbabel's sideAgentSpaces1A realmclaims-ops: three types,four producers, an API,and two apps2An importdrafts one recordper part, markedwith the realm's name3Approvea person approvesthe set this usecase needs4The groupentry types, AssetCards,a FlowManifest,and AppCardsTHEN AN EMBABEL AGENT WORKS ON THE SAME NAMESa SchemaRegistry beanmaps com.acme.claims tohttps://acme.example/realm/claims-ops#its @Action typesClaim, Payment: the realm'stypes, named by IRI on its cardits goalan @AchievesGoal that returnsa realm type, reached via the fleet
A realm in a running fleet. An import drafts, a person approves, and the group gets entry types and cards. An Embabel planner then works on the same names.

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, and Payment, each named by the namespace https://acme.example/realm/claims-ops#;
  • AssetCards for the operations listClaims and getPayment, from a REST connector, and one for the paymentsLedger query, 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 stages listClaims and getPayment. The API's operation-ids, in Embabel's words an "Exact operationId allowlist," leaves out orderPayment;
  • two AppCards, for the apps claims-desk and ledger-view;
  • the prompt claims-ops/triage, from the triage agent'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:

  1. Name your records by the realm's namespace. Declare a SchemaRegistry bean that maps your domain package, for example com.acme.claims, to https://acme.example/realm/claims-ops#, as in the vocabulary section. Your Claim record is then https://acme.example/realm/claims-ops#Claim on the wire and on your card.
  2. 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.
  3. Make a realm type your goal. An @AchievesGoal action that returns a Payment, 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 through platform.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.

aspace://guide/embabel/further

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:

A FLEET BESIDE A RUNNING WORLD: PATHS NOT YET TRIEDEmbabel's sideAgentSpacesA RUNNING WORLDEmbabel Worlds, on its applianceA FLEETAgentSpaces peers in one groupthe SQL doorPostgres wire; views as tablesa Postgres connectoran AssetCard per queryPostgres wire protocolthe model doorthe world answers as a modelan Embabel actionits world as its LLMOpenAI-compatible APIthe MCP doorthe world's toolsan MCP connectortools as cards, resources as assetsMCPa world-served app/apps/<scope>/<name>an AppCardlinks to the app as it isa linka new realminstalled from the app's URLa fleet servicewith a publisher libraryRealm Publishing ProtocolEvery path is untried. Each door signs in with the credentials its client sent ("Your login is forwarded,never held"), so a client reads only what its user may read.
A fleet beside a running world. Each path uses a door a world already opens or a kind of connector a fleet already has. None has been tried yet, so every arrow is dashed.
  • 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, and can_rerun. An AgentSpaces card action carries a name, a description, the types it consumes and produces, and a contract of pre, post, and a cost that is free text.
  • Embabel's remote server returns its types from /api/v1/types as DynamicType definitions (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-it builds 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 test runs 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.
aspace://guide/embabel/appendix

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, and AchievesGoal) 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 own AgentMetadataReader.
  • A bean that is also an @AgentSpec or a @SpaceAgent has chosen the core binder's card, so the Embabel binder skips it rather than publish a second card for it. A bean with only @SpaceTake or @SpaceNotify bindings 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 RemoteFleetAgent with a suffix, in the package ai.badmonkey.agentspaces.embabel.generated, annotated @Agent with the configured name and description. Each remote action becomes a public @Action method, with @AchievesGoal holding 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 AgentPlatform bean 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 AgentMetadataReader and the platform's deploy, the same path an annotated agent takes. To deploy by hand, set auto-deploy to false and call bridge.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:

  1. an explicit route set with route(type, space);
  2. the space named on the card's action, when it is a space of this group;
  3. the card's own space binding for the consumed type;
  4. 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.ref of <realm>/<app>, where each part matches [A-Za-z0-9._-]+;
  • origin.version of the realm's own semver, the version of its realm.yml (0.0.0 when it names none);
  • origin.attrs with realm.format (the form read and the Embabel commit the reader follows) and realm.namespace, realm.digest where it can (the SHA-256 of the import document), and optionally realm.reads and realm.commit (the realm's own commit);
  • url of app://<realm>/<app>, Embabel's app link;
  • owner of <realm>, and formats with text/html first for an HTML page, then the namespace.

A reader that relies on a realm origin verifies it in four steps:

  1. Verify the card as any card: the issuer's signature, an unexpired ttl, and an issuer that belongs to the group.
  2. Check that the group trusts that issuer to publish imports.
  3. Check that owner equals the first part of ref, that url is app:// followed by ref, and that formats holds the value of realm.namespace.
  4. 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.