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. Field names stay snake_case in every binding and in plugins.toml, even when language helper functions use language-native naming conventions.

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

Component Shape

The top-level adaptive object contains:

The requested area pages cover Adaptive Cache Governor (ACG) and Adaptive Hints. 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

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

1
import nemo_relay
2
3
adaptive_config = nemo_relay.adaptive.AdaptiveConfig(
4
    agent_id="planner",
5
    state=nemo_relay.adaptive.StateConfig(
6
        backend=nemo_relay.adaptive.BackendSpec.in_memory(),
7
    ),
8
    telemetry=nemo_relay.adaptive.TelemetryConfig(
9
        subscriber_name="adaptive.telemetry",
10
        learners=["tool_parallelism"],
11
    ),
12
    tool_parallelism=nemo_relay.adaptive.ToolParallelismConfig(mode="observe_only"),
13
    adaptive_hints=nemo_relay.adaptive.AdaptiveHintsConfig(
14
        inject_body_path="nvext.agent_hints",
15
    ),
16
    acg=nemo_relay.adaptive.AcgConfig(provider="passthrough"),
17
)
18
19
plugin_config = nemo_relay.plugin.PluginConfig(
20
    components=[nemo_relay.adaptive.ComponentSpec(adaptive_config)]
21
)
22
23
report = nemo_relay.plugin.validate(plugin_config)
24
if any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"]):
25
    raise RuntimeError(report["diagnostics"])
26
27
active = await nemo_relay.plugin.initialize(plugin_config)

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

Validation And Teardown

Validate plugin configuration before initialization. Disabled adaptive components are still validated, which lets operators prepare a rollout before setting enabled = true.

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.

Clear plugin configuration during shutdown or test cleanup. Clearing the plugin configuration deregisters 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.