]>

fengchongllly@gmail.com

Operations and Management NETCONF Working Group NAIM Operation IR AI-assisted network management intent-based networking NETCONF RESTCONF This document defines Operation IR, a protocol-neutral intermediate representation for runtime network operations in the NAIM architecture. Operation IR serves as an AI-friendly operation layer between AI agents or LLM-based systems and the underlying network management protocols. It captures write operations, retrieval, RPC/action invocation, filtering, transaction metadata, precondition verification, compensation semantics, and optional expression-based values. Operation IR is designed to be consumed by any upstream mechanism capable of generating structured operation intent, including but not limited to MCP tool invocations, function calling interfaces, and agent-to-agent communication protocols. The translation of Operation IR into protocol-specific messages is performed deterministically by a Handler component, keeping the AI agent in the role of intent encoder rather than protocol executor. This document also defines context completeness classes for the Originator (AI agent) side, validation feedback requirements, and an execution preview mode intended to improve safety and operator trust. It standardizes semantic expectations and interoperability boundaries, but does not standardize proprietary dialogue policies, implementation-specific scheduling internals, automatic compensation derivation algorithms, or private execution-engine logic.

Introduction The NAIM framework introduced a structured semantic representation for AI-assisted network modeling based on YANG . The same semantic discipline is useful for runtime network operations, where users increasingly expect to express configuration, monitoring, and troubleshooting requests using high-level or natural-language intent. NAIM Operation IR defines the operation layer of the NAIM architecture. It sits between the AI agent (Originator) and the network management protocols, providing a structured, AI-friendly representation of operational intent that can be deterministically translated into protocol messages by a Handler component. This separation keeps protocol complexity out of the AI reasoning loop. The upstream interface of Operation IR is deliberately protocol-agnostic: Operation IR objects may be submitted by an LLM via MCP tool invocations, function calling, agent-to-agent communication protocols, or any other mechanism. The choice of upstream delivery mechanism does not affect the semantics of the Operation IR itself. Companion documents define specific upstream bindings (e.g., MCP integration). The downstream interface of Operation IR targets model-driven network management protocols, with NETCONF and RESTCONF as the primary examples. Handlers MAY support additional management protocol backends. Direct translation of runtime intent into protocol messages suffers from:

• ambiguity in user intent;
• missing required parameters;
• violation of model constraints;
• lack of explicit precondition handling;
• multi-step changes that require rollback or compensation; and
• protocol-specific behavior that obscures the original intent.

NAIM-OP addresses these problems by introducing Operation IR, a protocol-neutral intermediate object designed to capture runtime semantics before protocol-specific requests are produced.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Where examples of JSON or other structured content exceed the line-length limits of this document format, the single-backslash strategy ('\') defined in is used to fold long lines.

Terminology

NAIM Document:

A semantic model object as defined by the NAIM framework .

Operation IR:

A structured JSON object representing a runtime operation intent.

Originator:

The AI agent or LLM-based system that generates Operation IR objects based on user intent and available semantic context.

Handler:

The deterministic software component that validates Operation IR objects against the NAIM Document, checks preconditions against the live device, and translates validated Operation IR into protocol-specific messages for execution.

Target Path:

An absolute schema path identifying the target of an operation.

Hard Constraint:

A model-derived constraint that MUST be satisfied.

Soft Constraint:

An operation-time condition or preference associated with a value.

Dynamic Reference:

A reference to current network state used during evaluation.

Transaction:

A group of operations intended to execute as one logical unit.

Compensation Operation:

An operation intended to reverse or mitigate the effect of a previously executed operation.

Context Completeness:

The degree to which the semantic context available to the Originator (AI agent) is complete, partial, or skeleton-only. This refers to the Originator-side NAIM LLM Context View, not to the Handler's internal NAIM Document, which SHOULD always be complete.

Scope and Non-Goals

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.

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.

Design Principles NAIM-OP is guided by:

• protocol neutrality on the upstream (AI agent) side;
• open extensibility on the downstream (protocol execution) side;
• semantic grounding in NAIM Document context;
• progressive extensibility;
• explicit degradation behavior; and
• user-visible safety boundaries.

Architectural Position

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: 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.

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 . Handler behavior is described in Sections through . 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 ]]>

Originator Workflow This section describes how an Originator (AI agent or LLM-based system) uses the NAIM LLM Context View to understand user intent and generate a semantically complete Operation IR. This workflow is the core value proposition of NAIM-OP: by grounding intent generation in explicit semantic context, the Originator produces Operation IR objects that are safe, complete, and deterministically executable by the Handler. The specific dialogue strategies and question ordering used by an Originator are implementation choices and are not standardized by this document. The following describes the expected logical stages.

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.

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.

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.

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.

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.

Operation Intermediate Representation

General Form An Operation IR object typically contains:

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

Core Fields

operation operation is required. Recognized values include: create, update, delete, replace, get, get-config, rpc, and action.

target target is required and MUST be an absolute schema path. For list instances, key predicates SHOULD be included where necessary to identify a specific instance.

values values carries configuration payload or input parameters. It SHOULD be omitted for retrieval-only or pure deletion cases when not needed.

filter filter is used for retrieval operations and SHOULD use one unambiguous filter form per operation.

order order MAY express numeric sequencing or explicit dependency relationships among operations.

description description MAY carry a human-readable summary suitable for audit, logging, preview, or operator review.

context context MAY include: module, datastore, transaction_id, timeout, execution_mode, and context_completeness. context_completeness describes the completeness of the NAIM LLM Context View available to the Originator at the time the Operation IR was generated. It does not describe the Handler's internal NAIM Document, which SHOULD always be a complete canonical representation.

precondition_state precondition_state MAY map one or more paths to expected values that MUST hold before execution.

compensation compensation MAY contain one or more Operation IR objects intended to reverse or mitigate previously executed changes.

constraints constraints MAY contain operation-time conditions such as soft constraints or structured expectations.

Datastore Selection Datastore selection in Operation IR follows the Network Management Datastore Architecture (NMDA) defined in and its updates. The datastore field in Operation IR context SHOULD reference a datastore by its NMDA-defined name or a vendor-defined name where applicable.

Conventional Configuration Datastores defines conventional configuration datastores as: running, startup, candidate, and intended. 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 . System configuration may be referenced or overridden by client configuration in running.

Operational State Datastore

operational:

Defined separately in 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.

Dynamic Configuration Datastores 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.

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 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.

Soft Constraints and Dynamic Values

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

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

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

Context Completeness and Best-Effort Operation

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.

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.

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.

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.

Transactions and Compensation

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

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

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

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.

Dry-Run and Execution Preview

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

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.

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.

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.

Protocol Mapping

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 and RESTCONF 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.

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.

Validation Error Handling

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

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.

Example

Interoperability Expectations Independent implementations SHOULD be able to:

• exchange Operation IR objects;
• interpret required core members consistently;
• preserve target-path semantics;
• preserve datastore and transaction metadata where supported;
• preserve precondition and compensation semantics where supported;
• preserve execution_mode semantics where supported; and
• communicate degraded context and validation failures explicitly.

Security Considerations Implementations SHOULD address:

• authorization for dynamic references;
• authorization for compensation operations;
• integrity of semantic context used for validation;
• audit logging of execution and rollback;
• safe handling of transaction identifiers;
• protection against unauthorized modification of Operation IR objects; and
• prevention of deceptive or incomplete dry-run previews.

Network device credentials MUST be managed by the Handler and MUST NOT be included in Operation IR objects or exposed to the Originator.

IANA Considerations This document has no IANA actions.

References Normative References &RFC2119; &RFC6241; &RFC7950; &RFC8040; &RFC8174; &RFC8342; &RFC8808; Informative References &RFC8792;

Example Operation IR

Example Skeleton-Context Warning

Example Dry-Run Preview Summary on candidate datastore followed by (NETCONF), or equivalent Compensation plan: restore enabled = true if later step fails ]]>