Adaptive Configuration

Use this page when you want to configure the built-in Adaptive plugin component as a whole. The component kind is adaptive.

Adaptive plugin configuration uses the generic NeMo Relay plugin document shape. Canonical plugin documents and plugins.toml use snake_case. Binding helpers can use language-native names and serialize them to canonical keys.

For plugin file discovery, precedence, merge behavior, editor controls, and gateway conflict rules, refer to Plugin Configuration Files.

Component Shape

The top-level adaptive object contains:

Dedicated pages cover Adaptive Cache Governor (ACG), Adaptive Hints, and Response Cache. State, telemetry, tool parallelism, and policy remain whole-plugin settings:

• Use state.backend.kind = "in_memory" for local experiments.
• Use Redis state when learned state must survive restarts or be shared across workers.
• Enable telemetry when adaptive learners should consume runtime events.
• Keep tool_parallelism.mode = "observe_only" until scheduling behavior has been validated.
• Keep policy.unsupported_value = "error" for rollout safety.

plugins.toml Example

Add the following whole-plugin Adaptive configuration to plugins.toml:

1
version = 1
2
3
[[components]]
4
kind = "adaptive"
5
enabled = true
6
7
[components.config]
8
version = 1
9
agent_id = "planner"
10
11
[components.config.state.backend]
12
kind = "in_memory"
13
14
[components.config.telemetry]
15
subscriber_name = "adaptive.telemetry"
16
learners = ["tool_parallelism"]
17
18
[components.config.tool_parallelism]
19
mode = "observe_only"
20
priority = 100
21
22
[components.config.adaptive_hints]
23
priority = 100
24
break_chain = false
25
inject_header = true
26
inject_body_path = "nvext.agent_hints"
27
28
[components.config.acg]
29
provider = "passthrough"
30
observation_window = 100
31
priority = 50
32
33
[components.config.acg.stability_thresholds]
34
stable_threshold = 0.95
35
semi_stable_threshold = 0.50
36
min_observations_for_full_confidence = 20
37
38
[components.config.policy]
39
unknown_component = "warn"
40
unknown_field = "warn"
41
unsupported_value = "error"

This configuration activates adaptive telemetry, keeps tool parallelism observational, injects adaptive hints, and leaves ACG in passthrough mode so requests can be observed without provider-specific cache translation.

Per-Language Plugin Configuration

The following examples configure and activate the Adaptive component through a language binding:

validate() resolves the same configuration layers as initialize() without loading plugin code or acquiring the activation lease. Use Python/Rust validate_exact(), Node.js validateExact(), or Go ValidateExact() when only the supplied static configuration should be checked. For complete layering rules, refer to Plugin Configuration Files.

1
import asyncio
2
3
import nemo_relay
4
5
adaptive_config = nemo_relay.adaptive.AdaptiveConfig(
6
    agent_id="planner",
7
    state=nemo_relay.adaptive.StateConfig(
8
        backend=nemo_relay.adaptive.BackendSpec.in_memory(),
9
    ),
10
    telemetry=nemo_relay.adaptive.TelemetryConfig(
11
        subscriber_name="adaptive.telemetry",
12
        learners=["tool_parallelism"],
13
    ),
14
    tool_parallelism=nemo_relay.adaptive.ToolParallelismConfig(mode="observe_only"),
15
    adaptive_hints=nemo_relay.adaptive.AdaptiveHintsConfig(
16
        inject_body_path="nvext.agent_hints",
17
    ),
18
    acg=nemo_relay.adaptive.AcgConfig(provider="passthrough"),
19
)
20
21
plugin_config = nemo_relay.plugin.PluginConfig(
22
    components=[nemo_relay.adaptive.ComponentSpec(adaptive_config)]
23
)
24
25
report = nemo_relay.plugin.validate(plugin_config)["config"]
26
if any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"]):
27
    raise RuntimeError(report["diagnostics"])
28
29
async def main():
30
    async with nemo_relay.plugin.activate(plugin_config):
31
        # Run instrumented application work here.
32
        pass
33
34
asyncio.run(main())

Manual API

Use the manual runtime API when an integration needs to own adaptive lifecycle directly instead of activating the top-level plugin component.

1
import asyncio
2
3
import nemo_relay
4
5
adaptive_config = nemo_relay.adaptive.AdaptiveConfig(
6
    agent_id="planner",
7
    state=nemo_relay.adaptive.StateConfig(
8
        backend=nemo_relay.adaptive.BackendSpec.in_memory(),
9
    ),
10
    telemetry=nemo_relay.adaptive.TelemetryConfig(
11
        subscriber_name="adaptive.telemetry",
12
        learners=["tool_parallelism"],
13
    ),
14
    tool_parallelism=nemo_relay.adaptive.ToolParallelismConfig(mode="observe_only"),
15
    adaptive_hints=nemo_relay.adaptive.AdaptiveHintsConfig(
16
        inject_body_path="nvext.agent_hints",
17
    ),
18
    acg=nemo_relay.adaptive.AcgConfig(provider="passthrough"),
19
)
20
21
runtime = nemo_relay.adaptive.AdaptiveRuntime(adaptive_config.to_dict())
22
asyncio.run(runtime.register())
23
try:
24
    # Run instrumented application work here.
25
    runtime.wait_for_idle()
26
finally:
27
    asyncio.run(runtime.shutdown())

Validation and Teardown

Validate plugin configuration before initialization. Disabled components are excluded from the effective host; validate their component-local configuration before enabling them when preparing a rollout.

Common validation failures include:

• Unknown adaptive fields when policy treats unknown fields as errors.
• Unsupported backend kinds, tool-parallelism modes, or ACG providers.
• Unsupported schema versions.
• Backend-specific fields that do not match the selected backend.

Close the activation during shutdown or test cleanup. Closing the activation deregisters the adaptive subscribers and intercepts owned by the plugin runtime.

Rollout Guidance

Start by enabling state and telemetry in a development environment. Run representative instrumented workflows, inspect emitted events and adaptive reports, and then enable active behavior one area at a time. Keep rollback as a configuration change.