diff --git a/Writerside/m.tree b/Writerside/m.tree index ea10ab0..57ffb0c 100644 --- a/Writerside/m.tree +++ b/Writerside/m.tree @@ -9,12 +9,12 @@ + - + - diff --git a/Writerside/topics/Agents.md b/Writerside/topics/Agents.md index bd83647..8cc561a 100644 --- a/Writerside/topics/Agents.md +++ b/Writerside/topics/Agents.md @@ -1,26 +1,52 @@ # Agents - -To create an agent, navigate to the Extras -> modAI -> Agents and hit `Create Agent` button. - -## Properties - -### Name -Name of the agent, this text will show up in the modAI UI, in the agent selector. - -### Description -Internal description of the agent, doesn't have any special functionality. - -### User Groups -When defined, only users from those user groups will be able to use this agent. SUDO users have an access to every agent. - -### Enabled -If set to `false`, the agent won't be available in the agent selector. - -### Model -Name of the model this agent will use. If not specified, model from appropriate system setting will be used. - -### Prompt -Custom system prompt for this agent. Can give a specific persona to the agent, or instruct the AI how to use and combine specific tools. - -### Advanced Config -Through advanced config, you can override any model setting (that you have in system settings), or add any additional parameters. The format is same as in system settings. +## What an Agent Is +An **Agent** is a named configuration that bundles: +- A default **AI model** (and provider) +- A **system prompt** that defines the Agent’s role and behavior +- Optional **Tools** an Agent is allowed to call +- Optional **Context Providers** an Agent can use for retrieval‑augmented generation +- Access control and advanced execution options + +Agents give you consistent behavior for repeated tasks (e.g., “ContentWriter”, “Dev Helper”, “Support Agent”) and allow you to centralize configuration instead of scattering prompts and settings across individual fields. + +## Example Use Cases +- A marketing‑focused writer for landing pages and blog posts +- An SEO assistant for refining titles, meta descriptions, and schema +- A developer-focused helper that can inspect MODX Elements or suggest code updates +- A support or internal‑docs Agent that answers questions from indexed resources +- +## Creating and Managing Agents +From the **Agents** tab: +- Click **Create Agent**. +- Fill in the core settings: + - **Name** – Human‑friendly label shown in dropdowns and selectors. + - **Description** – Short explanation of what the agent is for. + - **Model** – The default model identifier (e.g., openai/gpt-5.1-mini, anthropic/claude-4.5-opus, google/gemini-3.0-pro, or a custom provider/model ID). + - **Base Prompt / System Prompt** – High‑level instructions defining the Agent’s persona, guardrails, and output style. +- Optionally configure: + - **Tools** – Select which tools this agent may call. + - **Context Providers** – Select the providers this agent can use to pull in relevant content. + - **User Group / Access Rules** – Restrict visibility/use of the agent to specific MODX user groups. + - **Advanced Configuration** – Any JSON or structured options supported by the implementation (for example, temperature, max tokens, or provider‑specific flags). +- Set **Enabled = Yes** to make the agent available in the modAI UI. +- Save. + +Once created, the Agent appears in: +- The Agent selector in the modAI chat modal. +- Any UI where the ✦ button is configured to allow Agent selection. + +## Access Control and Permissions +Agents can be scoped so that: +- Only specific **user groups** can see or select them. +- Certain Agents are reserved for administrators (e.g., ones with tools that modify templates or chunks). +- Agents without any tools behave as “pure” chat/content Agents; those with tools can run actions on behalf of the user. + +When designing agents: +- Separate **high‑risk tools** (e.g., edit or delete operations) into dedicated admin‑only agents. +- Use more constrained, read‑only Agents for general users. + +## Best Practices +- Keep each Agent focused on a single domain (e.g., “ContentWriter”, “SEO Assistant”, “Developer Helper”) instead of one catchall agent. +- Put brand voice, tone, and formatting rules into the system prompt so results are consistent across your site. +- Reuse the same Agent wherever possible rather than copying prompts into multiple agents. +- Periodically review usage and refine prompts based on real outputs, feedback, and new LLM updates/options. diff --git a/Writerside/topics/Context-Providers.md b/Writerside/topics/Context-Providers.md index 598906f..e1a3bbf 100644 --- a/Writerside/topics/Context-Providers.md +++ b/Writerside/topics/Context-Providers.md @@ -1,22 +1,48 @@ # Context Providers -To be able to use context providers through agents, they have to be created and configured from this section. - -To create & configure context provider, navigate to the Extras -> modAI -> Context Providers and hit `Create Context Provider` button. - -## Properties - -### Context Provider Class -Implementation of the context provider. Every context provider class can have an additional configuration that will show up in the `Config` panel on the right side. Additional context providers can be registered using plugin with `modAIOnContextProviderRegister` event. - -### Name -Name of the context provider, this name has to be unique across all configured context providers. - -### Description -Internal description of the context provider, doesn't have any special functionality. - -### Enabled -If set to `false`, the context provider won't be available for use, even when assigned to agents. - -### Additional Config Options -Every context provider class can expose a different set of additional config options. You can reference a value from system settings by using `ss:system_setting_key` format for the config option's value. +## What a Context Provider Is +A **Context Provider** is a component that knows how to: +- Retrieve relevant documents or records (from MODX, a search index, or an external service). +- Convert them into chunks of text and/or metadata suitable for AI consumption. +- Optionally work with a vector database or other retrieval mechanism. + +Agents call Context Providers when they need **grounded, site‑specific** information instead of relying only on the base model. + +## Typical Data Sources +Examples of what a Context Provider might expose: +- MODX **Resources** (e.g., content pages, knowledge base articles) +- MODX **Elements** (Snippets, Chunks, Templates) and their descriptions +- Indexed documentation, FAQs, or release notes +- External knowledge bases or search APIs + +## Registering Context Providers +To add a new provider: +- Implement a PHP class that follows the `\modAI\Tools\ToolInterface` interface. +- Register the tool with modAI: + - Create a plugin that will run on `modAIOnContextProviderRegister` event and will return the class name of the Context Provider or an array of multiple context providers you wish to register. +- Create the context provider from Context Providers tab: + - Select the Context Provider class + - A **unique name**. + - Set the internal description explaining what the Context Provider does + +Once registered, the context provider appears in the **Context Provider** tab and you’ll be able to attach it to agents. + +## Configuring Context Providers in the Manager +From the **Context Providers** tab you can: +- Enable or disable providers. +- Attach providers to specific **Agents** so only the right agents can access a given data source. + +Design tips: +- Use separate providers for very different datasets (e.g., “Public Docs”, “Internal Runbooks”, “Developer API Docs”). +- Keep provider scopes narrow so retrieval stays relevant and efficient. + +## Performance and Cost +Context providers may rely on: +- Full‑text search queries +- Vector database lookups +- External API calls + +Be mindful of: +- Token usage when passing large chunks of context into prompts. +- Rate limits and pricing for external services. +- Caching strategies to reduce repeated work. diff --git a/Writerside/topics/Permissions.md b/Writerside/topics/Permissions.md index d54a002..736eb95 100644 --- a/Writerside/topics/Permissions.md +++ b/Writerside/topics/Permissions.md @@ -19,6 +19,13 @@ modAI comes with `modAI Admin` access policy, `modAI` access policy template and - modai_admin_agent_context_provider_delete: Unassign context provider from an agent - modai_admin_related_agent_save: Assign agent to a tool/context provider - modai_admin_related_agent_delete: Unassign agent from a tool/context provider +- modai_admin_prompt_library: Access Prompt Library tab +- modai_admin_prompt_library_prompt_save: Create/Update prompt +- modai_admin_prompt_library_prompt_save_public: Set prompt as public +- modai_admin_prompt_library_prompt_delete: Delete prompts +- modai_admin_prompt_library_category_save: Create/Update prompt category +- modai_admin_prompt_library_category_save_public: Set prompt category as public +- modai_admin_prompt_library_category_delete: Delete prompt category ### Client Permissions - modai_client: Use modAI diff --git a/Writerside/topics/Prompt-Library.md b/Writerside/topics/Prompt-Library.md index b420a32..6346cc8 100644 --- a/Writerside/topics/Prompt-Library.md +++ b/Writerside/topics/Prompt-Library.md @@ -1,54 +1,17 @@ # Prompt Library -Through system setting `modai.chat.prompt_library` you can define a set of prompts for both `text` and `image` chats, that the user will be able to quickly use. +## Purpose +The **Prompt Library** is a centralized place to store and manage reusable prompts and prompt snippets, such as: +- Brand voice and tone guidelines +- SEO optimization templates +- QA or review checklists +- Reusable task patterns (e.g., “Summarize this page for our CEO”, “Rewrite this in plain, non-technical language a 12 year old can understand”) -## Example +## Prompt Types and Visibility +In the library you can typically designate prompts as: +- **Public** – Available to all users who can access modAI. +- **Private** – Only visible to the user who created them. -```JSON -{ - "text": [ - { - "name": "MODX", - "children": [ - { - "name": "Blog", - "children": [ - { - "name": "Step 1", - "value": "Say hi" - }, - { - "name": "Step 2", - "value": "Say hello" - } - ] - }, - { - "name": "Dev", - "children": [ - { - "name": "Step 1", - "value": "Say I'm dev" - }, - { - "name": "Step 2", - "value": "Say yo!" - } - ] - } - ] - } - ], - "image": [ - { - "name": "Action Figure", - "children": [ - { - "name": "Blog", - "value": "Create an image of an action figure like box, where the figure will be a MODX developer. Additional items in the box will be macbook, iphone and a book." - }, - } - ] -} - -``` +This is useful for: +- Team‑wide standard prompts (public). +- Personal workflows diff --git a/Writerside/topics/Tools.md b/Writerside/topics/Tools.md index 209988a..4c80832 100644 --- a/Writerside/topics/Tools.md +++ b/Writerside/topics/Tools.md @@ -1,28 +1,46 @@ # Tools -To be able to use tools through agents, or directly from chat, they have to be created and configured from this section. - -To create & configure tool, navigate to the Extras -> modAI -> Tools and hit `Create Tool` button. - -## Properties - -### Tool Class -Implementation of the tool. Every tool class can have an additional configuration that will show up in the `Config` panel on the right side. Additional tools can be registered using plugin with `modAIOnToolRegister` event. - -### Name -Name of the tool, this name has to be unique across all configured tools. This is how AI references a tool that it wants to run. - -### Description -Internal description of the tool, doesn't have any special functionality. - -### Prompt -Tool's prompt (aka description in AI docs), the prompt describes how to the tools works to the AI. If empty, the default prompt (from the tool class) will be used. - -### Enabled -If set to `false`, the tool won't be available for use, even when assigned to agents. - -### Default -When set to `true`, the tool will be available for use in every prompt (without a need to select an agent). Be careful with enabling this on tools as it will increase token usage and can worsen the AI responses. - -### Additional Config Options -Every tool class can expose a different set of additional config options. You can reference a value from system settings by using `ss:system_setting_key` format for the config option's value. +## What a Tool Is + +A **Tool** is a server‑side capability that an agent can call when it needs structured data or needs to perform an action. + +In modAI, Tools are generally implemented as PHP classes that: +- Declare their **name**, **description/prompt**, and **parameters** +- Implement logic to perform an action (e.g., read or update a MODX element, call an external API, run a search) +- Return structured results to the agent + +Think of Tools as “functions” an agent can call to go beyond plain text generation. + +## Common Tool Examples +- Edit or create MODX **Templates**, **Chunks**, or **Snippets** +- Fetch and return content from specific Resources +- Trigger indexing jobs for a Context Provider +- Call a third‑party API (e.g., analytics, search, CRM) and return summarized data + +## Registering Tools +Tools are typically registered via configuration and/or service discovery. At a high level, you’ll: +- Create a PHP class that implements the `\modAI\Tools\ToolInterface` interface. +- Register the tool with modAI: + - Create a plugin that will run on `modAIOnToolRegister` event and will return the class name of the tool or an array of multiple Tools you wish to register. +- Create the tool from Tools tab: + - Select the Tool class + - A **unique name** (e.g., `EditChunk`, `SearchResources`). + - Set the internal description explaining what the Tool does + - Adjust the **prompt** if needed + +Once registered, the tool appears in the **Tools** tab and you’ll be able to attach it to agents. + +## Configuring Tools in the Manager +From the **Tools** tab you can: +- Enable or disable individual Tools. +- Edit the **user‑facing name** and **prompt/description**. +- Whether a Tool is available in every prompt even without an agent + +Changes here do not require you to redeploy code, which makes it a safe place to iterate on prompts and defaults. + +## Security Considerations +Because tools can read or modify data: +- Ensure tools check **permissions** for the current MODX user. +- Avoid exposing write or delete Tools to general users; instead, bind them to admin‑only Agents. +- Validate and sanitize all input arguments. +- Log usage for sensitive operations, especially those that change content or configuration. diff --git a/assets/components/modai/mgr/css/modai.css b/assets/components/modai/mgr/css/modai.css index 952d3f1..74f98b0 100644 --- a/assets/components/modai/mgr/css/modai.css +++ b/assets/components/modai/mgr/css/modai.css @@ -27,3 +27,22 @@ .modai-admin--prompt-library_category_disabled { font-style: italic; } + +.modai-admin--panel_desc { + padding-top: 20px; + padding-left: 20px; + font-size: 14px; + color: #495057; +} + +.modai-admin--panel_desc a { + color: #4a90e2; + text-decoration: none; + font-weight: 500; + border-bottom: 1px solid transparent; + transition: border-bottom-color 0.2s ease; +} + +.modai-admin--panel_desc a:hover { + border-bottom-color: #4a90e2; +} diff --git a/assets/components/modai/mgr/js/home/panel.js b/assets/components/modai/mgr/js/home/panel.js index 4b59919..eedd6c1 100644 --- a/assets/components/modai/mgr/js/home/panel.js +++ b/assets/components/modai/mgr/js/home/panel.js @@ -45,12 +45,17 @@ Ext.extend(modAIAdmin.panel.Home, MODx.Panel, { getTopTabs: function (config) { var output = []; - if (config.permissions.modai_admin_agents) { + if (config.permissions.modai_admin_prompt_library) { output.push({ - title: _('modai.admin.home.agents'), + title: _('modai.admin.home.prompt_library'), items: [ { - xtype: 'modai-grid-agents', + html: _('modai.admin.home.prompt_library_desc'), + border: false, + bodyCssClass: 'modai-admin--panel_desc', + }, + { + xtype: 'modai-panel-prompt_library', preventRender: true, cls: 'main-wrapper', permissions: config.permissions, @@ -59,12 +64,17 @@ Ext.extend(modAIAdmin.panel.Home, MODx.Panel, { }); } - if (config.permissions.modai_admin_tools) { + if (config.permissions.modai_admin_agents) { output.push({ - title: _('modai.admin.home.tools'), + title: _('modai.admin.home.agents'), items: [ { - xtype: 'modai-grid-tools', + html: _('modai.admin.home.agents_desc'), + border: false, + bodyCssClass: 'modai-admin--panel_desc', + }, + { + xtype: 'modai-grid-agents', preventRender: true, cls: 'main-wrapper', permissions: config.permissions, @@ -73,12 +83,17 @@ Ext.extend(modAIAdmin.panel.Home, MODx.Panel, { }); } - if (config.permissions.modai_admin_context_providers) { + if (config.permissions.modai_admin_tools) { output.push({ - title: _('modai.admin.home.context_providers'), + title: _('modai.admin.home.tools'), items: [ { - xtype: 'modai-grid-context_providers', + html: _('modai.admin.home.tools_desc'), + border: false, + bodyCssClass: 'modai-admin--panel_desc', + }, + { + xtype: 'modai-grid-tools', preventRender: true, cls: 'main-wrapper', permissions: config.permissions, @@ -87,12 +102,17 @@ Ext.extend(modAIAdmin.panel.Home, MODx.Panel, { }); } - if (config.permissions.modai_admin_prompt_library) { + if (config.permissions.modai_admin_context_providers) { output.push({ - title: _('modai.admin.home.prompt_library'), + title: _('modai.admin.home.context_providers'), items: [ { - xtype: 'modai-panel-prompt_library', + html: _('modai.admin.home.context_providers_desc'), + border: false, + bodyCssClass: 'modai-admin--panel_desc', + }, + { + xtype: 'modai-grid-context_providers', preventRender: true, cls: 'main-wrapper', permissions: config.permissions, diff --git a/core/components/modai/lexicon/en/default.inc.php b/core/components/modai/lexicon/en/default.inc.php index ea2ecee..baa8296 100644 --- a/core/components/modai/lexicon/en/default.inc.php +++ b/core/components/modai/lexicon/en/default.inc.php @@ -5,9 +5,13 @@ $_lang['modai.admin.home.page_title'] = 'modAI'; $_lang['modai.admin.home.agents'] = 'Agents'; +$_lang['modai.admin.home.agents_desc'] = 'Create focused agents for tasks like content writing, SEO cleanup, or developer assistance, then configure ✦ buttons for them anywhere you choose. Learn more.'; $_lang['modai.admin.home.tools'] = 'Tools'; +$_lang['modai.admin.home.tools_desc'] = 'Define tools that let agents call MODX actions or external APIs—safely extending what modAI can do for you. Learn more.'; $_lang['modai.admin.home.context_providers'] = 'Context Providers'; +$_lang['modai.admin.home.context_providers_desc'] = 'Register context providers that feed agents structured data from MODX, external indexes, or vector databases so responses stay grounded in your content. Learn more.'; $_lang['modai.admin.home.prompt_library'] = 'Prompt Library'; +$_lang['modai.admin.home.prompt_library_desc'] = 'Build a shared library of prompts—like brand voice guidelines, SEO templates, or QA checklists—that anyone can apply with a click. Learn more.'; $_lang['modai.admin.global.no_records'] = 'No records found.'; $_lang['modai.admin.global.any'] = 'Any';