From e4ae69f29549b0cd6f7746e69fda8dfcdd2489a4 Mon Sep 17 00:00:00 2001 From: Ryan Thrash Date: Fri, 5 Jun 2026 17:04:09 -0500 Subject: [PATCH] docs: add missing Agents page and fix gitignore that dropped it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs deploy workflow failed on main with broken links to docs/Admin/Agents.md from Tools.md and Chat.md. Root cause: the `.gitignore` rule `AGENTS.md` (meant for the root agent-instructions file) was unanchored, so with core.ignorecase=true on a case-insensitive filesystem it also matched `docs/Admin/Agents.md`. `git add docs/` silently skipped the new page, so it was never committed or merged — the local build only passed because the untracked file sat on disk. - Anchor the rule to `/AGENTS.md` so it ignores only the root file. - Add the previously-dropped docs/Admin/Agents.md. Verified with `npm run build` (no broken links). Co-Authored-By: Claude Opus 4.8 --- .gitignore | 2 +- docs/Admin/Agents.md | 48 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 docs/Admin/Agents.md diff --git a/.gitignore b/.gitignore index 9617f5b..565aeac 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,4 @@ _build/migrations/migrations.lock _build/gpm_scripts _build/gpm_resolvers copilot-instructions.md -AGENTS.md +/AGENTS.md diff --git a/docs/Admin/Agents.md b/docs/Admin/Agents.md new file mode 100644 index 0000000..38fe4bf --- /dev/null +++ b/docs/Admin/Agents.md @@ -0,0 +1,48 @@ +--- +sidebar_position: 3 +--- + +# Agents + +## What an Agent Is + +An **Agent** is a configurable preset that bundles the other modAI building blocks into a specific, reusable AI assistant. An agent can include: + +- **[Tools](Tools.md)** for specialized actions (reading/updating MODX elements, calling external APIs, running searches) +- **[Context Providers](Context-Providers.md)** for grounded, site‑specific information +- A custom **system prompt** that defines the assistant's behavior and persona +- **Model parameters** (e.g., temperature) that control response characteristics +- A specific AI **Model** (in `service/model` format, e.g. `openai/gpt-4o-mini`) + +:::info +Agents are currently the **only** way to utilize Tools and Context Providers within modAI. If you want an assistant to call a Tool or retrieve from a Context Provider, you attach them to an Agent. +::: + +## Creating an Agent + +From the **Agents** tab in the modAI admin you can: + +- Create a new agent with a **unique name** and description. +- Choose the **Model** the agent uses. +- Set a **system prompt** that frames every conversation the agent has. +- Adjust **model parameters** such as temperature. +- Attach one or more **Tools** so the agent can take actions. +- Attach one or more **Context Providers** so the agent can ground its answers in your data. + +Because agents are configured in the Manager rather than in code, you can iterate on prompts, swap models, and add or remove tools without redeploying. + +## Controlling Access + +Access to a specific agent is controlled by assigning one or more **user groups** to it: + +- If **no** user group is assigned, the agent is available to everyone who can use modAI. +- If one or more user groups are assigned, only members of those groups see the agent. +- **Sudo** users always have access to every agent, regardless of the groups specified. + +See [Permissions](../Configuration/Permissions.md) for the full list of `modai_admin_agent_*` and client permissions that govern who can create, edit, and use agents. + +## Design Tips + +- Keep each agent **narrowly scoped** — a focused agent (e.g., "SEO Assistant" or "Support Answer Drafter") produces more predictable results than a do‑everything one. +- Bind **write or delete Tools** to admin‑only agents, and restrict those agents to trusted user groups. +- Pair an agent with only the **Context Providers** it actually needs, to keep retrieval relevant and token usage down.