diff --git a/docs/explore-and-author/.pages b/docs/explore-and-author/.pages index cf3132983..1ed622537 100644 --- a/docs/explore-and-author/.pages +++ b/docs/explore-and-author/.pages @@ -6,7 +6,7 @@ nav: - Queries: query-module - Thesauri: thesauri-management - Charts: charts-catalog - - Companion AI chat: companion + - Companion: companion - Services integrations: embedding-services-via-the-integrations-module - Link rules: link-rules - Application view: workspace-configuration diff --git a/docs/explore-and-author/companion/.pages b/docs/explore-and-author/companion/.pages new file mode 100644 index 000000000..3742c0bde --- /dev/null +++ b/docs/explore-and-author/companion/.pages @@ -0,0 +1,5 @@ +--- +nav: + - Companion: index.md + - AI chat: chat + - Management: management diff --git a/docs/explore-and-author/companion/companion-anatomy.png b/docs/explore-and-author/companion/chat/companion-anatomy.png similarity index 100% rename from docs/explore-and-author/companion/companion-anatomy.png rename to docs/explore-and-author/companion/chat/companion-anatomy.png diff --git a/docs/explore-and-author/companion/companion-answer.png b/docs/explore-and-author/companion/chat/companion-answer.png similarity index 100% rename from docs/explore-and-author/companion/companion-answer.png rename to docs/explore-and-author/companion/chat/companion-answer.png diff --git a/docs/explore-and-author/companion/companion-confirm-change.png b/docs/explore-and-author/companion/chat/companion-confirm-change.png similarity index 100% rename from docs/explore-and-author/companion/companion-confirm-change.png rename to docs/explore-and-author/companion/chat/companion-confirm-change.png diff --git a/docs/explore-and-author/companion/companion-modes.png b/docs/explore-and-author/companion/chat/companion-modes.png similarity index 100% rename from docs/explore-and-author/companion/companion-modes.png rename to docs/explore-and-author/companion/chat/companion-modes.png diff --git a/docs/explore-and-author/companion/chat/index.md b/docs/explore-and-author/companion/chat/index.md new file mode 100644 index 000000000..a1cfca1c1 --- /dev/null +++ b/docs/explore-and-author/companion/chat/index.md @@ -0,0 +1,132 @@ +--- +title: "Companion: AI chat" +icon: eccenca/application-ai-suggestion +status: new +tags: + - Reference +--- +# Companion AI chat + +!!! info "AI Disclaimer" + + Companion is an AI-based feature. + AI-generated content may be inaccurate or incomplete. + Verify important information. + +The Companion is a chat panel in Explore that answers questions about the data in eccenca Corporate Memory and, on request, changes it. +It reads the view that is open, works with graphs, resources, queries, Build projects and Marketplace packages, and asks for a confirmation before it writes anything that the selected mode does not allow on its own. + +The Companion requires a [configuration](../index.md#configuration) of the deployment and an [access right](../index.md#access) for the user. +Agents, tools and modes are explained in [How the Companion works](../index.md#how-the-companion-works). + +## Open the Companion + +Click :eccenca-application-ai-suggestion: **Chat with the companion** in the application header, next to the :eccenca-application-useraccount: user menu. +The Companion panel opens on the right side of the screen. +Click the button again to close the panel. + +![Companion panel next to a resource in Explore](companion-anatomy.png){ class="bordered" width="70%" } + +The panel contains: + +- **Chats** to switch to an earlier chat, search for a chat, rename it with :eccenca-item-edit: or delete it with :eccenca-item-remove: +- :eccenca-item-add-artefact: **New chat** to start a new chat +- **Wide view** and **Narrow view** to change the width of the panel +- The messages of the current chat +- The mode selector, see [Modes](#modes) +- The context tag, which names the view the Companion sees +- The input field with :eccenca-item-upload: **Attach a file** and :material-send-variant-outline: **Send the message** + +## Ask a question + +1. Enter a question in the **Ask the companion** field. +2. Optionally, refer to a resource or a skill: + - Enter `@` followed by the beginning of a label to search for a resource in the open graph, then select the resource from the list. + - Enter `/` to list the skills, then select a skill, for example `/summarize_graph`. +3. Optionally, click :eccenca-item-upload: **Attach a file** to add one or more files to the message, or drop them on the panel. + Files larger than the configured limit, 10 MB by default, are not attached. +4. Click :material-send-variant-outline: **Send the message**, or press ++enter++. + +The Companion receives the context of the current view with every message: the view, the application view, the selected resources and graphs. +Click the context tag below the input field, for example `explore-instance`, to see what is sent. +The same tag appears on each sent message. + +While the Companion works, a status such as **Thinking** or **Working** is shown above the mode selector. +Click **Stop** to interrupt the answer. + +## Modes + +The mode decides which tool calls of the Companion run on their own, which need a confirmation, and which are declined. +Select the mode in the drop-down list above the input field. +A new chat starts in **Read only**. + +![Mode selector of the Companion with the available modes](companion-modes.png){ class="bordered" width="40%" } + +| Mode | Behavior | +| --- | --- | +| **Read here only** | The Companion reads data in this Corporate Memory deployment and does not change anything. Tools that reach outside the deployment, such as a web search or an external MCP server, are declined. | +| **Read only** | The Companion reads data, also with tools that reach outside the deployment, and does not change anything. | +| **Ask before writes** | The Companion reads data and asks for a confirmation before each change. | +| **Plan first** | The Companion writes a plan and presents it for approval before it changes anything. | +| **Execute** | The Companion runs changes without asking for a confirmation. | + +A mode that is selected while a chat is open applies with the next message. +Until then, **with next message** is shown next to the mode selector. + +### Confirm a change + +In **Ask before writes**, and after a plan was approved with **Approve, ask before writes**, the Companion opens a confirmation dialog for each change. +The dialog names the tool, marks it with **Changes or deletes data** and shows the parameters of the tool call. + +![Confirmation dialog for a change to a resource proposed by the Companion](companion-confirm-change.png){ class="bordered" width="50%" } + +1. Check the parameters of the change. + Expand a parameter to see its full value, or turn on **Show all as JSON**. + For a change to a resource, the dialog can instead list the values that the change adds and removes. + Clear the checkbox of each value that must not be written. +2. Click **Confirm** to run the change, or **Decline** to reject it. + +After **Decline**, the Companion waits for a message that says what to do instead. + +### Approve a plan + +In **Plan first**, the Companion reads what it needs and presents a plan. +Tools that write are not available until the plan is approved. + +- Click **Approve** to execute the plan without further confirmations. +- Click **Approve, ask before writes** to execute the plan with a confirmation for each change. +- Click **Decline** to reject the plan, and optionally give a reason so that the Companion revises it. + +The approval switches the chat to the mode that executes the plan. +While the plan runs, the Companion shows the progress of its tasks, for example `Tasks: 2/5`. + +## Answers + +![Companion answer with Build projects and Marketplace packages](companion-answer.png){ class="bordered" width="60%" } + +Each answer names the agent that wrote it and the model that it used, for example `domain_expert · anthropic/claude-sonnet-5`. +The Companion hands a question over to the agent that fits it, so the agent can change within a chat. + +An answer can contain the following interactive elements: + +Tool calls +: :eccenca-item-wrench: shows how many tool calls of the answer are finished, for example `4/4`. + A declined tool call is marked in red. + +Resources +: Click a resource to open it in :eccenca-application-explore: **Knowledge Graphs**. + +Queries +: Click :eccenca-item-copy: **Copy the query** to copy the query to the clipboard. + Click :eccenca-application-queries: **Open in Query Editor** to open the query in the **Queries** module. + +Build projects, Build tasks and Marketplace packages +: These items are shown as tags. + +To reuse a sent message, click :eccenca-item-edit: **Use as draft** next to its time. +The text of the message replaces the text in the input field. + +## Tools + +The Companion uses tools to read and change data in Corporate Memory, see [Tools](../index.md#tools). +Each agent uses only the tools that are configured for it in [Companion Management](../management/index.md). diff --git a/docs/explore-and-author/companion/index.md b/docs/explore-and-author/companion/index.md index bec85c07e..e3b004c11 100644 --- a/docs/explore-and-author/companion/index.md +++ b/docs/explore-and-author/companion/index.md @@ -1,10 +1,12 @@ --- +title: "Companion: Foundations" icon: eccenca/application-ai-suggestion status: new tags: - Reference + - Configuration --- -# Companion AI chat +# Companion !!! info "AI Disclaimer" @@ -12,141 +14,122 @@ tags: AI-generated content may be inaccurate or incomplete. Verify important information. -The Companion is a chat panel in Explore that answers questions about the data in eccenca Corporate Memory and, on request, changes it. -It reads the view that is open, works with graphs, resources, queries, Build projects and Marketplace packages, and asks for a confirmation before it writes anything that the selected mode does not allow on its own. +The Companion is the AI assistant of eccenca Corporate Memory. +It answers questions about the data in Corporate Memory and, on request, changes it. +Users talk to it in a chat panel in Explore. +Administrators configure its agents, skills and models in the **Companion Management** module. -## Configuration - -A specific configuration is required to activate this feature. -The deployment templates (helm charts and docker-compose configurations) provide tested configuration profiles for different LLM providers. - -!!! info "Configuration" +
- See [`spring.ai.*` configuration properties in _Configuration of Servlet Container_](../../deploy-and-configure/configuration/explore/dataplatform/application-full.md#configuration-of-servlet-container) to learn how to enable and configure this feature. - Explore uses _Spring AI_ to connect and configure LLM provider, as such the [Spring AI Chat Model API Configuration Reference](https://docs.spring.io/spring-ai/reference/api/chatmodel.html) applies. +- :eccenca-application-ai-suggestion: [Companion AI chat](chat/index.md) -For optimal results, use Anthropic or OpenAI frontier-level models configured through the native Spring AI provider setup. + --- -Access to the Companion is granted through the action `https://vocab.eccenca.com/auth/Action/Explore-Companion-Use`. -Agents, skills and models of the Companion are configured in **Companion management** in the **admin** section of the main navigation. + Ask questions, refer to resources and skills, select a mode and confirm the changes that the Companion proposes. -## Open the Companion +- :eccenca-application-ai-suggestion: [Companion Management](management/index.md) -Click :eccenca-application-ai-suggestion: **Chat with the companion** in the application header, next to the :eccenca-application-useraccount: user menu. -The Companion panel opens on the right side of the screen. -Click the button again to close the panel. + --- -![Companion panel next to a resource in Explore](companion-anatomy.png){ class="bordered" width="70%" } + Inspect the agent network, edit agents, skills and named models, check the available tools and manage the conversations of all users. -The panel contains: +
-- **Chats** to switch to an earlier chat, search for a chat, rename it with :eccenca-item-edit: or delete it with :eccenca-item-remove: -- :eccenca-item-add-artefact: **New chat** to start a new chat -- **Wide view** and **Narrow view** to change the width of the panel -- The messages of the current chat -- The mode selector, see [Modes](#modes) -- The context tag, which names the view the Companion sees -- The input field with :eccenca-item-upload: **Attach a file** and :material-send-variant-outline: **Send the message** +## How the Companion works -## Ask a question +A message travels through several agents before an answer reaches the user. +Each agent has its own instructions, its own tools and a named model that runs it. +All agents, skills and named models are stored in a catalog. -1. Enter a question in the **Ask the companion** field. -2. Optionally, refer to a resource or a skill: - - Enter `@` followed by the beginning of a label to search for a resource in the open graph, then select the resource from the list. - - Enter `/` to list the skills, then select a skill, for example `/summarize_graph`. -3. Optionally, click :eccenca-item-upload: **Attach a file** to add one or more files to the message, or drop them on the panel. - Files larger than the configured limit, 10 MB by default, are not attached. -4. Click :material-send-variant-outline: **Send the message**, or press ++enter++. +### Agents -The Companion receives the context of the current view with every message: the view, the application view, the selected resources and graphs. -Click the context tag below the input field, for example `explore-instance`, to see what is sent. -The same tag appears on each sent message. +Agents answer, route and work. +The kind of an agent decides what it may do, and it cannot be changed after the agent is created: -While the Companion works, a status such as **Thinking** or **Working** is shown above the mode selector. -Click **Stop** to interrupt the answer. +Routing agents +: Read the first message of a conversation and hand it to the interactive agent that fits it best. + Routing agents connect the application views to the Companion and run on a fast model. -## Modes +Interactive agents +: Fulfill a role, such as `domain_expert` or `knowledge_graph_expert`, and answer the user. + An interactive agent may hand the conversation over to another interactive agent and may start task agents. + Each answer in the chat names the agent that wrote it. -The mode decides which tool calls of the Companion run on their own, which need a confirmation, and which are declined. -Select the mode in the drop-down list above the input field. -A new chat starts in **Read only**. +Task agents +: Do a self-contained piece of work for an interactive agent and return the result. + Task agents cannot start further agents. -![Mode selector of the Companion with the available modes](companion-modes.png){ class="bordered" width="40%" } +Auxiliary agents +: Run jobs for the system itself, such as naming a conversation or assessing a change. + Auxiliary agents take no part in the handovers of a conversation. -| Mode | Behavior | -| --- | --- | -| **Read here only** | The Companion reads data in this Corporate Memory deployment and does not change anything. Tools that reach outside the deployment, such as a web search or an external MCP server, are declined. | -| **Read only** | The Companion reads data, also with tools that reach outside the deployment, and does not change anything. | -| **Ask before writes** | The Companion reads data and asks for a confirmation before each change. | -| **Plan first** | The Companion writes a plan and presents it for approval before it changes anything. | -| **Execute** | The Companion runs changes without asking for a confirmation. | +### Named models -A mode that is selected while a chat is open applies with the next message. -Until then, **with next message** is shown next to the mode selector. +Agents do not reference a model of a provider directly. +They reference a named model, such as `fast`, `default` or `expert`. +A named model points at a model of a provider and sets the parameters it runs with, for example the reasoning effort. +An installation can therefore exchange a model without changing the agents. -### Confirm a change +### Skills -In **Ask before writes**, and after a plan was approved with **Approve, ask before writes**, the Companion opens a confirmation dialog for each change. -The dialog names the tool, marks it with **Changes or deletes data** and shows the parameters of the tool call. +A skill is a prompt that a user calls by entering a slash and the name of the skill in the chat, for example `/summarize_graph`. +The text after the name of the skill is passed to the prompt. -![Confirmation dialog for a change to a resource proposed by the Companion](companion-confirm-change.png){ class="bordered" width="50%" } +### Catalog -1. Check the parameters of the change. - Expand a parameter to see its full value, or turn on **Show all as JSON**. - For a change to a resource, the dialog can instead list the values that the change adds and removes. - Clear the checkbox of each value that must not be written. -2. Click **Confirm** to run the change, or **Decline** to reject it. +A catalog is a graph that holds the agents, skills, named models and catalog properties of the Companion. +The main catalog graph is `https://ns.eccenca.com/data/companion/`. +It can import further catalog graphs with `owl:imports`. +The Companion runs on the effective catalog, which merges the main catalog and its imports. +When an identifier exists in more than one catalog, the entry of the main catalog applies. -After **Decline**, the Companion waits for a message that says what to do instead. +Until the catalog is saved for the first time, the Companion uses the catalog shipped with Corporate Memory. -### Approve a plan +### Application views -In **Plan first**, the Companion reads what it needs and presents a plan. -Tools that write are not available until the plan is approved. +The context of a message includes the application view in which the chat is open. +Agents and skills can be restricted to specific application views. +An agent or skill without such a restriction is available in every application view. -- Click **Approve** to execute the plan without further confirmations. -- Click **Approve, ask before writes** to execute the plan with a confirmation for each change. -- Click **Decline** to reject the plan, and optionally give a reason so that the Companion revises it. +### Tools -The approval switches the chat to the mode that executes the plan. -While the plan runs, the Companion shows the progress of its tasks, for example `Tasks: 2/5`. +The Companion uses tools to read and change data in Corporate Memory. +The tools are provided by the Model Context Protocol (MCP) servers of the Corporate Memory components and are named after them: -## Answers +| Prefix | Tools for | +| --- | --- | +| `cmem_explore-` | Graphs, vocabularies, resources, SHACL shapes and validation, queries and the query catalog | +| `cmem_build-` | Build projects, datasets, transformations, workflows and project resources | +| `cmem_marketplace-` | Marketplace packages and package manifests | -![Companion answer with Build projects and Marketplace packages](companion-answer.png){ class="bordered" width="60%" } +Each tool declares whether it reads or changes data. +A tool that declares nothing counts as changing data. +Each agent uses only the tools that match the tool patterns configured for it. +External MCP servers can be added through the [MCP client configuration](../../deploy-and-configure/configuration/explore/dataplatform/application-full.md#configuration-of-mcp-server). -Each answer names the agent that wrote it and the model that it used, for example `domain_expert · anthropic/claude-sonnet-5`. -The Companion hands a question over to the agent that fits it, so the agent can change within a chat. +### Modes -An answer can contain the following interactive elements: +The mode of a chat decides which tool calls run on their own, which need a confirmation and which are declined. +A new chat starts in **Read only**. +See [Modes](chat/index.md#modes) for the available modes. -Tool calls -: :eccenca-item-wrench: shows how many tool calls of the answer are finished, for example `4/4`. - A declined tool call is marked in red. +## Configuration -Resources -: Click a resource to open it in :eccenca-application-explore: **Knowledge Graphs**. +A specific configuration is required to activate the Companion. +The deployment templates (helm charts and docker-compose configurations) provide tested configuration profiles for different LLM providers. -Queries -: Click :eccenca-item-copy: **Copy the query** to copy the query to the clipboard. - Click :eccenca-application-queries: **Open in Query Editor** to open the query in the **Queries** module. +!!! info "Configuration" -Build projects, Build tasks and Marketplace packages -: These items are shown as tags. + See [`spring.ai.*` configuration properties in _Configuration of Servlet Container_](../../deploy-and-configure/configuration/explore/dataplatform/application-full.md#configuration-of-servlet-container) to learn how to enable and configure this feature. + Explore uses _Spring AI_ to connect and configure LLM provider, as such the [Spring AI Chat Model API Configuration Reference](https://docs.spring.io/spring-ai/reference/api/chatmodel.html) applies. -To reuse a sent message, click :eccenca-item-edit: **Use as draft** next to its time. -The text of the message replaces the text in the input field. +For optimal results, use Anthropic or OpenAI frontier-level models configured through the native Spring AI provider setup. -## Tools +## Access -The Companion uses tools to read and change data in Corporate Memory. -The tools are provided by the MCP servers of the Corporate Memory components and are named after them: +Two actions grant access to the Companion: -| Prefix | Tools for | -| --- | --- | -| `cmem_explore-` | Graphs, vocabularies, resources, SHACL shapes and validation, queries and the query catalog | -| `cmem_build-` | Build projects, datasets, transformations, workflows and project resources | -| `cmem_marketplace-` | Marketplace packages and package manifests | +- `https://vocab.eccenca.com/auth/Action/Explore-Companion-Use` grants access to the chat. +- `https://vocab.eccenca.com/auth/Action/Explore-Companion-Manage` grants access to **Companion Management**. -Each agent of the Companion uses only the tools that are configured for it in **Companion management**. -External MCP servers can be added through the [MCP client configuration](../../deploy-and-configure/configuration/explore/dataplatform/application-full.md#configuration-of-mcp-server). +Assign the actions to a user group in an [access condition](../../deploy-and-configure/configuration/access-conditions/index.md). diff --git a/docs/explore-and-author/companion/management/companion-management-agent-network.png b/docs/explore-and-author/companion/management/companion-management-agent-network.png new file mode 100644 index 000000000..7aabcc729 Binary files /dev/null and b/docs/explore-and-author/companion/management/companion-management-agent-network.png differ diff --git a/docs/explore-and-author/companion/management/companion-management-agent.png b/docs/explore-and-author/companion/management/companion-management-agent.png new file mode 100644 index 000000000..34584ab5e Binary files /dev/null and b/docs/explore-and-author/companion/management/companion-management-agent.png differ diff --git a/docs/explore-and-author/companion/management/companion-management-catalog.png b/docs/explore-and-author/companion/management/companion-management-catalog.png new file mode 100644 index 000000000..b0cd1d10a Binary files /dev/null and b/docs/explore-and-author/companion/management/companion-management-catalog.png differ diff --git a/docs/explore-and-author/companion/management/index.md b/docs/explore-and-author/companion/management/index.md new file mode 100644 index 000000000..d3a6d0d07 --- /dev/null +++ b/docs/explore-and-author/companion/management/index.md @@ -0,0 +1,202 @@ +--- +title: "Companion: Management" +icon: eccenca/application-ai-suggestion +status: new +tags: + - Configuration +--- +# Companion Management + +!!! info "AI Disclaimer" + + Companion is an AI-based feature. + AI-generated content may be inaccurate or incomplete. + Verify important information. + +The **Companion Management** module configures the Companion of eccenca Corporate Memory. +It shows how agents route a request, holds the catalog of agents, skills and named models, lists the tools an agent can call and keeps the conversations of all users. +The concepts behind these entries are explained in [How the Companion works](../index.md#how-the-companion-works). + +## Prerequisites + +- The Companion is configured for the deployment, see [Configuration](../index.md#configuration). +- The user has the action `https://vocab.eccenca.com/auth/Action/Explore-Companion-Manage`, see [Access](../index.md#access). + +## Open Companion Management + +Click :eccenca-application-ai-suggestion: **Companion management** under **ADMIN** in the main navigation. +The module opens with four tabs: + +- **Agent network** +- **Catalog** +- **Tools** +- **History** + +## Agent network + +The **Agent network** tab shows every path a request can take, not a single conversation. +A request travels from an application view through a routing agent to an interactive agent and back to the user. +Task agents and auxiliary agents are shown below, the graphs that no agent focuses on are shown as **Standalone graphs**. + +![Agent network with application views, routing, interactive, task and auxiliary agents](companion-management-agent-network.png){ class="bordered" } + +Each agent node shows the label, the id and the named model of the agent, for example `domain_expert` with `default`. + +- Select **By kind** or **By catalog** to group the nodes by the kind of agent or by the catalog that holds them. +- Click a node to highlight what it reaches. + Click **Clear selection** to remove the highlight. +- Click **Go to the agent definition** on an agent node to open the agent in the **Catalog** tab. + +## Catalog + +The **Catalog** tab holds the entries of the catalog in four tabs: + +- **Catalogs** +- **Agents** +- **Skills** +- **Models** + +Each tab lists the entries on the left and shows the selected entry on the right. +Enter a search term above the list to filter it. + +![Catalogs tab of Companion Management with the catalog status](companion-management-catalog.png){ class="bordered" } + +### Catalogs + +The **Catalog graphs** list shows the main catalog graph and the catalog graphs it imports. +Select a catalog graph to see its **Catalog status**: + +- **Health** of the catalog, for example `Healthy` +- **Main catalog graph** +- **Loaded at**, the time the catalog was last loaded +- **Catalog hash** +- **Entries**, the number of agents, skills and named models + +The list contains only the catalog graphs that the current user can read. +The Companion reads the catalog as administrator, so it also uses catalog graphs that are missing from the list. + +The following actions apply to the selected catalog graph: + +- Click **Export** to download the catalog. +- Click **Import** to load a catalog from a file. +- Click **Reload catalog** to load the catalog from the graph again. +- Click **Add a new catalog** in the header to add a catalog graph. + +!!! warning + + **Reset to the shipped catalog** replaces the catalog with the catalog shipped with Corporate Memory. + Changes made to agents, skills and named models are lost. + +### Agents + +The **Agents** tab lists the agents grouped by kind: **Routing agents**, **Interactive agents**, **Task agents** and **Auxiliary agents**. + +![Agents tab of Companion Management with the Domain Expert agent selected](companion-management-agent.png){ class="bordered" } + +- Select an agent to edit it. +- Click :eccenca-item-clone: **Clone** to create a copy of an agent with a new identifier, in a catalog of choice. +- Click :eccenca-item-edit: **Rename** to change the identifier of an agent. +- Click :eccenca-item-remove: **Delete** to delete an agent. +- Click **Add a new agent** in the header to create an agent. + +The kind of an agent is set when the agent is created and cannot be changed afterwards. +To change the kind, delete the agent and create it again. + +An agent has the following fields: + +- **Id:** the identifier of the agent in lowercase letters, digits and underscores, which is changed only with **Rename** +- **Label** +- **Description:** used as the description of the handoff or subagent tool through which other agents call it +- **Model:** the named model the agent runs on, for example `default` +- **System message:** the instructions of the agent as a Jinja template. + The properties of the conversation are available on the `conversation` object. + Expand **Preview system message** to see the rendered message. +- **Application views (optional):** the application views on which the agent is available. + Without an entry, the agent is available on every application view. +- **Available tool patterns (optional):** glob patterns of the tools the agent may use, for example `cmem_explore-*`. + A pattern without `*` is an exact tool name. + The constraints **Read-only**, **Destructive**, **Idempotent** and **Open world** narrow an entry to the tools that declare these hints. + Without an entry, the agent uses every tool of the application view. +- **Activity verbs (optional):** the words shown in the chat while the agent works, for example `Looking up` or `Querying` +- **Task agents (optional):** the task agents this agent may start +- **Handoff agents (optional):** the interactive agents this agent may hand the conversation to +- **Own personality**, **Own output instructions** and **Own resources rendering:** switches that keep the personality, the output instructions and the resources overview of the catalog out of the system message of this agent +- **Focus graphs (optional):** the graphs the agent focuses on, rendered into an overview for its system message +- **Disabled:** switches the agent off + +Click **Try it** to test the agent. + +### Skills + +The **Skills** tab lists the skills with their name, for example `/summarize_graph`. +A skill has the following fields: + +- **Id:** the identifier of the skill, which is changed only with **Rename** +- **Name:** the name the user enters after the slash +- **Description** +- **Prompt:** a Jinja template. + The text the user enters after the name of the skill is passed to it. +- **Application views (optional):** the application views on which the skill is available +- **Scripts (optional):** supplementary JavaScript stored with the skill +- **Model override (optional):** a named model that replaces the model of the agent. + A switch of the model prevents prompt caching, so leave this field empty unless the skill needs a different model. +- **Disabled:** switches the skill off + +Click **Add a new skill** in the header to create a skill. +The list offers :eccenca-item-clone: **Clone**, :eccenca-item-edit: **Rename** and :eccenca-item-remove: **Delete** as for agents. + +### Models + +The **Models** tab lists the named models, for example `fast`, `default` and `expert`. +A named model has the following fields: + +- **Name:** the name agents reference, in lowercase letters, digits and underscores +- **Provider:** `configured default` uses the provider and the model of the application configuration +- **Model**, **Temperature**, **Max tokens**, **Top P** and **Reasoning effort:** the parameters the model runs with + +Click **Test model** to test the named model. +Click **Add a new named model** in the header to create a named model. + +### Save changes + +Changes to catalogs, agents, skills and named models are collected until they are saved. +**Save changes** shows the number of unsaved changes, for example **Save changes (2)**. + +- Click :eccenca-operation-undo: **Undo** or :eccenca-operation-redo: **Redo** to step through the unsaved changes. +- Click **Discard changes** to drop all unsaved changes. +- Click **Save changes** to write the changes into the catalog graph. + +As long as the catalog has not been saved, the Companion uses the catalog shipped with Corporate Memory. +The first save writes the catalog into the main catalog graph. + +## Tools + +The **Tools** tab lists the tools an agent can call, grouped by MCP server, for example **build** with the prefix `cmem_build-*`. +Each tool shows its description, its arguments and the hints it declares about itself, such as `read`, `write` or `open world`. +A required argument is marked with `*`. + +A tool that declares no hints counts as changing data, so the Companion asks for a confirmation before it runs the tool. + +- Enter a term in **Search tools** to filter the list. +- Click **What this server says about its tools** to read the full description of a server. +- Click **Try it out** to call a tool. + +## History + +The **History** tab lists **All interactions** of all users with the Companion. +Each entry shows the title, the user, the agent, the number of messages and the time of the last message. + +Filter the list with the following fields: + +- **Search by name** +- **User:** the account name +- **From** and **To:** the time range +- **Kind:** `Conversations`, `Agent previews` or `System runs` + +The following actions apply to a single entry: + +- Click **Open** to read the conversation. +- Click **Export** to download the conversation. +- Click **Delete** to delete the conversation. + +Click **Back up all** to download all interactions, and **Restore** to load them from a backup. diff --git a/docs/explore-and-author/index.md b/docs/explore-and-author/index.md index 354de2479..ffc1ba344 100644 --- a/docs/explore-and-author/index.md +++ b/docs/explore-and-author/index.md @@ -49,11 +49,12 @@ You will also learn how we make use of [SHACL Shapes](https://www.w3.org/TR/sha The Charts module provides a user interface to define and manage visualizations of your query results and to integrate them into your shape configurations. -- :eccenca-application-ai-suggestion: [Companion AI chat](companion/index.md) +- :eccenca-application-ai-suggestion: [Companion](companion/index.md) --- - The Companion AI chat allows you to interact with your graphs, vocabularies, resources and queries in a chat-like way. + The Companion is the AI assistant of Corporate Memory. + Users ask questions and request changes in the [Companion AI chat](companion/chat/index.md), administrators configure agents, skills and models in [Companion Management](companion/management/index.md). - :eccenca-module-integrations: [Service integrations](embedding-services-via-the-integrations-module/index.md) diff --git a/nav.yml b/nav.yml index 13922b63a..645590574 100644 --- a/nav.yml +++ b/nav.yml @@ -548,8 +548,12 @@ nav: - explore-and-author/thesauri-management/index.md - Charts: - explore-and-author/charts-catalog/index.md - - Companion AI chat: - - explore-and-author/companion/index.md + - Companion: + - Companion: explore-and-author/companion/index.md + - AI chat: + - explore-and-author/companion/chat/index.md + - Management: + - explore-and-author/companion/management/index.md - Services integrations: - explore-and-author/embedding-services-via-the-integrations-module/index.md - Link rules: