Operation Intent Intermediate Representation for AI-Assisted Network Management

4.1. Scope

This document describes:¶

• the architectural position of Operation IR between AI agents and management protocols;¶
• the Originator workflow for intent recognition, parameter elicitation, precondition handling, and compensation planning;¶
• the structure of Operation IR;¶
• object semantics for core runtime operation fields;¶
• datastore selection semantics;¶
• representation of soft constraints and dynamic references;¶
• transaction grouping and compensation semantics;¶
• context completeness classes for the Originator side;¶
• dry-run execution preview semantics; and¶
• validation feedback expectations.¶

4.2. Non-Goals

This document does not standardize:¶

• natural-language elicitation strategies;¶
• question ordering policies;¶
• automatic compensation derivation algorithms;¶
• execution-engine scheduling internals;¶
• expression-evaluation internals;¶
• vendor-specific workflow logic;¶
• upstream delivery mechanisms (MCP, function calling, A2A, etc.), which are defined in companion binding documents; or¶
• wire-level syntax beyond the governing protocol specifications.¶

6.1. Layered Architecture

Operation IR occupies the operation layer of the NAIM architecture, positioned between the semantic layer (NAIM Document and LLM Context View) and the protocol execution layer:¶

AI Agent / LLM (Originator)
  |
  | [any upstream mechanism: MCP, function calling, A2A, ...]
  |
Operation IR                          <-- this document
  |
  | [deterministic Handler translation]
  |
NETCONF / RESTCONF / other management protocols
  |
Network Infrastructure

The Handler is responsible for:¶

• validating Operation IR against the NAIM Document;¶
• verifying preconditions against live device state;¶
• translating validated Operation IR into protocol-specific messages;¶
• executing protocol operations; and¶
• triggering compensation on failure.¶

The Originator is responsible for generating semantically correct Operation IR objects based on user intent and the NAIM LLM Context View. The Originator does not construct protocol-specific messages directly.¶

6.2. End-to-End Interaction Flow

The complete flow from user intent to device execution is illustrated below. The Originator side (steps 1-6) covers how the AI agent retrieves semantic context, elicits missing parameters, resolves preconditions, and generates a complete Operation IR. The Handler side (steps A-E) covers deterministic validation, precondition verification against the live device, protocol translation, execution, and automatic compensation on failure. Detailed description of the Originator workflow is provided in Section 7. Handler behavior is described in Sections Section 8 through Section 14.¶

User
  |
  | natural language intent
  |
  v
Originator (AI Agent / LLM)
  |
  |--[1]--> Retrieve NAIM LLM Context View for target resource
  |           (fields, constraints, operation vocabulary,
  |            preconditions, side effects, examples)
  |
  |--[2]--> Identify target resource and operation
  |           from intent and Context View
  |
  |--[3]--> Check required fields against Context View
  |           Missing required fields --> elicit from user [LOOP]
  |           Hard Constraint violation --> re-elicit with guidance
  |           Soft Constraints --> confirm with user
  |
  |--[4]--> Resolve preconditions from Context View
  |           Structured preconditions --> populate precondition_state
  |           Natural language preconditions --> confirm with user
  |
  |--[5]--> Determine compensation need from Context View
  |           Write operations with declared side effects -->
  |           populate compensation
  |
  |--[6]--> Generate complete Operation IR
  |
  v
Handler (deterministic)
  |
  |--[A]--> Validate Operation IR against NAIM Canonical Document
  |--[B]--> Verify precondition_state against live device state
  |--[C]--> Translate to protocol-specific messages
  |--[D]--> Execute against network device
  |--[E]--> Trigger compensation on failure
  |
  v
Execution Report --> Originator --> natural language result --> User

7.1. Context View Retrieval

Before generating an Operation IR, the Originator SHOULD retrieve the NAIM LLM Context View for the target resource. The LLM Context View provides the semantic information the Originator needs to reason correctly about the operation, including:¶

• available operations and their target paths;¶
• field definitions with types, constraints, and examples;¶
• preconditions that must hold before each operation;¶
• side effects and state transitions associated with each operation;¶
• compensation vocabulary for reversible operations; and¶
• visibility conditions (if-feature, when) affecting field availability.¶

The Originator MUST NOT generate an Operation IR by guessing field names, types, or constraints from training knowledge alone. Semantic grounding in the NAIM LLM Context View is the mechanism that distinguishes NAIM-OP from generic function calling.¶

7.2. Intent Recognition and Operation Mapping

Once the Context View is available, the Originator maps the user's natural language intent to a specific operation defined in the Context View. This includes:¶

• identifying the target resource (e.g., an interface, a BGP neighbor, a routing policy);¶
• identifying the operation type (e.g., update, delete, get); and¶
• extracting any parameter values explicitly stated in the user intent.¶

If the intent is ambiguous or maps to multiple possible operations, the Originator SHOULD seek clarification from the user before proceeding.¶

7.3. Parameter Elicitation and Constraint Validation

After identifying the target operation, the Originator checks the required fields declared in the Context View against the parameters extracted from user intent. For any required field that is missing or invalid, the Originator MUST elicit the value from the user through targeted questions grounded in the Context View.¶

Elicitation SHOULD be specific and informative. The Originator SHOULD use the field's description, type, constraints, and examples from the Context View to formulate questions. For example, instead of "Please provide the MTU value", the Originator SHOULD ask: "Please provide the MTU value for interface eth0. The allowed range is 68 to 65535 bytes; common values are 1500 (standard) and 9000 (jumbo frames)."¶

Hard Constraint validation MUST be applied to each value as it is received. If a provided value violates a Hard Constraint, the Originator MUST reject the value, explain the constraint to the user, and re-elicit. The Originator MUST NOT pass a value that violates a Hard Constraint to the Handler.¶

Soft Constraints represent operation-time preferences that are not model-derived. The Originator SHOULD confirm Soft Constraints with the user before including them in the Operation IR.¶

The elicitation loop continues until all required fields are populated with values that satisfy Hard Constraints. The Originator SHOULD present a summary of the planned operation to the user for confirmation before generating the final Operation IR.¶

7.4. Precondition Handling

The Context View may declare preconditions for each operation. Preconditions come in two forms:¶

Structured preconditions are machine-evaluable conditions expressed as field-path and expected-value pairs. The Originator SHOULD include these in the precondition_state field of the Operation IR, allowing the Handler to verify them automatically against live device state before execution.¶

Natural language preconditions are human-readable descriptions that cannot be automatically verified. The Originator SHOULD present these to the user and request explicit confirmation that the precondition is satisfied before proceeding.¶

7.5. Compensation Planning

For write operations (create, update, delete, replace), the Originator SHOULD examine the side effects and state transition information declared in the Context View to determine whether a compensation operation is warranted. If the operation has declared side effects that may need to be reversed on failure, the Originator SHOULD populate the compensation field of the Operation IR with an appropriate reversing operation.¶

The Originator derives compensation operations from the Context View's operation vocabulary. For example, if the Context View declares that a create operation can be reversed by a delete operation targeting the same resource, the Originator SHOULD include that delete as the compensation for the create.¶

8.1. General Form

An Operation IR object typically contains:¶

• operation;¶
• target;¶
• values;¶
• filter;¶
• order;¶
• description;¶
• context;¶
• precondition_state;¶
• compensation; and¶
• constraints.¶

8.2. Core Fields

9.1. Conventional Configuration Datastores

[RFC8342] defines conventional configuration datastores as: running, startup, candidate, and intended. [I-D.ietf-netmod-system-config] updates this definition to also include system. These datastores share a common datastore schema, and protocol operations allow copying data between them.¶

running:

The current active configuration applied to the device. Suitable for simple standalone changes or environments in which no candidate datastore exists.¶

candidate:

A configuration datastore that can be manipulated without immediately affecting the running configuration. Suitable when operations are grouped transactionally, a preview-before-apply workflow is desired, or multiple related changes require coordinated validation.¶

startup:

The configuration loaded by the device at startup. MAY be used when persistence semantics require startup configuration handling.¶

intended:

The configuration that the device intends to apply after resolving all configuration sources. Read-only. Represents the effective configuration after all transformations have been applied to running.¶

system:

A read-only conventional datastore holding configuration provided by the device itself, as defined in [I-D.ietf-netmod-system-config]. System configuration may be referenced or overridden by client configuration in running.¶

9.2. Operational State Datastore

operational:

Defined separately in [RFC8342] as a distinct datastore category. It represents the current operational state of the device, including both applied configuration and derived state. Suitable for retrieval of live state data.¶

9.3. Dynamic Configuration Datastores

[RFC8342] defines dynamic configuration datastores as an extensible category for configuration obtained dynamically during device operation through interaction with other systems. Vendor-defined dynamic datastores MAY be referenced by name in Operation IR.¶

9.4. Other Datastores

Additional datastores defined outside the above categories MAY also be referenced by name in Operation IR. An example is:¶

factory-default:

An optional datastore defined in [RFC8808] that holds a preset initial configuration. It is neither a conventional nor a dynamic datastore but conforms to the NMDA datastore schema conventions.¶

Operation IR implementations SHOULD support selection of any NMDA-conformant datastore by name. If a requested datastore is not supported by the Handler or the target device, the Handler MUST return a validation error rather than silently falling back to an alternative datastore.¶

10.1. Distinction from Hard Constraints

Hard constraints are derived from semantic model context and MUST take precedence over operation-time preferences.¶

10.2. Expression Forms

Implementations MAY support expression objects including comparison operators, logical operators, arithmetic operators, and dynamic references.¶

10.3. Dynamic References

If a referenced value cannot be resolved, the implementation SHOULD fail the operation before generating a final protocol request.¶

11.1. Motivation

Context completeness describes the quality of the NAIM LLM Context View available to the Originator (AI agent) when generating an Operation IR. In some environments the Originator has access to a full LLM Context View derived from a complete NAIM Document. In others, only a partial or skeleton-level view is available. This section defines completeness classes for the Originator side.¶

Note: The Handler SHOULD always maintain a complete NAIM Canonical Document internally. Context completeness classes apply to the Originator's view, not to the Handler's internal representation.¶

11.2. Completeness Classes

full:

Complete semantic context from a NAIM LLM Context View derived from a complete NAIM Document or semantically equivalent source.¶

partial:

Structural and some semantic context are available, but certain descriptions, side effects, or non-structural annotations may be absent.¶

skeleton:

Only a minimum context is available, typically including path, node type, type information, key structure, basic requiredness, and machine-recoverable constraints.¶

11.3. Skeleton Context Expectations

A skeleton context SHOULD include, where available:¶

• path;¶
• node-type;¶
• type;¶
• key information;¶
• writable/config status;¶
• mandatory or requiredness indicators; and¶
• basic structural constraints recoverable from YANG.¶

11.4. Best-Effort Mode

An Originator MAY generate Operation IR in best-effort mode when only partial or skeleton context is available. If it does so, the context_completeness field MUST be set accordingly, and the Originator MUST disclose that semantic guidance is incomplete. The Handler MUST NOT relax validation requirements based on the Originator's declared context completeness.¶

12.1. Transaction Grouping

Multiple Operation IR objects MAY be associated by a shared transaction identifier.¶

12.2. Precondition Verification

If a required precondition fails, the associated operation MUST NOT be executed.¶

12.3. Compensation Operations

Compensation operations SHOULD be subject to the same authorization, validation, and logging expectations as normal operations.¶

12.4. Error Handling Expectations

Implementations supporting transactions SHOULD define behavior for: precondition failure, mid-transaction failure, compensation failure, timeout during grouped execution, and loss of connectivity during rollback.¶

13.1. Overview

An implementation SHOULD support an execution preview capability so that an operator can review planned actions before actual device change occurs.¶

13.2. execution_mode

The context member MAY contain execution_mode. Recognized values MAY include: apply, dry-run, plan-only, and validate-only. This document specifically defines dry-run semantics.¶

13.3. dry-run Semantics

When execution_mode is dry-run, the Handler MUST NOT apply actual configuration changes to the target system. Instead, it SHOULD return an execution preview containing:¶

• resolved target objects;¶
• input values or evaluated expressions;¶
• selected datastore;¶
• precondition checks or planned checks;¶
• protocol message summary (NETCONF XML, RESTCONF, or equivalent);¶
• compensation plan summary;¶
• known side effects; and¶
• any limitations of the preview.¶

13.4. Preview Limitations

A dry-run result MAY be incomplete if live-state dependencies, authorization results, or external conditions cannot be fully verified without execution. Such limitations SHOULD be disclosed.¶

14.1. Relationship to Management Protocols

The Handler performs deterministic translation of validated Operation IR objects into protocol-specific messages appropriate to the target device or management system. This translation is a Handler concern and is not visible to the Originator.¶

NETCONF [RFC6241] and RESTCONF [RFC8040] are the primary target protocols. A conforming Handler SHOULD be capable of translating Operation IR into one or more of:¶

• NETCONF <edit-config> operations;¶
• NETCONF <get-config> or <get> operations;¶
• NETCONF RPC or action invocations; or¶
• RESTCONF equivalent operations.¶

Handlers MAY support additional management protocol backends. The choice of target protocol and the specific wire format produced are Handler implementation decisions. The Operation IR representation is identical regardless of which protocol the Handler uses for execution.¶

14.2. Upstream Protocol Independence

Operation IR objects MAY be delivered to the Handler by any upstream mechanism. The semantic content of an Operation IR object is independent of the upstream delivery mechanism. Companion documents define specific upstream bindings, such as MCP tool integration.¶

15.1. Validation Error Envelope Reuse

Implementations SHOULD use the Validation Error Envelope model defined by the NAIM framework for Operation IR validation failures.¶

15.2. Operational Error Categories

Common categories MAY include:¶

• missing_required_field;¶
• invalid_target;¶
• constraint_violation;¶
• unresolved_dynamic_reference;¶
• precondition_failed;¶
• unsupported_extension; and¶
• dry_run_not_supported.¶

15.3. Example

NOTE: '\' line wrapping per RFC 8792

{
  "error_type": "constraint_violation",
  "field_path": "/values/mtu",
  "user_message": "The MTU value 100000 \
is too large. The allowed range is 68 \
to 65535.",
  "suggested_fix": "1500",
  "retryable": true
}