Register Plugin Behavior

Use this guide after you define plugin configuration validation and before the plugin installs NeMo Relay runtime behavior.

What You Build

Register a plugin kind, initialize validated configuration, install subscribers or middleware through PluginContext, and clear active plugin configuration during teardown.

Use PluginContext

PluginContext is the component-scoped registration surface that Relay passes to the plugin during initialization. Register subscribers, guardrails, and intercepts through this context instead of through global registration calls in application startup.

The context gives the plugin system three important guarantees:

• The runtime qualifies names for the component instance.
• Relay rolls back partial setup if one registration fails.
• Plugin diagnostics can identify the affected configured component when the plugin includes component in each diagnostic.

Use the context only after validation succeeds. Keep validation deterministic and side-effect free. Inspect configuration and return diagnostics. Create runtime objects and attach them to the context during registration.

Header Plugin Example

The same model applies in every binding: validate component-local config, then install middleware through the component-scoped registration context.

1
from typing import Any
2
3
import nemo_relay
4
5
class HeaderPlugin:
6
    def validate(self, plugin_config: dict[str, Any]) -> list[dict[str, str]]:
7
        diagnostics = []
8
        for field in ("header_name", "value"):
9
            if not isinstance(plugin_config.get(field), str):
10
                diagnostics.append({
11
                    "level": "error",
12
                    "code": "header-plugin.invalid_config",
13
                    "component": "header-plugin",
14
                    "field": field,
15
                    "message": f"{field} must be a string",
16
                })
17
        return diagnostics
18
19
    def register(self, plugin_config: dict[str, Any], context: nemo_relay.plugin.PluginContext):
20
        def add_header(
21
            name: str,
22
            request: nemo_relay.LLMRequest,
23
            annotated: nemo_relay.AnnotatedLLMRequest | None
24
        ) -> nemo_relay.LLMRequestInterceptOutcome:
25
            headers = request.headers.copy()
26
            headers[plugin_config["header_name"]] = plugin_config["value"]
27
            return nemo_relay.LLMRequestInterceptOutcome(
28
                nemo_relay.LLMRequest(headers=headers, content=request.content),
29
                annotated,
30
            )
31
32
        context.register_llm_request_intercept("inject-header", 100, False, add_header)

Activation APIs

After you register the plugin kind, use the plugin APIs in this order. Refer to the Header Plugin Example for the registration pattern:

1. Build a PluginConfig.
2. Validate the config.
3. Initialize the config.
4. Inspect the activation report.
5. Clear active config during teardown when needed.

Register the plugin kind before initialization. With the default unknown_component="warn" policy, validate() reports an enabled unregistered kind as a warning. An error-only check therefore passes, but initialize() raises for an enabled unregistered kind. Register every enabled kind before initialization, or set unknown_component="error" to make validation fail.

validate() checks only the configuration you pass to it. initialize() also layers discovered plugins.toml configuration, so startup can activate or reject components that a preflight report did not include. Refer to Plugin Configuration Files when file discovery participates in deployment.

Append the following entry point to the matching Header Plugin Example above. Each tab relies on that example’s plugin definition and imports. Together, the two blocks register the custom plugin, validate configuration, initialize it, inspect the activation report and available kinds, and clear active configuration:

1
import asyncio
2
3
import nemo_relay
4
5
async def main() -> None:
6
    nemo_relay.plugin.register("header-plugin", HeaderPlugin())
7
8
    config = nemo_relay.plugin.PluginConfig()
9
    config.components = [
10
        nemo_relay.plugin.ComponentSpec(
11
            kind="header-plugin",
12
            config={"header_name": "x-tenant", "value": "tenant-a"},
13
        )
14
    ]
15
16
    report = nemo_relay.plugin.validate(config)
17
    if any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"]):
18
        raise RuntimeError(report["diagnostics"])
19
20
    try:
21
        active_report = await nemo_relay.plugin.initialize(config)
22
        print("Activation report:", active_report)
23
        print("Available kinds:", nemo_relay.plugin.list_kinds())
24
    finally:
25
        nemo_relay.plugin.clear()
26
27
28
if __name__ == "__main__":
29
    asyncio.run(main())

Registration Checklist

Before publishing or sharing a plugin:

1. Validate a correct config and confirm no errors are reported.
2. Validate an intentionally invalid config and confirm diagnostics are actionable.
3. Initialize the plugin and verify the expected subscribers or middleware run.
4. Force one registration failure and confirm partial setup is rolled back.
5. Call clear() to remove active component registrations during teardown. Call deregister() too only when a test or embedded runtime must register the same custom kind again.

Common Issues

Check these symptoms first when the workflow does not behave as expected.

• Middleware names collide: Use component-local names and let the plugin runtime qualify them.
• Partial registrations remain after failure: Register through PluginContext so rollback can clean up.
• Registration does validation work: Move deterministic checks into the validation hook.
• Global state leaks across component instances: Create instance-local state during registration or key shared state by component identity.

Next Steps

Use these links to continue from this workflow into the next related task.

• Add advanced validation and rollout controls with Design Plugin Configuration.
• Review concrete authoring patterns in Code Examples.