Federation for Agent Networks: Cross-Namespace Capability Sharing via Realms

May 13, 2026

Discovery lets ensembles find capabilities within a network. But in a real deployment, not every ensemble lives in the same namespace or even the same cluster. A hotel chain might run separate ensemble networks at each property, each in its own Kubernetes namespace, but want them to share spare capacity when one property is overloaded.

This is the federation problem: how do you extend capability discovery across trust and network boundaries without collapsing everything into one flat namespace?

Realms as trust boundaries

AgentEnsemble v3.0.0 introduces realms as the organizational unit for federation. A realm is a namespace-level discovery and trust boundary — typically mapping to a Kubernetes namespace in production deployments.

FederationConfig federation = FederationConfig.builder()
    .localRealm("hotel-downtown")
    .federationName("Hotel Chain")
    .realm("hotel-airport", "hotel-airport-ns")
    .realm("hotel-beach", "hotel-beach-ns")
    .build();

Within a realm, ensembles discover each other freely. Cross-realm discovery requires explicit opt-in: an ensemble must advertise its capacity as shareable for other realms to use it.

Capacity advertisement

Ensembles periodically broadcast their current load and availability. The shareable flag is the federation gate — when true, spare capacity is available to other realms.

The routing hierarchy

Priority	Scope	Condition
1 (highest)	Local realm	Provider is in the same realm
2	Same realm (unregistered)	Provider has no realm info (assumed local)
3 (lowest)	Cross-realm	Provider is in a different realm and `shareable = true`

Within each level, the least-loaded provider is preferred. The hierarchy encodes a simple principle: prefer local providers, fall back to cross-realm when local capacity is insufficient.

The design principle

Federation is a capacity-sharing problem, not a networking problem. The networking already works across boundaries. What federation adds is a policy layer: who can use whose spare capacity, and in what order.

Realms provide the organizational unit. Capacity advertisement provides the data. The routing hierarchy provides the policy. Together, they turn independent agent networks into a cooperative federation that shares spare capacity while maintaining operational independence.

Federation is part of AgentEnsemble. The federation guide covers the full API including capacity advertisement and realm configuration.