Skip to content

netorca_ai_processor - Manage NetOrca Pack AI processors

Part of the netautomate.netorca collection (version 2.0.0). Added in version 2.0.0.

Synopsis

  • Create, update or delete the AI processors of your services - the per-service AI agents of the NetOrca Pack framework (see netautomate.netorca.netorca_ai_processor_info for the concept).
  • A service carries at most one processor per action_type; that pair is the processor's identity. Select the target either by id or by service_id plus action_type. If no processor exists there, it is created; if one exists, only the fields you supply are compared and updated, so the task is idempotent.
  • The processor type cannot be changed in place - the platform enforces the (service, action_type) uniqueness - so re-typing a processor means removing it and creating the new one.

Requirements

The below requirements are needed on the host that executes this module.

  • netorca-sdk >= 1.0.9, < 2.0.0

Parameters

Parameter Comments
action_type
str		 The processor type - its role in the pack pipeline (config, verify, execution), the optimiser, or the change_instance_validator that reviews incoming PENDING changes.
Part of the processor's identity; required when selecting by service_id.
Choices: config, verify, execution, optimiser, change_instance_validator
active
bool		 Whether the processor participates in pipeline runs.
extra_data
dict		 The processor's behaviour switches - context enrichment (enable_pack_context, include_change_instance, include_service_config, ...), scheduling (schedule_enabled, schedule_crontab), generative UI, and for validators allow_auto_approval / allow_auto_rejection.
Compared and written key by key - keys you omit keep their current values.
Unlike the LLM model catalogue, this extra_data carries no credentials and is returned unmasked.
id
int		 ID of an existing AI processor.
With state=present the processor must exist; use service_id plus action_type to create one.
llm_model
int		 ID of the LLM model the processor runs on (see netautomate.netorca.netorca_llm_model_info).
name
str		 Human-readable processor name. Required when creating.
prompt
str		 The service owner prompt - the instructions the processor combines with the platform prompt, the declaration and any retrieved knowledge on every run.
response_schema
dict		 JSON Schema the processor's output must conform to, making the stage output machine-parseable. Ignored by the platform for change_instance_validator and optimiser processors, which use internal formats.
service_id
int		 ID of the service the processor belongs to. Selects the processor together with action_type.
state
str		 Whether the AI processor should exist.
Choices: present, absent
Default: present

Common parameters

Connection and query parameters shared by every module in the collection. See Authentication for the environment-variable pattern.

Parameter Comments
context
str		 Point of view for the request. The same query returns different data depending on which side of the service relationship your team is on.
serviceowner operates on the services your team offers - the requests made against them, their service items and deployed items. This is the side that validates, approves, deploys and completes changes.
consumer operates on what your team consumes - the service items your applications declared and the change instances tracking your own requests.
If not set, the value of the NETORCA_CONTEXT environment variable is used.
Choices: serviceowner, consumer
Default: serviceowner
api_url
str
required		 Base URL of the NetOrca API, for example https://api.example.netorca.io.
The URL is normalised to end in a single /v1, so passing it with or without the suffix both work.
If not set, the value of the NETORCA_API_URL environment variable is used.
api_key
str
required		 API key of your NetOrca team. The NetOrca API supports API-key authentication only - there is no username/password mode.
Treat the key like a password - supply it via the NETORCA_API_KEY environment variable (for example from a CI/CD secret) or from Ansible Vault, never as a literal in a playbook.
If not set, the value of the NETORCA_API_KEY environment variable is used.
validate_certs
bool		 Whether to validate TLS certificates when talking to the API.
Only disable this for lab instances with self-signed certificates.
If not set, the value of the NETORCA_VALIDATE_CERTS environment variable is used.
Default: true

Attributes

Attribute Support Description
check_mode full Create, update and delete are predicted from the fetched state without writing.
diff_mode full Returns before/after of exactly the fields that change.

Notes

  • All modules talk to the NetOrca REST API and are typically executed on the controller (hosts=localhost with gather_facts=false, or delegate_to=localhost).
  • Module parameters take precedence over their NETORCA_* environment variable fallbacks.

Examples

- name: A config-stage processor that renders AS3 from declarations
  netautomate.netorca.netorca_ai_processor:
    service_id: 49
    action_type: config
    name: vip_config
    llm_model: 8
    prompt: "{{ lookup('ansible.builtin.file', 'prompts/config_prompt.md') }}"
    response_schema: "{{ lookup('ansible.builtin.file', 'prompts/config_schema.json') | from_json }}"
    active: true

- name: Auto-approve valid requests as they arrive
  netautomate.netorca.netorca_ai_processor:
    service_id: 49
    action_type: change_instance_validator
    name: request_validator
    llm_model: 8
    prompt: Approve requests whose declaration names an allowed backend subnet.
    extra_data:
      allow_auto_approval: true
      allow_auto_rejection: false

- name: Disable a processor without losing its configuration
  netautomate.netorca.netorca_ai_processor:
    service_id: 49
    action_type: verify
    active: false

- name: Remove the optimiser
  netautomate.netorca.netorca_ai_processor:
    service_id: 49
    action_type: optimiser
    state: absent

Return values

ai_processor

The AI processor after the operation (or the projected result in check mode).

  • Returned: when state=present
  • Type: dict
  • Sample:
{
  "action_type": "config",
  "active": true,
  "id": 65,
  "name": "vip_config"
}

msg

Human-readable summary of what happened.

  • Returned: always
  • Type: str
  • Sample:
"updated: prompt, active"

See also

Authors

  • NetAutomate (@netautomate)