Installing KIO Co-Pilot

Last updated 12 minutes ago

Set up KIO Co-Pilot quickly and correctly.

Table of Contents

Prerequisites
Validated AI Models
Installing or Updating 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)

Validated 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 validated models see Validated AI Providers and LLM Models.

Validated models are continuously tested by CoreMedia. KIO Co-Pilot will run the most stable when using one of them.

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

Installing or Updating 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.
If you update the KIO Co-Pilot Plugin version, clean the studio-client workspace.
Build the studio-client application.

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 search in the CoreMedia Repository.
```
docker login container-registry.coremedia.com

docker pull container-registry.coremedia.com/applications/kio-editorial-backend:IMAGE_TAG
```
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
```

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 or Updating 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/applications/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 both the (legacy) HTTP+SSE server transport and the Streamable HTTP 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, using the Streamable HTTP transport, which is the recommended transport for new MCP server integrations:

spring.ai.mcp.client.streamable-http.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_STREAMABLE_HTTP_CONNECTIONS_ACMEDOC_URL=https://<mcp-server-host>:<mcp-server-port>

If your MCP server only supports the legacy HTTP+SSE transport, use the sse connection properties instead:

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

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?