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:
- Your Embabel agents join the fleet. The
embabel-agentspacesmodule publishes each@Agentas anAgentCard. Embabel's planner then plans over the actions of the whole fleet. - 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.
- 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 andAgentCards, its APIs becomeFlowManifests, and its apps becomeAppCards.
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 fleet | Works. 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 group | Works, 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 types | Each piece works and has its own test. No example runs the whole chain yet. |
| A realm's own agents | They 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 world | Not tried yet. A world's SQL door, through a SQL connector, is the first path we would try. |
For the Embabel side of the story, an agent joining a fleet and the cards it meets there, read the Embabel guide.
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.
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).
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 @Agent | the agent's own peer, through embabel-agentspaces | its actions, with Embabel's pre, post, and cost, and its goals |
a realm's remote, api, or sql producer | a REST or SQL connector, once a person approves its configuration | an AssetCard per operation or query, with its shape; the data stays at its source |
| a producer of any other kind | the agents of a fleet package that serves the agent kind <realm>/<producer> | the package's own AgentCards and actions |
| a realm's API | no card: the group's reconciler applies the FlowManifest once a person approves it | a code stage per listed operation, on a lane named after the API |
| a realm's app | the issuer that ran the import, once a person approves the app | an 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.