aspace://realm

AgentSpaces + Embabel + Realm

AgentSpaces runs Embabel agents as a fleet, including agents that draw on an Embabel world and its realms. A realm holds many definitions: agents, the tools they use, and the data they reference. An import takes the set one use case needs and turns those definitions into the fleet's cards: AgentCards, AssetCards, FlowManifests, and AppCards.

AgentSpaces 0.6.0Embabel agentsEmbabel realms
Better togetherThe two worldsThe mappingThe worked example
aspace://realm/together

Better together: AgentSpaces, Embabel, and Realm

Each project does one job, and the jobs fit together:

  • Embabel gives an agent its goals, its typed actions, and a planner that finds the path between them.
  • Embabel Worlds and its realms give a business a picture of itself. A realm teaches a world about one system. It holds many definitions: agents, the tools they use (APIs and their operations), and the data they reference (types, and the producers that fetch each object).
  • AgentSpaces runs agents as a fleet. The peers of a group share typed, leased entries and publish signed cards that say what each one offers.

A use case needs only some of what a realm defines. A claims desk, for example, needs the claim types, the claims API, and the payments ledger. Three steps take that set and deploy it as one fleet:

  1. Your Embabel agents join the fleet. The embabel-agentspaces module publishes each @Agent as an AgentCard. Embabel's planner then plans over the actions of the whole fleet.
  2. An import reads the realm. It drafts one record for each type, producer, API, and app, and marks every draft with the realm's name.
  3. A person approves the set this use case needs. The approved drafts reach the group. The realm's types become the fleet's entry types, its tools and data become AssetCards and AgentCards, its APIs become FlowManifests, and its apps become AppCards.
ONE REALM, ONE USE CASE, ONE FLEETEmbabel's sideAgentSpacesEmbabel agentsyour application's @Agent classesgoals, typed actions, a plannerplans over the fleet's actionsAn Embabel realm: many definitions; a deployment takes a setagentsstay in their worldtoolsAPIs, operationsdatatypes, producersappspages over objectsan import reads the realm and drafts; a person approves the set this use case needsAgentCardyour Embabel agentsAgentCarda fleet packageAssetCarddata at its sourceFlowManifesta flow per APIAppCarda page per appentry typesthe realm's typesembabel-agentspacesAGENTSPACES: ONE GROUP, THE FLEET FOR THIS USE CASEeach issuer signs its card and leases it by its ttl; members find one another by discovery
Better together. Your Embabel agents and the set of a realm's definitions that one use case needs become one fleet's cards. An import drafts from the realm, and a person approves the set. A realm's own agents stay in their world today (dashed).

A platform built on AgentSpaces can then add guardrails, rules, and flows to that fleet.

What works today

Piece Today
An Embabel agent in a fleetWorks. Each @Agent publishes an AgentCard, and an integration test watches Embabel's GOAP planner reach a goal through another peer.
A realm's types, producers, APIs, and apps in a groupWorks, from one import document that holds the realm (how an import runs). An import drafts, a person approves, and the group publishes the cards.
An Embabel agent that plans over a realm's typesEach piece works and has its own test. No example runs the whole chain yet.
A realm's own agentsThey run in their world. An import drafts each agent's prompt file as a prompt, when the import document carries the file.
A fleet beside a running worldNot tried yet. A world's SQL door, through a SQL connector, is the first path we would try.
Who owns whatEmbabel authors and governs the realm format in the Embabel Realm Specification, and that repository's git history versions the format. The realms belong to their authors. An import reads a realm's declared parts and drafts records from them. The AgentSpaces protocol carries the cards and reads no realm itself. The appendix says why the site puts it this way.

For the Embabel side of the story, an agent joining a fleet and the cards it meets there, read the Embabel guide.

aspace://realm/two-worlds

The two worlds, one sentence each

An Embabel realm is a package of meaning. An import reads four of its parts: its types (the domain objects), its producers (how each object is obtained), its APIs (the remote operations the producers call), and its apps (pages over the objects). It also reads each agent's prompt file as a prompt. An AgentSpaces group is a package of operation: its spaces (lanes of typed entries agents write and take), its cards (what each agent, asset, model, and app advertises), and its flows (stages over the lanes).

A realm imports into a group, and nothing a realm proposes runs before a person approves it. Data moves one way, from the realm into the group, and nothing writes back into a realm.

An Embabel realm: meaningrealm.ymlname, version, url, descriptiontypes/the domain objectsproducers/how each object is obtainedapis/the remote operationsapps/pages over the objectsagents/each agent's prompt fileAn AgentSpaces group: operationgroupone group per importentry typesthe type IRIs under the namespaceAssetCards, AgentCardswhat serves each producerFlowManifestsa code stage per operationAppCardsorigin realm, found by discoveryprompt setcarried as a configurationimports intotypes name the entriesan AssetCard or AgentCarda FlowManifest per APIan AppCard eachthe group's prompt setrealm → group, never backThe realm says what the objects are and where they come from; the group says who works on them and how.An import drafts a record for each part and marks it with the realm's name; a person approves what runs.
Two worlds. A realm is a package of meaning, a group a package of operation; a realm imports into a group, and nothing runs before a person approves it.

meaning

A realm answers what are the objects and where do they come from. It knows nothing of peers, leases, takes, or who is on duty.

operation

A group answers who works on the objects and how. It knows nothing of a producer's SQL or an API's token until a configuration tells one of its agents.

the seam

An import joins the two. It reads the realm, drafts what the group will need, and carries what a person approves into the group.

the vocabulary

The realm's type names become the vocabulary of the fleet: the entries in the lanes, the cues of the flows, and the goals of the planner.

The rest of the site: the mapping (what each part becomes, the app card a realm app gets, and how an import runs) and the worked example (the claims-ops realm, end to end). This site reads the Embabel Realm Specification at commit 89faba6. Its AgentSpaces account is AgentSpaces and Realm (REALM.md in the AgentSpaces specification).

aspace://realm/appendix

Appendix: how it works and why

The main text says what happens. This appendix says how, and why.

How a definition becomes a card

Each card has one issuer. The issuer signs the card and leases it by its ttl, and a reader decides what to allow from what the card claims.

Definition Who publishes the card What the card says
an Embabel application's @Agentthe agent's own peer, through embabel-agentspacesits actions, with Embabel's pre, post, and cost, and its goals
a realm's remote, api, or sql producera REST or SQL connector, once a person approves its configurationan AssetCard per operation or query, with its shape; the data stays at its source
a producer of any other kindthe agents of a fleet package that serves the agent kind <realm>/<producer>the package's own AgentCards and actions
a realm's APIno card: the group's reconciler applies the FlowManifest once a person approves ita code stage per listed operation, on a lane named after the API
a realm's appthe issuer that ran the import, once a person approves the appan AppCard with origin realm and the realm's namespace in formats

Why a person approves the set

A realm proposes what a group could do: which operations to call with which credential, which database to query, which pages to serve. A person approves each proposal before it runs, as for a configuration typed by hand. That is also how a deployment takes only the set its use case needs.

The approval governs the fleet alone. It grants nothing inside a world, where the world's owner makes every approval.

Why the site says an import reads realms

Embabel authors and governs the realm format, and Embabel decides what its specification contains. The specification's notice lets anyone build applications, tools, agents, or services that read realms. It asks a vendor for a written agreement before implementing the specification in an engine or a platform.

AgentSpaces does not implement Embabel's specification. An import reads a realm's declared parts and drafts records from them. The site makes no compatibility or conformance claim for it.

Why one document

A realm on disk is many files: realm.yml, the types, the producers, the APIs with an OpenAPI file each, and the apps. One document makes the import one request and one report. It also gives the import one digest, which every app card the import makes records as realm.digest.