Creating Custom AI Actions for the AI Positron add-on

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

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

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

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

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

{
    "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.",
    ....
}

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

 {
        "id": "action.create.new.xslt",
        "title": "Create New XSLT",
        "profile": "xml_editor, xml_developer",
        ....
}

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. The list of functions that can be referenced is available here.

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",
    "type": "insert-schema-aware-fragment",
    "title": "Insert Latest Oxygen Version",
    "context": "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.

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

replace-selection-with-fragment

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",
  "type" : "replace-selection-with-fragment",
  "context" : "Replace the bold element with the uicontrol element (<uicontrol>)....",
}

insert-schema-aware-fragment

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",
    "type": "insert-schema-aware-fragment",
    "title": "Update Title",
    "context": "You are tasked with creating a title for the given text, summarizing it and focusing on its main points:"
}

prompt-user

Shows a dialog box that asks for a context and then runs the action.

Example:

{
        "id": "action.formula.equation",
        "title": "Formula/Equation",
        "type": "prompt-user",
        "additional_info": {"prompt-example": "hydrogen peroxide"},
        ...
}

show-response

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",
    "type": "show-response",
    "context": "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",
    "type": "create-new-document",
    "additional_info": {
        "properties": {"file_extension": "sch"}
    },
    "prompt_ref": "prompts/create-schematron-rules.md"
}