Understanding agent registration

An agent contract is a self-description that an agent publishes about itself. It declares the inputs the agent accepts, the outputs it produces, the tools it uses, the permissions it requires, and the AI models it is compatible with.

The contract is the only thing the orchestrator needs to know about an agent. It does not need access to the agent’s source code, internal logic, or runtime implementation. This separation is deliberate: it means the orchestrator can reason about every registered agent in the same way, regardless of who built it or how it works internally.

For the complete field-by-field schema, see Agent contract specification.

Each agent exposes its contract at a well-known URL: /.well-known/agent.json. This convention means the orchestrator never needs to be told where to find an agent’s description. If the agent is reachable on the network, its contract is reachable too.

Registration itself is driven by a seed process. The seed fetches each agent’s agent.json and upserts the contract into the orchestrator’s agent registry. Running the seed repeatedly with the same contract is safe and produces the same result, so registration is idempotent — re-running it after a contract change updates the registry without creating duplicate entries.

In local development, the seed writes directly to the orchestrator’s database and requires no authentication. Production deployment uses the same conceptual flow with appropriate access controls.

The agent registry is the orchestrator’s lookup table of available agents. When a request arrives, the orchestrator consults the registry to identify which agent — or combination of agents — can satisfy it, validates the request against the agent’s declared inputs and permissions, and routes accordingly.

The registry is what makes the hub-and-spoke architecture work. The orchestrator acts as the hub precisely because it holds the registry; domain agents act as spokes because they are discoverable only through it. See Agent Console architecture for a fuller discussion of how the hub coordinates work across registered agents.

Agent Console could have used a central configuration file maintained by the orchestrator team, listing every agent and what it can do. Contract-driven self-registration was chosen instead for three reasons.

Extensibility. Teams across Storyteq can build and deploy new agents without modifying core orchestrator code. A new agent appears in the registry as soon as it is seeded; the orchestrator did not need to know about it in advance.

Decoupling. The orchestrator depends on what an agent declares, not how it is implemented. Agents can change their internals freely as long as their contract continues to describe their behaviour accurately.

Validation and governance by default. Because every agent declares its permissions and tools up front, the platform can enforce policy at the contract level rather than inspecting every request at runtime. This makes governance a property of the registry, not an afterthought layered on top of it.

The trade-off is that self-description requires discipline. An inaccurate contract — one that overstates what the agent accepts, or understates the permissions it actually needs — leads to routing failures or permission gaps that surface only at request time. The contract is a commitment, not just documentation about the agent.

Registration is a narrow concern. It is helpful to be explicit about what it does not cover:

Keeping these concerns separate from registration is what allows the contract to stay small, stable, and easy to reason about.