Installing KIO Co-Pilot

Last updated 16 minutes ago

Set up KIO Co-Pilot quickly and correctly.

Table of Contents

Prerequisites
Supported AI Models
Installing the KIO Co-Pilot Plugin
Setting up the KIO Co-Pilot Backend
- KIO Development Setup with local Studio-Server and Studio-Client
Actuator Endpoint
Extending the KIO Co-Pilot Backend via MCP Tools

The following instructions apply only to self-managed CoreMedia Content Cloud (CMCC) customers.

If you are using the CoreMedia Content Cloud – Service offering, you do not need to follow these setup steps.

Simply contact CoreMedia if you’re interested in using KIO Co-Pilot — we’ll handle the setup for you.

KIO Co-Pilot is a CoreMedia Studio feature that provides AI-based services through a copilot-style chat UI. It consists of a CoreMedia Studio Plugin and a Docker image for the backend service.

Prerequisites

CMCC v.2406.1.1 and higher or CMCC v.12.2412.0.1 and higher
CoreMedia account with SSO Login to access CoreMedia Container Registry and Repository
CoreMedia License with KIO Co-Pilot enabled
OpenAI API key for the default configuration (other LLM providers can be configured as well, see LLM Provider Configuration)

Supported AI Models

The KIO Co-Pilot backend uses Spring AI and supports different AI models. In the default configuration, described here, OpenAI models are used. For other supported models see Supported LLM Providers and Models.

In case you want to use other models, please get in touch with CoreMedia support.

Installing the KIO Co-Pilot Plugin

The Studio Plugin includes a Studio Client customization. It extends the CoreMedia Studio UI with new AI functions and connects to the Spring AI-based CoreMedia AI Service running on the same domain as Studio below the path "/kio".

To bundle this plugin with your application Docker images, you can provide plugin-descriptors in the plugin-descriptors directory or reference them as URLs in plugin-descriptors.json in the CoreMedia Blueprint workspace.

Find the latest KIO Co-Pilot Plugin Release on GitHub: coremedia-contributions/kio-plugin/releases.
Copy the URL of the file kio-plugin-x.y.z.json to the clipboard.
Go to workspace-configuration/plugins.

Add the URL of the plugin-descriptor to the plugin-descriptors.json file.

For example:

[
  "https://github.com/CoreMedia/content-hub-adapter-rss/releases/download/v2.0.5/content-hub-adapter-rss-2.0.5.json",
  "https://github.com/CoreMedia/content-hub-adapter-youtube/releases/download/v2.0.6/content-hub-adapter-youtube-2.0.6.json",
  "https://github.com/CoreMedia/feedback-hub-adapter-imagga/releases/download/v2.0.3/feedback-hub-adapter-imagga-2.0.3.json",
  "https://github.com/CoreMedia/pendo-plugin/releases/download/v2.2.0/pendo-tracking-plugin-2.2.0.json",
  "https://github.com/coremedia-contributions/kio-plugin/releases/download/v1.0.1/kio-plugin-1.0.1.json"
]

Execute mvn generate-resources.
Commit the changes.
Build the studio-server and studio-client applications.

You can find more information about bundling CoreMedia Plugins here.

Setting up the KIO Co-Pilot Backend

This example demonstrates configuration using OpenAI. For other LLM providers, please refer to the section LLM Provider Configuration.

By default, the KIO Co-Pilot backend is not enabled in the Blueprint deployment. However, for local docker setup, a prefabricated compose file lies in the Blueprint workspace in global/deployment/docker/compose/development-kio.yml. This is used to deploy the KIO Co-Pilot Backend.

Note: The deployment file development-kio.yml is available with CMCC versions 2406.1.2, 2412.0.2 or higher. In case you are running an older version you can find the file in coremedia-contributions/coremedia-blueprints-workspace.

Pull the latest KIO Co-Pilot Backend image:

Use your CoreMedia credentials to log in to the CoreMedia Container Registry and pull the latest KIO Co-Pilot backend image. Choose your docker image tag from the list of available tags: KIO Docker image tags or go to CoreMedia Repository and search for `coremedia/kio-editorial-backend.
```
docker login container-registry.coremedia.com

docker pull container-registry.coremedia.com/coremedia/kio-editorial-backend:IMAGE_TAG
```

To enable the KIO Co-Pilot backend, you need to configure it in your .env file as follows:

# Include the KIO Co-Pilot Backend Compose File
COMPOSE_FILE=$COMPOSE_FILE:compose/development-kio.yml

# KIO Backend Version needs to be compatible with the KIO Plugin Version
KIO_VERSION=CONFIGURE_ME

# Profile for development
KIO_SPRING_PROFILES_ACTIVE=dev

# Configure your OpenAI API Key
# You can get an API Key from https://platform.openai.com/account/api-keys
# Permissions: Models: Read, Model capabilities: Write
KIO_OPENAI_API_KEY=CONFIGURE_ME

# Configure the github repository for access to CoreMedia default playbooks.
# To configure this, you need to create a personal access token on GitHub (https://github.com/settings/tokens) and grant it access to the repository ("repo" scope).
KIO_GITHUB_TOKEN=CONFIGURE_ME

Change the directory:
```
cd global/deployment/docker
```
To list the services that will be started execute the following command:
```
docker compose config --services
```
To start the services execute the following command:
```
docker compose up -d
```
Open http://studio.docker.localhost/ and you should see the KIO Co-Pilot icon in the bottom right corner. Click it to start a conversation with KIO.

For general information about the docker compose setup, please refer to the Blueprint Developer Manual - Docker Compose Setup.

KIO Development Setup with local Studio-Server and Studio-Client

You have already set up your local CoreMedia Studio development environment using the Blueprint workspace. That means you can run your Studio-Server and Studio-Client locally with the KIO Plugin installed as described in the section Installing the KIO Co-Pilot Plugin.

The KIO Backend also needs to run locally as it needs access to the local Studio-Server instance.

To integrate KIO Co-Pilot into your local CoreMedia Studio development setup, follow these steps:

Run the KIO Backend Docker Container locally:

docker run \
  -e "SPRING_PROFILES_ACTIVE=dev" \
  -e "SERVER_PORT=8000" \
  -e "STUDIO_REST_URL=http://host.docker.internal:3000/rest/api" \
  -e "REPOSITORY_URL=http://CMS_HOST:40180/ior" \
  -e "SPRING_AI_OPENAI_APIKEY=CONFIGURE_ME" \
  -p 8000:8000 \
  container-registry.coremedia.com/coremedia/kio-editorial-backend:IMAGE_TAG

Note: You can also use docker compose or use an env-file to pass the configuration properties.

Add the following settings to your local Studio-Server:
```
server.servlet.session.cookie.path=/
server.servlet.context-path=/rest
```
Restart your local Studio-Server after applying these changes. Launch it either directly from your IDE or via Maven from the commandline by calling mvn spring-boot:run in module studio-server-app.

Start the Studio-Client:

cd apps/studio-client

pnpm -r --filter "@coremedia-blueprint/studio-client.studio" run start  --proxyTargetUri=http://localhost:8000 --proxyPathSpec=/kio --proxyTargetUri=http://localhost:41080/rest --proxyPathSpec=/rest

Open http://localhost:3000/ and you should see the KIO Co-Pilot icon in the bottom right corner. Click it to start a conversation with KIO. KIO Co-Pilot should answer and be able to access content.

Actuator Endpoint

The KIO Co-Pilot backend provides an actuator endpoint /actuator/kio to get basic information about the application.

Extending the KIO Co-Pilot Backend via MCP Tools

The KIO Co-Pilot backend can be extended by tools provided via an MCP server. The Model Context Protocol is a standardized protocol that enables AI models to interact with external tools. KIO Co-Pilot supports the Servlet-based SSE server transport to access the external servers. The MCP server itself is not provided or hosted by CoreMedia.

You can use this mechanism to integrate custom tools. For example, if you want to provide your company documentation to KIO Co-Pilot, you can do so by providing an MCP server that can perform a full-text search within this documentation. There are various frameworks on the market that can create an MCP server for an existing service.

You can simply add the MCP server via a configuration property to the KIO Co-Pilot backend. Below is an example configuration provided for the company documentation of a fictional company Acme:

spring.ai.mcp.client.sse.connections.acmedoc.url=https://<mcp-server-host>:<mcp-server-port>

A corresponding configuration using environment variables would look like this. It can be added to the .env file:

SPRING_AI_MCP_CLIENT_SSE_CONNECTIONS_ACMEDOC_URL=https://<mcp-server-host>:<mcp-server-port>

These services must be accessible when the KIO Co-Pilot backend is started. If these services become temporarily unavailable, the KIO Co-Pilot backend cannot reconnect to the MCP service. If an MCP service has been restarted, the KIO Co-Pilot backend must also be restarted. Unfortunately, this is currently a shortcoming in Spring AI, as this implementation is unable to update the session ID from a newly started MCP service.

Check the KIO Co-Pilot backend log for the corresponding error messages.

Is this page useful?