Schritt-für-Schritt-Anleitung: Hinzufügen benutzerdefinierter KI-Funktionen zum ONLYOFFICE KI-Agenten

Mit unserem neuen intelligenten KI-Agenten liefern wir innovative Tools, die den Anforderungen der heutigen schnelllebigen digitalen Welt gerecht werden. Als Open-Source-Projekt begrüßen wir nutzerorientierte Innovationen. In diesem Beitrag zeigen wir Ihnen, wie Sie dem KI-Agenten benutzerdefinierte Funktionen hinzufügen, um Ihre Arbeit mit Dokumenten schneller, einfacher und komfortabler zu gestalten.

Was sind KI-Funktionen und wozu dienen sie?

KI-Funktionen sind die Kernbausteine der Funktionalität eines KI-Agenten. Im Wesentlichen sind sie Anweisungen, die dem KI-Agenten mitteilen:

• Welche Anfrage soll an das KI-Modell gesendet werden?
• Welche Manipulationen sollen an Ihrem Dokument vorgenommen werden?

Mithilfe von KI-Funktionen können Sie die Interaktion der KI mit Ihren Dokumentinhalten erweitern und steuern.

So verwenden Sie eine KI-Funktion:

1. Fügen Sie dem KI-Plugin ein Modell Ihrer Wahl hinzu.
2. Öffnen Sie das Dialogfeld des KI-Agenten, indem Sie STRG + / drücken.
3. Geben Sie Ihre Eingabeaufforderung ein und drücken Sie die Eingabetaste.

Beispiel: Die Funktion „commentText“

Mit der Funktion commentText können Sie KI-generierte Kommentare direkt in Ihr Dokument einfügen. So funktioniert es:

• Wählen Sie ein Wort aus, zu dem Sie einen Kommentar hinterlassen möchten.
• Öffnen Sie das Dialogfeld des KI-Agenten (STRG + /).
• Geben Sie Ihre Anweisung ein, zum Beispiel: „Diesen Text erklären“.
• Drücken Sie die Eingabetaste.

Der KI-Agent führt die Funktion commentText aus und fügt relevante Kommentare in Ihr Dokument ein:

Warum sollten Sie Ihrem KI-Agenten benutzerdefinierte Funktionen hinzufügen?

Mit benutzerdefinierten KI-Funktionen erweitern Sie die Fähigkeiten des intelligenten KI-Agenten und passen ihn genau an Ihre Bedürfnisse an. Ob Sie mit Dokumenten, Tabellen oder Präsentationen arbeiten – die Vielseitigkeit des Agenten, kombiniert mit der Leistungsfähigkeit moderner KI-Modelle, hilft Ihnen, Ideen umzusetzen und nahtlos in Ihren Workflow zu integrieren.

Allgemeine Logik zum Hinzufügen benutzerdefinierter KI-Funktionen

Das Hinzufügen einer benutzerdefinierten Funktion umfasst zwei Hauptphasen:

• Funktionsregistrierung – Registriert die KI-Funktion und ihre Metadaten in der Umgebung des Agenten.
• Funktionsausführung – Implementiert die Kernlogik, die das Senden von Anfragen an das KI-Modell und die Bearbeitung von Dokumentinhalten mithilfe unserer Office-API umfasst.

Sehen wir uns diese Phasen nun genauer an.

Funktionsregistrierung

Um eine neue Funktion hinzuzufügen, implementieren wir das Objekt RegisteredFunction. Es ermöglicht uns, Metadaten und Logik hinzuzufügen. Hier ist ein Beispiel für das Hinzufügen der Funktion commentText für den Dokumenteditor:

let func = new RegisteredFunction();
        func.name = "commentText";
        func.params = [
            "type (string): whether to add as a 'comment' or as a 'footnote'    default is 'comment')"
        ];


        func.examples = [
            "If you need to explain selected text as a comment, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"comment\"}",


            "If you need to add a footnote to selected text, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Add a footnote to this text\", \"type\": \"footnote\"}",


            "If you need to comment selected text, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Comment this text\"}",


            "If you need to explain selected text as a footnote, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"footnote\"}"
     ]

Dabei gilt:

• func.name: Der Name, den die KI zum Aufrufen dieser Funktion verwendet (z. B. „commentText“).
• func.params:Eine Liste der Parameter, die die Funktion von der KI erwartet. Beispiele:

–  prompt (string): Eine Beschreibung oder Anweisung für den Kommentar.

–  type (string): “comment” (Kommentar) oder “footnote” (Fußnote) — Gibt an, was eingefügt werden soll.

• func.examples: Beispiele für korrekte Funktionsaufrufe der KI.
• func.description: Erklärt der KI, wofür die Funktion verwendet wird.

Diese Parameter werden von der KI verwendet. Das Objekt RegisteredFunction() ist in der Datei helperFunc.js definiert.

Funktionsausführungslogik

Nach der Registrierung der Funktion implementieren wir die eigentliche Logik, die ausgeführt wird, wenn die KI diese Funktion aufruft.

• Der ausgewählte Text wird mit Asc.Editor.callCommand() abgerufen.

func.call = async function(params) {
            let type = params.type;
            let isFootnote = "footnote" === type;


// Executes a block of code inside the editor's context using the office=js API.
            let text = await Asc.Editor.callCommand(function(){
                let doc = Api.GetDocument();
// Gets the current selected text range.
                let range = doc.GetRangeBySelect();
                let text = range ? range.GetText() : "";
                if (!text)
                {
                    text = doc.GetCurrentWord();
// Selects the current word so comments can be applied to it.
                    doc.SelectCurrentWord();
                }


                return text;
            });

• Erstellen Sie die Eingabeaufforderung für die KI, indem Sie params.prompt und den ausgewählten Text kombinieren.

let argPromt = params.prompt + ":\n" + text;

• Initialisieren Sie das Objekt AI.Request.create mit AI.Request.create. Das Objekt ist in der Datei engine.js definiert. Dieses Objekt erleichtert das Senden einer Anfrage an das KI-Modell.

// Initializes a request engine for communicating with the AI model (e.g. Chat, Translation).
            let requestEngine = AI.Request.create(AI.ActionType.Chat);
            if (!requestEngine)
                return;

• Senden Sie die Anfrage mit chatRequest() und erhalten Sie das Ergebnis in einem Rückruf.

// Sends a prompt to the AI model and processes the response via callback. Can stream or wait.
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;

• Fügen Sie die Antwort mit AddFootnote() oder AddComment() als Kommentar oder Fußnote ein.

Implementierung von AddFootnote:

if (isFootnote)
            {
                let addFootnote = true;
// Sends a prompt to the AI model and processes the response via callback. Can stream or wait.
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;


// Marks the end of a logical group or block action in the editor.
                    await checkEndAction();
                    Asc.scope.data = data;
                    Asc.scope.model = requestEngine.modelUI.name;


                    if (addFootnote)
                    {
// Executes a block of code inside the editor's context using the document model API.
                        await Asc.Editor.callCommand(function(){
// Returns the main document object, which gives access to all editing, structure, and selection APIs.
                            Api.GetDocument().AddFootnote();
                        });
                        addFootnote = false;
                    }
// Inserts the AI-generated result into the document at the current selection or cursor.
                    await Asc.Library.PasteText(data);
                });

Implementierung von AddComment:

let commentId = null;
// Sends a prompt to the AI model and processes the response via callback. Can stream or wait.
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;


// Marks the end of a logical group or block action in the editor.
                    await checkEndAction();
                    Asc.scope.data = data;
                    Asc.scope.model = requestEngine.modelUI.name;
                    Asc.scope.commentId = commentId;


// Executes a block of code inside the editor's context using the document model API.
                    commentId = await Asc.Editor.callCommand(function(){
// Returns the main document object, which gives access to all editing, structure, and selection APIs.
                        let doc = Api.GetDocument();


                        let commentId = Asc.scope.commentId;
                        if (!commentId)
                        {
// Gets the current selected text range, which can be modified or annotated.
                            let range = doc.GetRangeBySelect();
                            if (!range)
                                return null;


                            let comment = range.AddComment(Asc.scope.data, Asc.scope.model, "uid" + Asc.scope.model);
                            if (!comment)
                                return null;
                            doc.ShowComment([comment.GetId()]);
                            return comment.GetId();
                        }


                        let comment = doc.GetCommentById(commentId);
                        if (!comment)
                            return commentId;


                        comment.SetText(comment.GetText() + scope.data);
                        return commentId;
                    });
                });
            }

Hinweis! Um sicherzustellen, dass der gesamte Änderungsblock nach Ausführung der Anfrage zurückgesetzt werden kann, verwenden wir die Methoden StartAction und EndAction in der Funktion commentText.

Die vollständige Implementierung der Funktion commentText mit Kommentaren:

(function(){
// Defines the commentText function — lets AI insert a comment or footnote for selected text using AI response.
    WORD_FUNCTIONS.commentText = function()
    {
// Creates a new function object that will be registered and exposed to the AI.
        let func = new RegisteredFunction();
        func.name = "commentText";
// Lists the parameters expected by the function. These are passed as a JSON object by the AI agent.
        func.params = [
            "type (string): whether to add as a 'comment' or as a 'footnote' (default is 'comment')"
        ];


// Gives example JSON inputs to teach the AI how to correctly invoke this function.
        func.examples = [
            "If you need to explain selected text as a comment, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"comment\"}",


            "If you need to add a footnote to selected text, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Add a footnote to this text\", \"type\": \"footnote\"}",


            "If you need to comment selected text, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Comment this text\"}",


            "If you need to explain selected text as a footnote, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"footnote\"}"
        ];
        
// The actual logic that gets executed when the AI calls this function.
        func.call = async function(params) {
            let type = params.type;
            let isFootnote = "footnote" === type;


// Executes a block of code inside the editor's context using the office-js API.
            let text = await Asc.Editor.callCommand(function(){
                let doc = Api.GetDocument();
// Gets the current selected text range.
                let range = doc.GetRangeBySelect();
                let text = range ? range.GetText() : "";
                if (!text)
                {
                    text = doc.GetCurrentWord();
// Selects the current word so comments can be applied to it.
                    doc.SelectCurrentWord();
                }


                return text;
            });


            let argPromt = params.prompt + ":\n" + text;


// Initializes a request engine for communicating with the AI model (e.g. Chat, Translation).
            let requestEngine = AI.Request.create(AI.ActionType.Chat);
            if (!requestEngine)
                return;


            let isSendedEndLongAction = false;
// Marks the end of a logical group or block action in the editor.
            async function checkEndAction() {
                if (!isSendedEndLongAction) {
// Marks the end of a logical group or block action in the editor.
                    await Asc.Editor.callMethod("EndAction", ["Block", "AI (" + requestEngine.modelUI.name + ")"]);
                    isSendedEndLongAction = true
                }
            }


// Starts a block action in the editor, used for undo/redo 
            await Asc.Editor.callMethod("StartAction", ["Block", "AI (" + requestEngine.modelUI.name + ")"]);
// Starts a block action in the editor, used for undo/redo
            await Asc.Editor.callMethod("StartAction", ["GroupActions"]);


            if (isFootnote)
            {
                let addFootnote = true;
// Sends a prompt to the AI model and processes the response via callback
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;


// Marks the end of a block action in the editor.
                    await checkEndAction();
                    Asc.scope.data = data;
                    Asc.scope.model = requestEngine.modelUI.name;


                    if (addFootnote)
                    {
// Executes a block of code inside the editor's context using the  office-js API.
                        await Asc.Editor.callCommand(function(){
                            Api.GetDocument().AddFootnote();
                        });
                        addFootnote = false;
                    }
// Inserts the AI-generated result into the document at the current selection or cursor.
                    await Asc.Library.PasteText(data);
                });
            }
            else 
            {
                let commentId = null;
// Sends a prompt to the AI model and processes the response via callback.
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;


// Marks the end of a block action in the editor.
                    await checkEndAction();
                    Asc.scope.data = data;
                    Asc.scope.model = requestEngine.modelUI.name;
                    Asc.scope.commentId = commentId;


// Executes a block of code inside the editor's context using the office-js API.
                    commentId = await Asc.Editor.callCommand(function(){
                        let doc = Api.GetDocument();


                        let commentId = Asc.scope.commentId;
                        if (!commentId)
                        {
// Gets the current selected text range.
                            let range = doc.GetRangeBySelect();
                            if (!range)
                                return null;


                            let comment = range.AddComment(Asc.scope.data, Asc.scope.model, "uid" + Asc.scope.model);
                            if (!comment)
                                return null;
                            doc.ShowComment([comment.GetId()]);
                            return comment.GetId();
                        }


                        let comment = doc.GetCommentById(commentId);
                        if (!comment)
                            return commentId;


                        comment.SetText(comment.GetText() + scope.data);
                        return commentId;
                    });
                });
            }


// Marks the end of a  block action in the editor.
            await checkEndAction();
// Marks the end of a block action in the editor.
            await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
        };


        return func;
    }

Wir sind bestrebt, mit der modernen Technologie Schritt zu halten und sicherzustellen, dass sich unser intelligenter KI-Agent zusammen mit den Anforderungen der heutigen digitalen Welt weiterentwickelt. Durch die Erstellung eigener Funktionen können Sie seine Fähigkeiten erweitern und Ihren individuellen Anforderungen anpassen. Wir freuen uns über Ihre Kreativität und Ideen.

Bei Fragen, Anregungen oder Feedback können Sie sich gerne an uns wenden. Wir freuen uns immer über eine Zusammenarbeit und helfen Ihnen, Ihre Vision zu verwirklichen! Viel Erfolg bei Ihren Forschungsvorhaben!