Edit online

Creating Custom AI Actions

In the Oxygen AI Positron Assistant Actions preferences page, you can define a reference to a folder that contains custom actions.

The New Document wizard in Oxygen can be used to create either a new AI Positron Custom Action file that contains a custom action definition in JSON format or an AI Positron Custom Actions List that contains a JSON array with multiple defined actions. Validation and content completion are automatically provided for these custom action files. To edit multi-line parameter values, you can switch the edited action JSON definition file to the Author visual editing mode.

If you save the action definition files in the custom actions folder defined in the Oxygen AI Positron Assistant Actions preferences page, the AI Positron Assistant view automatically reloads its Actions list to include them.

Various examples of custom AI actions can be found here and can be used as starting points for your own similar AI actions.

An AI action definition may contain the following properties:

id

A unique ID for the action. If the ID of the action starts with agent.hidden.action., then the action is not visible to be invoked directly but can be called by using the invoke_ai_action(actionID, content) function.

Example:

{
        "id": "improve.grammar.custom.styles",
        "title": "...",
        ...
}

Note:

An Oxygen XML desktop plugin can contribute an extra translation.xml file that contains translations. Such a plugin may translate titles and descriptions for AI actions using the action ID as part of the key.

Example:

	<key value="improve.grammar.custom.styles.title"> 
		<val lang="en_US">Improve Styles</val> 
		<val lang="de_DE">...</val> 
		... 
	</key>
	<key value="improve.grammar.custom.styles.description">
		<val lang="en_US">Analyze and improve styles.</val>
		<val lang="de_DE">...</val>
		...
	</key>

title

The action name/title that gets presented in the UI.

Example:

{
        "id": "improve.grammar.custom.styles",
        "title": "Improve Grammar and Styles",
        ...
}

description

A longer description of what the AI action does, usually used as a tooltip.

Example:

{
        "id": "...",
        "title": "Improve Grammar and Styles",
        "description": "Improve the grammar and styles based on the company's style guide."
}

short-description

A shorter description for the AI action that usually appears under the action title in the chat view. If not specified, it defaults to the description value.

Example:

{
    "id": "action.translate.to.english",
    "title": "English",
    "short-description": "Translate to English",
    "description": "Translate the selected content to English while preserving its 
    original DITA XML markup.",
    ....
}

categoryId

The optional category in which the AI action is visually grouped, if not specified it defaults to Other.

Example:

{
        "id": "improve.grammar.custom.styles",
        "title": "Improve Grammar and Styles",
        "categoryId": "Rewrite"
}

framework

A framework pattern (like 'DITA*') or content type name (like 'text/css') that, when matched, presents the action when the document belonging to the framework is opened.

Example:

{
    "id": "generate.img.alternate.text",
    "title": "Generate Image Alternate Text",
    "framework": "*DITA*",
    ...
}

An example of an AI action that shows this for any edited XML document (as it matches the text/xml content type) can be found here.

prompt_ref

A reference to a separate file (usually encoded in Markdown) which defines the entire action prompt.

Example:

{
    "id": "action.update.title.based.on.content",
    ....
    "prompt_ref": "prompts/action_update_title.md"
  }

Important:

The prompt is the most important part of the AI action. A prompt must be as precise and detailed as possible, including examples. Some companies may adopt prompt methodologies like COSTAR to specify the prompt value. The context prompt defined in the Oxygen AI Positron Assistant Preferences page is used as a prefix for all AI action prompts.

Here is an example of a large prompt file.

A custom AI action can expand the context prompt in a specific part of its prompt by using the ${contextPrompt} variable in its own prompt.

To define a custom AI action that does not use the context prompt in any way, in the AI action's JSON configuration file, you can expand the context prompt to an empty value like this:

{
    "id": "improve.grammar.custom",
    "title": "..",
     ....
    "expand-params": [
        {
         "name": "contextPrompt",
         "value": ""
        }
    ]
}

prompt

Multi-line parameter value that defines inline the prompt that is sent to the AI along with the content to be processed.

Example:

{
    "id": "action.review.logical.mistakes",
    "title": "Logical Inconsistencies",
    "output-action": "none",
    "prompt": "# CONTEXT #\n\nYou will act as a reviewer interested in finding inconsistency 
    and logical mistakes.\n\n# OBJECTIVE #\n\nYou are tasked with reviewing the given content.
    \nFind logical and inconsistency mistakes in the content and return a report."
}

Important:

Here is an example of a large prompt file.

A custom AI action can expand the context prompt in a specific part of its prompt by using the ${contextPrompt} variable in its own prompt.

To define a custom AI action that does not use the context prompt in any way, in the AI action's JSON configuration file, you can expand the context prompt to an empty value like this:

{
    "id": "improve.grammar.custom",
    "title": "..",
     ....
    "expand-params": [
        {
         "name": "contextPrompt",
         "value": ""
        }
    ]
}

expand-params

A JSON array that can define values for parameters that should be expanded in the context content.

You can define parameters that can be configured by the end user when hovering over the AI action in the UI.

Example:

{
  "id": "thesaurus",
  "title": "Thesaurus/Synonyms",
  "output-action": "replace",
  "prompt": "Provide a max of ${number} synonyms for:",
  "expand-params": [
    ...
    {
      "name": "number",
      "label": "Number of synonyms",
      "value": "10",
      "choice-type": "single-choice",
      "alternate-values": [
        "10",
        "20",
        "30"
      ]
    }
  ]
}

The following properties are available for a defined parameter:

name

The parameter name. It can be referenced multiple times with the syntax ${param_name} in the context parameter or in the external prompt file referenced using prompt_ref.

label

The label that appears in the UI when the parameter's value is configured by the end user.

value

The value of the parameter. It can contain various editor variables that get automatically expanded.

Example:

{
        "id": "action.update.prolog",
        ...
        "prompt": "Update the DITA XML topic prolog with the current date ${currentDate}...",
        "expand-params": [
            {
                "name": "currentDate",
                "value": "${date(yyyy-MM-dd)}"
            }
        ]
    }

alternate-values

An optional array of alternate values that are available to be configured by the end user when hovering over the AI action.

choice-type

An optional choice type that defines how the end user can configure the alternate values (combo box, check boxes, radio buttons).

prefix

The optional prefix value to be used for each expansion of the parameter's value.

parameters

An array of parameters that can be used to specify an engine name, temperature, or the available function definitions. Some of the most commonly set parameters:

engine

The optional name of the engine to use with the AI action, no matter what the default AI engine model is configured to be.

Example:

{
    "id": "action.review.logical.mistakes",
    ....,
    "parameters": {
        "engine": {"name": "o1"}
    }
}

temperature

Temperature is an optional parameter that governs the randomness and thus the creativity of the responses. It is always a number between 0 (more deterministic) and 1 (more random). The default value is 0 and it should, in general, remain unspecified when your AI actions are intended for technical documentation that is precise in nature.

function_refs

An optional JSON array that describes which functions can be used when executing this action. For the list of available functions, see Function Calls.

Example of an AI action that uses Retrieval Augmented Generation (RAG) functions to find related content in the project:

{
    "id": "find.add.related.links",
    ...
    "parameters": {
    "function_refs": [
        {"ref": "get_related_resources_overview_from_project"},
        {"ref": "get_content_for_document_url"}
    ]
}
}

Example of an AI action that uses the get_content_for_document_url function to retrieve content from a web site:

{
    "id": "action.get.oxygen.version.web.site",
    "output-action": "insert",
    "title": "Insert Latest Oxygen Version",
    "prompt": "Obtain the latest version of Oxygen from the 
    'https://www.oxygenxml.com/xml_editor/whats_new.html' web site by calling the function 
    'get_content_for_document_url' and return it.",
    "parameters": {
        "function_refs": [
            {"ref": "get_content_for_document_url"}
        ]
    }
  }

Important:

There are specific actions that can be called to invoke other AI actions from an AI action, thus creating an agenting mechanism where various parts of the work is done by various actions. An example can be found here.

input

Defines which part of the current document should be sent to be processed by the AI engine.

selection, document [default]: Prefers sending the selected content. If there is no selection, it selects and sends the entire document.
selection: Prefers sending the selected content. If no content is selected, either no content is sent or an error message is received (depending on the action's output-action).
document: Always sends the entire document for processing, regardless if there is content selected inside it.
none: Does not send any content from the current document. See this example.

input-type

Describes how the XML content from the document that is sent to the platform should be processed, as regular XML including markup tags or as plain text without the tags and with all DITA XML content references and key references expanded. By default, its value is assumed to be markup, which means the content is sent exactly as it is.

Example of an AI action that requires the input to be sent without any markup tags and with the DITA XML conrefs and keyrefs expanded:

{
    "id": "action.answer.questions",
    "output-action": "none",
    "description": "Generate answers to questions you ask based on the selected text or on the 
    entire document content.",
    "input-type": "markup",
    ....
  }

output-action

Defines the type of change the AI action performs on the opened document. Some of the most commonly used type values are listed below:

replace

The most common type of action. Sends the selected content to the AI platform and proposes to replace the selection with the received response. If there is no selected content automatically, the entire document is selected when the action is invoked.

Example:

{
  "id" : "replace.bold.with.uicontrol",
  "title" : "Replace bold with uicontrol",
  "output-action" : "replace",
  "prompt" : "Replace the bold element with the uicontrol element (<uicontrol>)....",
}

insert

Inserts the content received from the AI engine in the current document at the cursor position or at an offset specified by the insert-modes. If the inserted content is invalid at the proposed offset, the application attempts to find a proper location for it.

Example:

{
    "id": "action.update.title.based.on.content",
    "title": "Update Title",
    "output-action": "insert",
    "prompt": "You are tasked with creating a title for the given text, summarizing it and 
    focusing on its main points:"
}

none

Sends the selected content or the entire document to the AI platform and shows the response to the end user.

Example:

{
    "id": "action.review.logical.mistakes",
    "title": "Logical Inconsistencies",
    "output-action": "none",
    "prompt": "Find logical and inconsistency mistakes in the content and return a report.",
}

create-new-document

Shows a dialog box that asks for a context and then creates a new document based on the received server response. The "additional_info"/"properties"/"file_extension" property can be set to impose an extension for the newly created document.

Example:

{
    "id": "action.create.schematron.rules",
    "title": "Schematron Rules from Style Guide",
    "output-action": "create-new-document",
    "additional_info": {
        "properties": {"file_extension": "sch"}
    },
    "prompt_ref": "prompts/create-schematron-rules.md"
}

insert-modes

A JSON array that defines places for inserting the content in an XML document. The first mode for which the XPath condition becomes true is run. Such modes are used when the AI action output-action is insert.

Example:

{
    "id": "action.update.title.based.on.content",
    ...
    "output-action": "insert",
    ...
    "insert-modes": [
      {
        "xpath-condition": "(//title)[1]",
        "target-location": "(//title)[1]",
        "action": "replace"
      },
      {
        "target-location": "(//shortdesc)[1]",
        "action": "insert-before"
      }
    ]...
  }

embed-assist

Set this optional boolean parameter to true to add the AI action to the top right AI Positron Assistant drop-down menu that appears when editing content in the Author visual editing mode.

quick-assist

Set this optional boolean parameter to true to add the AI action to the quick assist bulb drop-down menu that appears in the left vertical stripe.

Function Calls

Within the definition of custom actions, you can reference existing functions that are called by the AI engine to interact with the application. This gives actions more context information and generates more accurate responses from the AI.

Here is an example of a function reference that gets called by the AI engine to obtain the entire contents of the document:

{
    "id": "action.summarize",
    "title": "Summarize",
    "categoryId": "Overview",
    "output-type": "none",
    "description": "Generate a summary of the selected content or the entire document.",
    "prompt": "Your task is to summarize the provided user text.",
    "parameters": {
        "function_refs": [
            {
                "ref": "get_current_document_plain_text_content"
            }
        ]
    }
}

The current available function reference values are:

add_to_toc(ditaMapURL, resourceURL, anchorNodeURL, positionOfInsertion): Modifies the DITA map currently opened in the DITA Maps Manager view and adds a topic reference to it.
get_content_around_caret: Retrieves size-limited content around the current cursor location within the document open in the editor.
get_content_for_document_url: Retrieves content from the document specified by the provided URL. An optional lineNumbering parameter allows the AI to request the returned content to be returned with line numbers included.
get_current_document_marked_up_content: Retrieves all text with markup from the current document open in the editor. An optional lineNumbering parameter allows the AI to request the returned content to be returned with line numbers included.
get_current_document_plain_text_content: Retrieves all plain text (e.g. without markup) from the current document open in the editor.
get_current_editor_file_location: Retrieves the location (absolute path/URL) of the current file that is open in the editor.
get_related_content_from_webhelp: Returns content from the associated Oxygen Feedback WebHelp system that has external RAG sources enabled and configured.
get_related_content_from_specific_feedback_site: Returns content from the specified Oxygen Feedback WebHelp token passed as a parameter. The Enable External RAG Sources checkbox must be selected in the Functions and RAG preferences.
get_sch_component_details: Retrieves Schematron components (e.g. pattern, title, phase, diagnostics) used in the provided code, defined in both the current file and any imported or included stylesheets.
get_xsd_component_details: Retrieves XML schema components (e.g. simpleType, elements, notations, complexType, attributes, groups) used in the provided code, defined in both the current file and any imported or included stylesheets.
get_topic_context_in_toc: Returns a hierarchical structure of the DITA map that is currently open in the DITA Maps Manager view. This structure shows the selected topic and provides context, including its parent, siblings, descendants, and nearby nodes within the DITA map. This feature helps the AI understand where the topic is located in relation to other elements in the DITA map. If the selected topic cannot be identified, the hierarchy will start from the root of the DITA map.
invoke_ai_action(actionID, content): Invoke an action by passing the action ID and content to process.
Tip:
To define actions that are hidden in the interface and intended only for use by other actions, prefix their IDs with agent.hidden.action.
retrieve_all_ai_actions: Get IDs and descriptions for each available AI action.
save_document(URL,content): Saves the document at the specified path and writes content to it. If a resource already exists at the specified URL, the content of the document will be overridden with the new content. For actions that use this function, the application gathers a list of resources to modify and displays them in a Preview dialog box after the action processes.
validate_document_content(URL, content): Validates specified content and reports error messages in JSON format.
validate_current_document(): Validates the current document's content and reports error messages in JSON format.

You can impose a description for the referenced function that is called by the AI engine:

"function_refs": [
  {
      "ref": "get_current_document_plain_text_content",
      "description": "The function is designed to retrieve the complete document as 
      plain text without markup."
  }
]

Distributing and Filtering AI Actions

When installed in Oxygen XML 27.1 or newer, plugins or frameworks can contain a folder named ai-positron-actions where custom AI actions are automatically loaded from by the AI Positron add-on.

The ai-positron-actions folder can contain an extra file named excluded-action-ids.txt, which can list all action IDs (on a line-by-line basis) that should be filtered out of the AI Positron UI.