Fixes #1002 - Add AI agent usage in macros

Author: ralf401

ai/ai-agents.rst

@@ -24,9 +24,9 @@ Important Information
 
 - To configure AI agents, the ``admin.ai_agent`` permission is required
 - AI agents don't run on their own. They have to be invoked by a
-  :doc:`trigger </manage/trigger>` or a
-  :doc:`scheduler job </manage/scheduler>` with the action
-  **AI** > **AI Agent**.
+  :doc:`trigger </manage/trigger>`, a :doc:`scheduler job </manage/scheduler>`
+  or a :doc:`macro </manage/macros>` with the action **AI** > **AI Agent**.
+- By creating a macro with an AI agent action, your agents can run it on demand.
 - If an AI agent applies changes to a ticket, you can find an entry in the
   ticket history with the name of the AI agent.
 
@@ -42,17 +42,17 @@ Create an AI agent by clicking the **New AI Agent** button in the top right
 corner. This opens a wizard where you can choose the type of the agent and
 additional settings based on the selected type, see :ref:`ai-agent-types` for
 details. The action column with the ︙ button allows you to clone or delete an
-AI agent. You can only delete AI agents which are not used in triggers and
-schedulers. You can find this information in the two columns in the AI agent
-table.
+AI agent. You can only delete AI agents which are not used in triggers,
+scheduler jobs and macros. Check the **Used in** column and hover over an
+entry to see where an AI agent is used.
 
 .. _ai-agent-types:
 
 AI Agent Types
 --------------
 
-Define your AI agents and use them afterwards in triggers or scheduler jobs.
-An example for a trigger configuration could look like this:
+Define your AI agents and use them afterwards in triggers, scheduler jobs or
+macros. An example for a trigger configuration could look like this:
 
 - Activated by: **Action**
 - Action execution: **Selective**

images/ai/manage-agents.png

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Zammad Admin Documentation pre-release\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-12-04 09:19+0100\n"
+"POT-Creation-Date: 2025-12-04 15:20+0100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
@@ -46,7 +46,11 @@ msgid "To configure AI agents, the ``admin.ai_agent`` permission is required"
 msgstr ""
 
 #: ../ai/ai-agents.rst:26
-msgid "AI agents don't run on their own. They have to be invoked by a :doc:`trigger </manage/trigger>` or a :doc:`scheduler job </manage/scheduler>` with the action **AI** > **AI Agent**."
+msgid "AI agents don't run on their own. They have to be invoked by a :doc:`trigger </manage/trigger>`, a :doc:`scheduler job </manage/scheduler>` or a :doc:`macro </manage/macros>` with the action **AI** > **AI Agent**."
+msgstr ""
+
+#: ../ai/ai-agents.rst:29
+msgid "By creating a macro with an AI agent action, your agents can run it on demand."
 msgstr ""
 
 #: ../ai/ai-agents.rst:30
@@ -62,15 +66,15 @@ msgid "Screenshot shows AI agents management"
 msgstr ""
 
 #: ../ai/ai-agents.rst:41
-msgid "Create an AI agent by clicking the **New AI Agent** button in the top right corner. This opens a wizard where you can choose the type of the agent and additional settings based on the selected type, see :ref:`ai-agent-types` for details. The action column with the ︙ button allows you to clone or delete an AI agent. You can only delete AI agents which are not used in triggers and schedulers. You can find this information in the two columns in the AI agent table."
+msgid "Create an AI agent by clicking the **New AI Agent** button in the top right corner. This opens a wizard where you can choose the type of the agent and additional settings based on the selected type, see :ref:`ai-agent-types` for details. The action column with the ︙ button allows you to clone or delete an AI agent. You can only delete AI agents which are not used in triggers, scheduler jobs and macros. Check the **Used in** column and hover over an entry to see where an AI agent is used."
 msgstr ""
 
 #: ../ai/ai-agents.rst:52
 msgid "AI Agent Types"
 msgstr ""
 
 #: ../ai/ai-agents.rst:54
-msgid "Define your AI agents and use them afterwards in triggers or scheduler jobs. An example for a trigger configuration could look like this:"
+msgid "Define your AI agents and use them afterwards in triggers, scheduler jobs or macros. An example for a trigger configuration could look like this:"
 msgstr ""
 
 #: ../ai/ai-agents.rst:57
@@ -6972,55 +6976,59 @@ msgstr ""
 msgid "add new notes to a ticket"
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:24
+#: ../manage/macros/how-do-they-work.rst:23
+msgid "run an :doc:`AI agent </ai/ai-agents>`"
+msgstr ""
+
+#: ../manage/macros/how-do-they-work.rst:25
 msgid "There are **no** actions for:"
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:26
+#: ../manage/macros/how-do-they-work.rst:27
 msgid "sending a reply to the customer"
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:28
+#: ../manage/macros/how-do-they-work.rst:29
 msgid "Unlike triggers, the scheduler, and text modules, macro actions do **not** support the use of :doc:`/misc/variables`."
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:32
+#: ../manage/macros/how-do-they-work.rst:33
 msgid "If the ticket is missing a required attribute and the macro doesn't set it, then **no actions will be applied**."
 msgstr ""
 
 #: ../manage/macros/how-do-they-work.rst:0
 msgid "Once completed..."
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:37
+#: ../manage/macros/how-do-they-work.rst:38
 msgid "After running this macro, should Zammad remain on the current tab, close it, or automatically switch to the next ticket? (Does not apply when running macros \"in bulk\".)"
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:42
+#: ../manage/macros/how-do-they-work.rst:43
 msgid "What should other Zammad admins know about this macro? (Visible only via the \"Edit: Macro\" dialog, Rails console, and API.)"
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:46
+#: ../manage/macros/how-do-they-work.rst:47
 msgid "Which :doc:`/manage/groups/index` are allowed to see/use this macro?"
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:49
+#: ../manage/macros/how-do-they-work.rst:50
 msgid "Choose \"inactive\" to disable this macro without deleting it."
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:52
+#: ../manage/macros/how-do-they-work.rst:53
 msgid "Managing Macros"
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:54
+#: ../manage/macros/how-do-they-work.rst:55
 msgid "Edit your macros by simply clicking on it. You can delete or even clone existing macros by clicking on the ︙ action menu and select the desired action:"
 msgstr ""
 
 #: ../manage/macros/how-do-they-work.rst:None
 msgid "Screenshot showing the macro action menu"
 msgstr ""
 
-#: ../manage/macros/how-do-they-work.rst:62
+#: ../manage/macros/how-do-they-work.rst:63
 msgid "When cloning a macro, make sure to click \"Submit\" for the duplicate to be created."
 msgstr ""
 

locale/admin-docs.pot

@@ -20,6 +20,7 @@ Creating Macros
 
    * set ticket attributes (priority, state, group, etc.)
    * add new notes to a ticket
+   * run an :doc:`AI agent </ai/ai-agents>`
 
    There are **no** actions for: