Platform Core

Bridge Application

The bridge runs conversations against a Promethist application automatically, so an agent can be tested end to end without a person holding the conversation.

A bridge run puts two conversational parties in touch and shuttles audio, text and screen content between them:

Tester

An agent running on the engine — usually a TestAgent — that plays the role of the user. The bridge connects to it over the engine’s Socket.IO pipeline and speaks on its behalf.

Tested application

What is being tested. That can be the real mobile app on a physical or virtual device, the web client in a browser, or another engine session standing in for the client. The bridge sends the tester’s utterances to it, and returns its audio and its screen back to the tester.

Because the tester is itself an agent, the conversation is a real conversation: the tester decides what to say next from what it hears and sees, and the run ends when the tester decides the test is over — or when a limit is reached.

What a Run Produces

Every run is recorded as a BridgeRun document with a Passed / Failed verdict, the reason, the final screenshot, the engine session ID, and — once the engine has finished evaluating the conversation — the evaluation results and an optional weighted score. Runs are stored in MongoDB and indexed in Elasticsearch, so they can be charted and compared in Kibana over time. See Results and Evaluation.

How It Works

  1. The run is started through the REST API or the CLI, from either a saved configuration or ad-hoc parameters.

  2. The bridge creates the device for the run from the device-uri scheme (see Devices) and opens its own tester socket to the engine.

  3. The device turn: the bridge takes the current screenshot of the device and the tested application’s audio or text, and feeds both into the tester socket — the tester "sees and hears" the application.

  4. The socket turn: the tester’s reply is delivered to the application, either as audio into the device, as text, or through the relay when the device cannot be driven directly.

  5. Commands the tester emits are executed on the device: tap, drag, scroll, open, type, clear. exit closes the turn and flushes queued speech to the device; sessionShouldEnd ends the run, with the verdict derived from the reason.

  6. Everything the run sees can be recorded as a video stream, and optionally displayed locally.

Safety nets: a watchdog re-triggers a device turn if no turn activity happens for a while, a per-session turn limit caps runaway conversations, and an overall timeout (600 s by default) ends the run regardless. A shutdown hook makes sure a killed process still reports its runs.

Several runs can be produced from one configuration: deviceCount and the deviceQueries list multiply into separate runs, each with its own run ID, and parallelism controls how many execute at once.

Running the Service

The bridge is a Spring Boot application with two modes:

Mode Behaviour

Web (no command line arguments)

Starts the HTTP service on port 9013 with MongoDB and Elasticsearch, exposing the REST API. This is how it runs in a deployment. Headless.

CLI (with arguments)

Executes one run and exits, without a web server and without the databases. Local playback of the device screen and audio is available in this mode. See Command Line.

 
# web service
./gradlew :promethist-bridge:bootRun

# single run from the command line
java -jar bridge/build/libs/promethist-bridge-*.jar \
  --key=agent:tester --device-uri="http://eu.promethist.ai?key=agent:acme-support"

Deployment is covered in the bridge Helm chart, which also renders the scheduled end-to-end test CronJobs.

Configuration

Property Meaning

promethist.bridge.secret-token

The token the REST API requires. When it is blank every request is rejected — the API has no open mode.

promethist.bridge.device-user, promethist.bridge.device-secret

Credentials for the device provider (BrowserStack).

promethist.bridge.video-recording-enabled

Whether runs are recorded to storage. Defaults to true.

promethist.storage.*

Where recordings are written — Azure Blob Storage or the local filesystem. The path prefix defaults to recording/bridge.

spring.data.mongodb., spring.elasticsearch.

Where runs, configurations and test cases are stored.

In this section