What is a capability in UMA?

The short answer

In UMA, a capability is the actionable shape of a service. It tells the runtime what this piece of the system can do, what it expects, what it produces, and under which conditions it should be considered valid. That makes it more useful than a vague service label and more durable than a one-off function call buried inside a stack-specific implementation.

This is why capabilities matter so much once the system becomes dynamic. A runtime cannot compose a workflow out of loosely described code. It needs visible units with clear meaning. Capabilities are those units.

The portability goal here is not “write once, run everywhere.” It is “write once, run where it makes sense,” with capabilities giving the runtime concrete units to evaluate.

• Capability: a discoverable unit of behavior the runtime can reason about.
• Workflow: a runtime-approved sequence of capabilities used to satisfy a goal.
• Runtime: the layer that validates which capabilities can actually participate.

Why UMA uses capabilities instead of only services

The word service is useful, but it can stay too broad. It often tells you that some behavior exists without telling you what the runtime can do with it. A capability is more specific. It expresses the part of the service that is operationally meaningful for discovery, selection, compatibility checking, and composition.

That distinction becomes important as soon as the system supports more than one possible path to the same outcome. If the runtime must decide whether to summarize, translate, enrich, format, reject, or adapt, it needs a unit more precise than “we have a service for that.” It needs something it can compare and govern. That is what a capability provides.

This also works better when the underlying service is portable in a disciplined way. A runtime can govern a capability much more cleanly when the service behavior is deterministic enough to remain stable across hosts and explicit enough to preserve one visible contract.

What makes something a capability

A capability is not defined only by where it runs or which team owns it. It is defined by whether the runtime can treat it as a clear architectural unit. That usually means four things are visible: the behavior it offers, the input it expects, the output it produces, and the conditions under which it is allowed to participate.

Without those elements, the runtime is left inferring too much. The system may still work, but it becomes harder to discover, validate, or explain why one path was chosen over another. UMA uses capabilities to keep that ambiguity low.

Capability versus workflow

A capability is not the same thing as a workflow. A capability is one participant. A workflow is the approved path the runtime builds from one or more capabilities to satisfy a goal. Mixing those two ideas makes dynamic systems harder to understand because the unit of behavior and the unit of orchestration stop being separate.

UMA keeps them distinct on purpose. The capability stays reusable and inspectable. The workflow stays explainable as a composition of capabilities rather than a hidden chain of internal calls.

Capability versus agent

This is another useful distinction. An agent can help interpret the goal and propose which capabilities might fit. But the capability is still the unit of work the runtime validates and selects. Agents help with reasoning. Capabilities are the architectural units being reasoned about.

That is one reason the capability model matters even more in AI-assisted systems. If the planning layer is dynamic, the units being planned must become clearer, not less clear. Otherwise the runtime ends up evaluating suggestions that are too vague to govern properly.

Why this matters for runtime authority

The runtime cannot remain authoritative if the units of work are fuzzy. It can only approve or reject what is visible enough to inspect. Capabilities give the runtime something concrete to reason about: what behavior is being requested, what contract it implies, what placement it requires, and whether the current environment should allow it.

This is the bridge between the conceptual pages on the site and the reference app. The app is not just showing boxes and arrows. It is showing a runtime making decisions over capabilities rather than blindly following a hardwired script.

A concrete proof point

The easiest proof is to watch one workflow in the reference app. You can see which capabilities are available, which one is proposed or selected, and where the runtime keeps authority over the final path. That is much clearer than treating capabilities as another naming convention for services.

What a capability is not

• It is not every function or class in the codebase.
• It is not the same thing as a deployable service boundary.
• It is not the workflow itself.
• It is not a synonym for “tool” with no contract or runtime context.
• It is not just an AI agent prompt with a nice name attached.

A practical design test

If you are unsure whether something in your system is a capability, ask two questions. First: can the runtime understand what this unit does and when it is valid? Second: can it be selected or rejected as part of a larger workflow without reading hidden implementation details? If both answers are yes, you are probably looking at a capability rather than just an internal implementation detail.

If the answers are no, the unit may still be useful code, but it is not yet expressed clearly enough for governed runtime composition.

Why capabilities make the architecture easier to learn

Capabilities give the reader a stable mental unit. Instead of thinking in terms of full applications, hidden helpers, or stack-specific modules, the reader can ask simpler questions: what capabilities exist, what goal is being satisfied, which capability was chosen, and why did the runtime approve that path? That makes the system easier to understand without reducing it to simplistic diagrams.

It also helps teams talk about architecture with more precision. “This workflow needs translation after summarization” is clearer than “the app calls some translation code after it does the other thing.” The capability model creates that clarity.

Frequently asked questions

Is a capability the same as a microservice?

Not necessarily. A microservice is often described as a deployable unit. A capability is the unit the runtime can discover, validate, and compose. Sometimes those ideas overlap. Often they do not.

Can one service expose more than one capability?

Yes. One service boundary can expose multiple meaningful capabilities, especially if the runtime needs to distinguish between different kinds of behavior that should be validated or composed separately.

Do capabilities only matter in dynamic or AI-driven systems?

No. They matter even in simpler systems because they make the service behavior more visible. Dynamic planning just makes the need for them more obvious.