notice

This is documentation for Rasa X/Enterprise Documentation v1.0.x, which is no longer actively maintained.
For up-to-date documentation, see the latest version (1.4.x).

Version: 1.0.x

Connect Rasa Open Source to Rasa X

Connect a Rasa Open Source Server

In order to collect incoming conversations and interact with your running bot in the UI, you will need to connect your deployment to a Rasa Open Source server.

By default, rasactl installs only Rasa X without a Rasa Open Source server. If you are using the Rasa X Helm chart, it is still recommended to connect an external Rasa Open Source server as your production server. Future versions of the Rasa X Helm chart will default to disabling the integrated Rasa Open Source servers.

Connection Types

A Rasa Open Source server can be connected to Rasa X for two purposes:

  1. To stream conversations to Rasa X. This requires connection via the event broker.
  2. To act as a deployment environment. This requires connection via the event broker and additional configuration.

These purposes are not mutually exclusive. All deployment environments will also stream conversations into Rasa X and a Rasa Open Source server that is used only to stream conversations can later be added as a deployment environment as well.

Event Broker Connection

For the purpose of collecting incoming conversations with the bot, the only requirement is that the Rasa Open Source server must be connected to the same event broker as Rasa X.

If you have historical conversations from an existing Rasa Open Source deployment, you can also export them into Rasa X via the event broker..

Deployment Environment Connection

In order to interact with your bot in the UI, in addition to sharing the same event broker, the Rasa Open Source server must be configured as a deployment environment. There are two default deployment environments:

  • The production deployment environment is used to talk to or share your bot using Rasa X.
  • The worker deployment environment is used to calculate Intent Insights and to train a model

In Rasa Enterpise, you can add additional deployment environments besides production and worker.

Connect a Local Rasa Open Source Server

If you installed Rasa X on KIND using rasactl, you have the option to connect a locally running Rasa Open Source server to a Rasa X deployment on the same machine.

To use this option, Rasa must be installed on your local machine and the version must be compatible with the version of Rasa X you have deployed. Please consult the compatibility matrix to check that your installed version is compatible.

Once Rasa is installed, you only need to run:

rasactl connect rasa

The command rasactl connect rasa starts a local Rasa Open Source server using the rasa command available in whichever Python environment is currently active. It provides the event broker endpoint configuration for your Rasa X deployment and updates your Rasa X deployment with the local address of the Rasa server. By default, the command will start a single server to be used as both the production and worker environments. You can use the flag --run-separate-worker to connect a separate Rasa Open Source server as the worker environment. See the rasactl CLI docs for more options.

Connect an External Rasa Open Source Server

Connection via the Event Broker

To send conversation from an existing Rasa Open Source deployment you have to connect Rasa Open Source and Rasa X to the same event broker.

Rasa X Event Broker Configuration

The event broker used by Rasa X must be able to receive events from the Rasa Open Source server. Depending on where the Rasa Open Source server is deployed relative to the Rasa X event broker, you may need to expose the port it runs on. If you are using an external event broker, you will need to configure access to it directly.

Rasa Open Source Event Broker Configuration

You will need to configure the endpoints.yml file read by your Rasa Open Source server with connection details for the Rasa X event broker. For example, if you are using RabbitMQ:

event_broker:
type: "pika"
url: <URL of the exposed RabbitMQ service in your Rasa X deployment>
port: 5672 # change if your RabbitMQ service is exposed on a different port
username: "user" # if customized, value of the RABBITMQ_USERNAME environment variable
password: <value of RABBITMQ_PASSWORD>
queues:
- "rasa_production_events" # if using a custom queue, change the queue name to the one that you use

If you are deploying Rasa Open Source using the Rasa Helm Chart, see the section on Rasa Helm chart configuration for an example of how to configure the event broker.

tip

If you’ve deployed Rasa X in a cluster using Helm, Kubernetes or OpenShift, check out Accessing Secrets to get the values needed to configure Rasa Open Source to stream events to the Rasa X event broker.

Connection as a Deployment Environment

To connect an external Rasa Open Source deployment as a Rasa X deployment environment, Rasa Open Source must be connected to the same event broker following the instructions above, and the Rasa Open Source deployment must be available to Rasa X. Under most circumstances that means your Rasa Open Source deployment needs to be available at an external endpoint. However, if you are using the Rasa Helm Chart and have deployed Rasa X in the same namespace as your Rasa Open Source deployment, you can use cluster-internal endpoints.

Rasa X Configuration

  1. Update the values for your Rasa X deployment with the endpoints for the external Rasa Open Source servers. The example below adds two separate Rasa Open Source servers, one for the worker environment and one for production.

    rasa:
    # token Rasa Open Source accepts as authentication token
    token: "<safe credential>"
    versions:
    # In the section below the "rasa-oss.example.com" is added
    # to the production environment.
    rasaProduction:
    external:
    enabled: true
    host: "https://rasa-oss.production.example.com"
    # In the section below the "rasa-oss.example.com" is added
    # to the worker environment.
    rasaWorker:
    external:
    enabled: true
    host: "https://rasa-oss.worker.example.com"
  2. Apply the configuration to the Rasa X deployment.

    helm -n <namespace> upgrade -f values.yaml --reuse-values rasa-x/rasa-x <your release name>
note

You can also use the Rasa X UI to add or modify connections to external Rasa Open Source deployments.

Rasa Helm Chart Configuration

In this section, you can learn how to configure a Rasa Open Source deployment that was deployed via the Rasa Helm chart to connect to Rasa X as a deployment environment.

The example below assumes the Rasa Open Source deployment is located in the same namespace as a Rasa X deployment, allowing it to access the same secrets and cluster-internal addresses that are available to the Rasa X deployment.

  1. Prepare the rasa-values.yaml file with the following configuration.

    Configure the Rasa Open Source deployment to refer to the event broker started by Rasa X and to use Rasa X as its model server:

    applicationSettings:
    rasaX:
    enabled: true
    # here you have to put the URL to your Rasa Enterprise instance
    url: "http://rasa-x-rasa-x.my-namespace.svc:5002"
    endpoints:
    # In order to send messages to the same
    # event broker as Rasa X/Enterprise does we can pass
    # a custom configuration.
    eventBroker:
    type: "pika"
    url: "rasa-x-rabbit.my-namespace.svc"
    username: "user"
    password: ${RABBITMQ_PASSWORD}
    port: 5672
    queues:
    - "rasa_production_events"
    # Use Rasa X as a model server
    models:
    enabled: true
    # User Rasa X/Enterprise token
    # If you use the Rasa X Helm chart you can set a token by using the `rasax.token` parameter
    # See: https://github.com/RasaHQ/rasa-x-helm/blob/main/charts/rasa-x/values.yaml#L22
    token: "rasaXToken"
    waitTimeBetweenPulls: 20
    useRasaXasModelServer:
    enabled: true
    # -- The tag of the model that should be pulled from Rasa X/Enterprise
    tag: "production"
    extraEnv:
    # The configuration for an event broker uses environment variables, thus
    # you have to pass extra environment variables that read values from
    # the rasa-x-rabbit secret.
    - name: "RABBITMQ_PASSWORD"
    valueFrom:
    secretKeyRef:
    name: rasa-x-rabbit
    key: rabbitmq-password
  2. Update the Rasa Open Source deployment.

    helm upgrade -n <namespace> -f values.yaml <RELEASE NAME> rasa/rasa

General Requirements for Deployment environments

The following requirements are automatically fulfilled if you are using the Rasa Helm Chart to deploy Rasa Open Source and follow the instructions specfic to that deployment method. For any other Rasa Open Source deployment method, the following settings are required:

  1. The environmental variable RASA_ENVIRONMENT must be set to the name of the environment e.g. production.

  2. The model server URL must match the target model tag endpoint of your Rasa X deployment. For example, if you are setting up a production environment:

endpoints.yml
models:
url: <Rasa-Enterprise-Base-URL>/api/projects/default/models/tags/production
token: ${RASA_X_TOKEN}
wait_time_between_pulls: 10
  1. The rasa channel credentials must point to your Rasa Enterprise deployment:
credentials.yml
rasa:
url: <Rasa-Enterprise-Base-URL>/api
  1. The server must be secured with an authentication token. You will need to provide this token to Rasa Enterprise when you add the server as a deployment environment.

Import Existing Conversations from Rasa Open Source

In order to annotate conversations users have already had with a live Rasa Open Source deployment, you can export existing conversations from your tracker store into Rasa X.

This also requires connection via the event broker, but instead of streaming incoming events, an independently running Rasa process exports historical events from the tracker store to Rasa X.

Because the process runs independently of any active Rasa Open Source servers, you will need to create a local endpoints.yml file containing the right settings for the Rasa X event broker, and for the tracker store from which you want to export conversations.

Rasa Open Source Event Broker Configuration

Follow the instructions for configuring the Rasa Open Source event broker to get the right settings and save them in a local endpoints.yml file. For example, if you are using RabbitMQ as the event broker, you should end up with an entry like this:

event_broker:
type: "pika"
url: <URL of the exposed RabbitMQ service in your Rasa X deployment>
port: 5672 # change if your RabbitMQ service is exposed on a different port
username: "user" # if customized, value of the RABBITMQ_USERNAME environment variable
password: <value of RABBITMQ_PASSWORD>
queues:
- "rasa_production_events" # if using a custom queue, change the queue name to the one that you use

Follow the intructions for exposing the RabbitMQ port if you are using RabbitMQ and it is not accessible on the machine where you are running the export command. If you are using Kafka or an external RabbitMQ instance as an event broker, you will need to configur access to it directly.

Rasa Open Source Tracker Store Configuration

Exporting conversations starts an independent Rasa process that reads from the tracker store. Therefore you will need to configure access to the tracker store containing your historical conversations by updating your local endpoints.yml file. For example:

# <event broker settings>
tracker_store:
type: sql # other databases are supported
dialect: <if using SQL, your Rasa Open Source deployment's SQL dialect, e.g. "postgresql">
url: <URL of the database service in your Rasa Open Source deployment>
username: <tracker database username in your Rasa Open Source deployment>
password: <tracker database password in your Rasa Open Source deployment>
db: <name of the tracker database in your Rasa Open Source deployment>

Follow the instructions for exposing the database port if your tracker store is not accessible on the machine where you are running the export command.

Export Conversations

You can use Rasa’s rasa export command-line tool to export conversations from the tracker database to an event broker. From there, your running Rasa X deployment will consume the events and save them to your Rasa X database.

Head to the same directory as your endpoints.yml file from above. To export all conversations contained in the tracker database, simply run

rasa export

The rasa export command allows you to specify a subset of conversation IDs to export, or restrict the time range of events. Run rasa export --help for an overview of options, or check out the Rasa CLI docs on rasa export.

You can now log in to your Rasa X deployment and view the exported conversations.

Exposing Ports

Exposing the RabbitMQ Port

Before RabbitMQ can accept external events, you need to expose the port to the outside world. Depending on your chosen deployment method, read one of the following sections.

Rasa Ephemeral Installer or Helm Chart Deployment

Follow these instructions if you’ve deployed Rasa X using the Rasa Ephemeral Installer or the Rasa X Helm chart.

First, configure your values to expose a RabbitMQ service on an external address using a LoadBalancer resource:

rabbitmq:
service:
type: "LoadBalancer"

Upgrade your deployment using the new configuration:

helm -n <namespace> upgrade -f values.yaml --reuse-values rasa-x/rasa-x <your release name>

Next, get an external IP address for the RabbitMQ service by executing command:

kubectl -n <namespace name> get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'

Use the external IP address in the event_broker section of your endpoints.yml. Make sure that your cluster or VM firewall settings allow traffic to port 5672.

Once you’re done importing historical conversations, or you no longer want to stream events to your Rasa X deployment, you can remove the RabbitMQ load balancer by applying the following configuration:

rabbitmq:
service:
type: "ClusterIP"

Exposing the Database Port

If you’re following the steps on importing historical conversations on a machine that’s different from where you’ve deployed Rasa Open Source, you need to make the database accessible from the outside world. How to open your database port depends on the way you deployed Rasa Open Source, but following similar steps as in Exposing the RabbitMQ Port is a good start if you’ve deployed Rasa Open Source alongside a database container using Docker Compose or Kubernetes.