This page explains how plugins package reusable runtime behavior behind configuration.
Plugins let NeMo Relay install reusable runtime behavior from configuration instead of requiring every application or framework integration to register the same middleware and subscribers by hand.
They are the main packaging layer for reusable runtime components.
The canonical plugin document has three main areas:
versioncomponentspolicyThe version identifies the configuration format expected by the plugin system.
Components describe the individual runtime pieces to activate. Each component declares what it is and which config it should use.
Policy controls how strictly the plugin system interprets unknown fields, unsupported values, or compatibility issues.
Plugins follow a small lifecycle rather than registering everything blindly.
Validation checks whether the supplied config is structurally and semantically acceptable before initialization.
Initialization activates the configured components and registers their runtime behavior.
Reporting provides structured diagnostics about what activated successfully and what did not.
The plugin context is the runtime surface that a component uses to register its behavior. This is where plugins connect configuration to real runtime state.
Depending on the component, a plugin can register:
This is what makes plugins a packaging mechanism rather than a separate runtime model. Plugins do not replace scopes, middleware, or subscribers. They install them.
Plugin initialization is process-level. It is intended for runtime components that should activate once for the running process rather than once per request.
Scope-local behavior still matters after plugin installation, but the plugin system itself is a global activation layer.
Core plugin APIs register built-in components before lookup, validation, and initialization. Applications can still register custom plugins, but first-party components are available by kind without an explicit registration call.
Adaptive is implemented as a built-in plugin component. It is not a separate runtime model. It uses the same plugin system as custom components.
This matters conceptually because adaptive behavior is configured and activated through the same component lifecycle as other plugins:
Detailed adaptive configuration belongs in Adaptive Configuration, Adaptive Cache Governor (ACG), and Adaptive Hints.
The core crate ships a built-in observability plugin component for Agent
Trajectory Observability Format (ATOF), Agent Trajectory Interchange Format
(ATIF), OpenTelemetry, and OpenInference exporters. Each exporter section is
disabled unless its section sets enabled: true, and subscriber names are
inferred from the plugin namespace instead of exposed in public config.
Detailed observability plugin configuration belongs in Observability Configuration.
The core crate also ships a built-in nemo_guardrails plugin component. It is
the first-party Guardrails integration point that NeMo Relay owns through the
shared plugin system.
The current shipped user-facing lane is the remote backend. It gives NeMo Relay one canonical plugin kind and config shape for Guardrails-backed managed LLM and tool checks while broader backend parity work remains separate.
Detailed Guardrails plugin configuration belongs in NeMo Guardrails Configuration.
For the CLI gateway’s plugins.toml discovery, precedence, merge, and editing
rules, see Plugin Configuration Files.
Use these practices when applying the concept in application or integration code.