What each part becomes
| Realm part | AgentSpaces record in the group |
|---|---|
realm (name, version, commit, namespace) | origin on each app card (below), 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, such as https://acme.example/realm/claims-ops#Claim |
producers of kind remote or api | an AssetCard per operation, from an OpenAPI 3.x and REST connector, configured with the API's location, a credential reference, the operation, the base URL from the document's first server, and the auth scheme |
producers of kind sql | an AssetCard per query, from a SQL connector, configured with the datasource and the query |
producers of any other kind | the AgentCards of a fleet package that serves the agent kind <realm>/<producer>, configured with the producer's fields |
apis | a FlowManifest with one code stage per listed operation, on a lane named after the API; the operation's request schema cues each stage, its parameters are cue fields, and its response schema is the result |
prompts | the group's prompt set, carried as a configuration |
apps | an AppCard with owner the realm, origin realm, formats with the realm's namespace, and the app link app://<realm>/<app> |
A realm imports into one group per import, and creates no group. It names no spaces of its own: the lanes come from the flows its APIs become. A realm ships no code to the fleet either, so a fleet package serves the producer kinds that no connector serves.
The realm's type names become the vocabulary of the fleet. A Claim the realm declares is the shape of the Claim entries agents write into the group's lanes. A flow's stage is cued by a type, and a planner's goal is achieve Payment. The Embabel guide shows an Embabel agent naming its records by the realm's namespace.
An app card from a realm
An AppCard whose origin.system is realm keeps the realm's provenance on the wire. The group's members find a realm's apps by discovery, by origin, and by format. AgentSpaces and Realm (REALM.md in the AgentSpaces specification) ยง5 defines the card, and it is normative with SPEC v0.1.33.
| Field | What it holds |
|---|---|
origin.ref | <realm>/<app> |
origin.version | the realm's own semver, 0.0.0 when the realm names none, and empty for a version of another form |
origin.attrs["realm.format"] | the form the import read and the commit of the Embabel Realm Specification its reader follows, such as yaml@<commit> |
origin.attrs["realm.namespace"] | the realm's namespace, or urn:realm:<realm># when it names none |
origin.attrs["realm.digest"] | the SHA-256 of the import document (SHOULD) |
origin.attrs["realm.reads"], ["realm.commit"] | the type names the app reads, and the commit the realm's files came from (MAY) |
owner | the realm's name |
url | the app link app://<realm>/<app>, which a world that installs the realm serves at /apps/<realm>/<app>.html |
formats | text/html first for an HTML page, then the realm's namespace |
The card constrains no kind, and a reader never refuses a card for its kind or its origin. The issuer signs that the app, the version, the namespace, the commit, and the type names are the import document's own. The card makes no claim that the realm's authors approved the publication.
How an import runs
An import reads one document, the import document. It is a realm folded by hand into one YAML file, with the parts as top-level keys, each OpenAPI document inline under its API, and each agent's prompt file inline under promptText. Its shape follows the legacy YAML form of a realm in the Embabel Realm Specification at commit 89faba6. Two of its keys are its own: commit, the commit the realm's files came from, and namespace, the IRI (RFC 3987) namespace of the realm's types. The worked example shows one.
Embabel now prefers realm.ts, a realm written in TypeScript that a world's host evaluates directly. No tool turns it into YAML yet, so an import cannot read a realm.ts realm today.
- Fold. A person folds the realm's files into one import document, by hand today.
- Import. A person or a script hands the import document to an importer, with the target group.
- Draft. The importer drafts one record per type, producer, API, prompt, and app, and marks each with the realm's name. Its answer carries a report of what it could not use. It never guesses a missing piece.
- Approve. A person reviews what one import proposed, and approves the set the use case needs.
- Serve. The approved records reach the group. The connectors publish
AssetCards, a fleet package's agents publishAgentCards, the reconciler applies theFlowManifests, and members find theAppCards by discovery. - Import again. A second import of the same realm drafts new versions of the same records, and nothing in force changes until a person approves it.
Data moves one way. Nothing writes back into a realm, and what the agents produce stays in the group's spaces.