Bridge Application

Bridge Configuration

A run is described by BridgeProperties. Those properties can be supplied ad hoc (query parameters, a JSON body or CLI options), or stored as a named configuration and grouped into a test case so the same test can be repeated and scheduled.

The model lives in common (ai.promethist.bridge), so the platform backend can read and write configurations that the bridge then executes.

Run Properties

BridgeProperties — JSON field names are hyphenated, as shown.

Property Default Meaning

Property	Default	Meaning
`key`	required	Pipeline key of the tester agent, e.g. `agent:tester`.
`device-uri`	required	What the tested application runs on — see Devices.
`engine-url`	`https://eu.promethist.ai`	Engine the tester connects to.
`client-url`	—	URL the device should open, typically an agent link (`…/a/{agentRef}`). Used to launch the application under test.
`relay-url`	—	Relay service to route audio through, for device types that cannot receive it directly.
`device-queries`	empty	Extra query strings appended to the device URI; each entry produces its own run.
`device-ref`	`bridge:%id`	Device ref reported to the engine. `%id` is replaced by the run ID.
`locale`	`en-US`	Conversation locale.
`sample-rate`	platform default	Audio sample rate used in both directions.
`audio-speed`	`1`	Pacing multiplier for audio sent to the device.
`text-only`	`false`	Run the conversation as text, without speech synthesis. Cannot be combined with `speech-processing`.
`no-system-prompt`	`false`	Suppress the engine’s own system prompt for the tester, so only the agent’s instructions apply.
`speech-processing`	`false`	Enable server-side speech processing (facial animation data).
`timeout`	`600`	Overall run timeout in seconds. The most reliable stop condition — use it as the primary limit.
`max-turns-per-session`	—	Cap on turns per session. Has no effect for browser tests, where the turn-end command never arrives in realtime mode; rely on `timeout` there.
`session-count`	`1`	How many consecutive conversations the run holds.
`session-delay`	`20`	Seconds to wait between consecutive sessions.
`device-count`	`1`	How many devices to run in parallel from this configuration.
`realtime-configuration-id`	—	Realtime configuration to force on the tester’s session.
`configuration-id`	—	The saved configuration this run came from; set automatically.
`test-run-id`	—	Identifier grouping several runs into one logical execution.
`tester-test-mode`	`false`	Marks the tester’s session as test data in the engine.
`tested-agent-test-mode`	`true`	Marks the tested agent’s session as test data. Only settable where the bridge owns that connection, i.e. for a virtual device.
`aggregate-weights`	empty	Weights per evaluation metric, used to compute the run’s weighted average score — see Results and Evaluation.

key

required

Pipeline key of the tester agent, e.g. agent:tester.

device-uri

required

What the tested application runs on — see Devices.

engine-url

https://eu.promethist.ai

Engine the tester connects to.

client-url

—

URL the device should open, typically an agent link (…/a/{agentRef}). Used to launch the application under test.

relay-url

—

Relay service to route audio through, for device types that cannot receive it directly.

device-queries

empty

Extra query strings appended to the device URI; each entry produces its own run.

device-ref

bridge:%id

Device ref reported to the engine. %id is replaced by the run ID.

locale

en-US

Conversation locale.

sample-rate

platform default

Audio sample rate used in both directions.

audio-speed

1

Pacing multiplier for audio sent to the device.

text-only

false

Run the conversation as text, without speech synthesis. Cannot be combined with speech-processing.

no-system-prompt

false

Suppress the engine’s own system prompt for the tester, so only the agent’s instructions apply.

speech-processing

false

Enable server-side speech processing (facial animation data).

timeout

600

Overall run timeout in seconds. The most reliable stop condition — use it as the primary limit.

max-turns-per-session

—

Cap on turns per session. Has no effect for browser tests, where the turn-end command never arrives in realtime mode; rely on timeout there.

session-count

1

How many consecutive conversations the run holds.

session-delay

20

Seconds to wait between consecutive sessions.

device-count

1

How many devices to run in parallel from this configuration.

realtime-configuration-id

—

Realtime configuration to force on the tester’s session.

configuration-id

—

The saved configuration this run came from; set automatically.

test-run-id

—

Identifier grouping several runs into one logical execution.

tester-test-mode

false

Marks the tester’s session as test data in the engine.

tested-agent-test-mode

true

Marks the tested agent’s session as test data. Only settable where the bridge owns that connection, i.e. for a virtual device.

aggregate-weights

empty

Weights per evaluation metric, used to compute the run’s weighted average score — see Results and Evaluation.

testMode matters: leave the defaults in place so automated runs do not pollute production analytics and billing.

Saved Configurations

A BridgeConfiguration is a stored, named set of properties. It is polymorphic — the type property selects the variant, which decides which fields are relevant:

type Describes

`type`	Describes
`VirtualDevice`	A conversation against another engine session. Adds `engineUrl`, `deviceUri`, `textOnly`, `sessionDelay`, `testedAgentTestMode`, `overrideRealtimeConfigurationId` and `aggregateWeights`.
`BrowserStackMobile`	The mobile app on a BrowserStack device. Adds `engineUrl`, `clientUrl` (required), `deviceUri`, `deviceQueries` and `relayUrl` (defaulting to the EU relay).
`BrowserStackBrowser`	A BrowserStack desktop browser. Adds `engineUrl`, `clientUrl`, `deviceUri`, `deviceQueries` and `textOnly`.
`BrowserStackWebClient`	The web client in a BrowserStack browser, driven through the relay. Adds `clientUrl` (required), `relayUrl`, `deviceUri` and `deviceQueries`.
`LinkDevice`	A real client reached over its link WebSocket. Adds `deviceUri`.

VirtualDevice

A conversation against another engine session. Adds engineUrl, deviceUri, textOnly, sessionDelay, testedAgentTestMode, overrideRealtimeConfigurationId and aggregateWeights.

BrowserStackMobile

The mobile app on a BrowserStack device. Adds engineUrl, clientUrl (required), deviceUri, deviceQueries and relayUrl (defaulting to the EU relay).

BrowserStackBrowser

A BrowserStack desktop browser. Adds engineUrl, clientUrl, deviceUri, deviceQueries and textOnly.

BrowserStackWebClient

The web client in a BrowserStack browser, driven through the relay. Adds clientUrl (required), relayUrl, deviceUri and deviceQueries.

LinkDevice

A real client reached over its link WebSocket. Adds deviceUri.

Every variant carries the shared fields description, key, locale, deviceRef, sessionCount, deviceCount, timeout, maxTurnsPerSession, noSystemPrompt, sampleRate, audioSpeed, speechProcessing and testerTestMode, and converts itself to BridgeProperties when the run starts.

Configurations are managed through the configuration endpoints.

Test Cases

A BridgeTestCase is a name plus a list of configuration IDs:

{
  "id": "…",
  "name": "Support agent regression",
  "configurationIds": ["…", "…"]
}

Running a test case runs every configuration in it, which is how one test covers several device types or agents at once. The resulting runs carry the test case ID, so they can be listed and compared together.

Variable Groups

Configurations can be written with $VARIABLE placeholders instead of literal values. On every run the bridge resolves them from a named variable group, selected with the variable-group parameter (default default).

Substitution applies to key, locale, engineUrl, clientUrl, relayUrl, deviceUri and each entry of deviceQueries. This is what lets the same test case run against different environments and different agent refs — the scheduled test jobs in the deployment use exactly this mechanism.