> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Experiments

> Run, configure, and monitor A/B experiments end to end

## Overview

The **Inworld's Unreal Runtime** lets you iterate on prompts, models, custom nodes/edges parameters, and configs (LLM and TTS) without redeploying code. This guide covers the full workflow: graph creation, Portal setup, and experiment rollout.

## Experiments workflow summary

<Steps titleSize="h3">
  <Step title="Create a Graph asset">
    Design your graph and enable remote config.
  </Step>

  <Step title="Register variants">
    Upload JSON configs for the baseline graph and its variants.
  </Step>

  <Step title="Start experiment">
    Define targeting rules and rollout percentages in the Portal.
  </Step>

  <Step title="Monitor & roll out">
    Track metrics, then promote the winning variant.
  </Step>
</Steps>

## Step 1 - Create a Graph asset

### 1. Code your solution

In this example we developed a simple Blueprint that instantiates the graph, runs it, and prints the response on screen.

### 2. Design your graph

The sample graph makes an LLM call:

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/graph_example.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=63aa9a59a63e2172a02d6a10425467aa" alt="" width="1483" height="975" data-path="img/unreal/experiments/graph_example.png" />

It includes a custom node that appends "PREFIX" (when its `AddPrefix` boolean is enabled) and inputs A and B as:

```
PREFIX --- {A} --- {B}
```

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/customnode_example.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=e4053b01edfc00f19d69e4028220ca60" alt="" width="1485" height="976" data-path="img/unreal/experiments/customnode_example.png" />

### 3. Enable remote config

Enable remote config inside the graph editor:

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/graph_enableremoteconfig.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=02988ab6bac24c77dbe0ee7953a6141a" alt="" width="558" height="310" data-path="img/unreal/experiments/graph_enableremoteconfig.png" />

Graph executions return results as:

* **AddPrefix is false**: `{Request text} --- {LLM response}`
* **AddPrefix is true**: `PREFIX --- {Request text} --- {LLM response}`

The baseline uses `Ministral-8b-Latest` with `AddPrefix = false`:

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/graph_variant_base.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=0f84a4ac8f5a756bed58d088c23429bd" alt="" width="1480" height="969" data-path="img/unreal/experiments/graph_variant_base.png" />

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/graph_variant_base_customnode.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=29a1110cf6274348b972617e05c81140" alt="" width="1484" height="971" data-path="img/unreal/experiments/graph_variant_base_customnode.png" />

## Step 2 - Register variants

Registering a variant tells Portal which configuration can participate in Experiments. Start with the baseline, then add variants.

### 1. Register the baseline variant

* **Register Graph**:
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_registergrpah.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=c0e8041f57a9a73c635bca4d8525ffa0" alt="" width="1272" height="760" data-path="img/unreal/experiments/portal_registergrpah.png" />

* **Copy the Graph ID** from the Graph Editor:
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_addgraph_copy_id.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=c65b63cbf7db6d15bc8a6b602f7af9a7" alt="" width="558" height="310" data-path="img/unreal/experiments/portal_addgraph_copy_id.png" />

* **Enter or paste the Graph ID** to the Portal:
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_addgraph_enter_id.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=4ff6d1dc0ac57cce098a549188a1c3bf" alt="" width="945" height="299" data-path="img/unreal/experiments/portal_addgraph_enter_id.png" />

### 2. Create baseline variant

* **Export baseline JSON config** from the Graph Editor:
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_export_base.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=f6d10d5067262053fcb58c9d1ce1f191" alt="" width="1483" height="970" data-path="img/unreal/experiments/portal_export_base.png" />

* **Click on created Graph** then **Create Variant** in the Portal:
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_addvariant.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=917c9c699d02f3fc28c56f6abf1d5dc0" alt="" width="1273" height="761" data-path="img/unreal/experiments/portal_addvariant.png" />
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_addvariant_baseline.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=f336db1dd249b265ef9faf206603e3ba" alt="" width="629" height="506" data-path="img/unreal/experiments/portal_addvariant_baseline.png" />

* **Upload baseline JSON config** to the Portal:
  <img src="https://mintcdn.com/inworldai/5DYC78iamoiRY6Hu/img/unreal/experiments/portal_upload_base.png?fit=max&auto=format&n=5DYC78iamoiRY6Hu&q=85&s=e5171426aca320894f675f1aaa2a1e7a" alt="" width="950" height="648" data-path="img/unreal/experiments/portal_upload_base.png" />

### 3. Create GPT-5 variant

* **Export GPT-5 config** from the Graph Editor:
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_export_variant_gtp5.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=3a99276417eecc65caaab6bbb466d5bf" alt="" width="1478" height="967" data-path="img/unreal/experiments/portal_export_variant_gtp5.png" />

* **Create and upload GPT-5 variant** to the Portal:
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_create_variant_1.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=a33df835df890c86a9104fc6d4f9cdd7" alt="" width="1274" height="755" data-path="img/unreal/experiments/portal_create_variant_1.png" />
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_create_variant_2.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=dace4bab76196ef83915518c2843d116" alt="" width="993" height="570" data-path="img/unreal/experiments/portal_create_variant_2.png" />

### 4. Create GPT-5 with AddPrefix variant

* **Export GPT-5 config** from the Graph Editor:
  <img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_export_variant_gtp5_with_prefix.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=31dc1e77f82b9a73789577c426fd69f9" alt="" width="1477" height="968" data-path="img/unreal/experiments/portal_export_variant_gtp5_with_prefix.png" />

* **Create and upload GPT-5 with prefix variant** to the Portal

## Step 3 - Start an experiment

Open the **Targeting & Rollout** tab and set default variant:

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/portal_targeting.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=e9f65922eea7743b92483d22296185b1" alt="" width="1271" height="762" data-path="img/unreal/experiments/portal_targeting.png" />

Changing the default targeting updates the configuration for:

* All currently running graph instances (on their next execution)
* All newly compiled graphs

<Warning>Targeting changes may take time to propagate.</Warning>

### Example results

**Baseline execution**:

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/execution_baseline.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=71da458259839bf9853986a58a0e628c" alt="" width="1472" height="964" data-path="img/unreal/experiments/execution_baseline.png" />

**Switch targeting to GPT-5**:

<img src="https://mintcdn.com/inworldai/5DYC78iamoiRY6Hu/img/unreal/experiments/portal_targeting_gpt5.png?fit=max&auto=format&n=5DYC78iamoiRY6Hu&q=85&s=ad170b9aa6e03abc592bd7262c307752" alt="" width="1268" height="763" data-path="img/unreal/experiments/portal_targeting_gpt5.png" />

Next execution result:

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/execution_gpt5.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=40a53c9c3a81f3bcf82a53dd94ce0490" alt="" width="1480" height="967" data-path="img/unreal/experiments/execution_gpt5.png" />

**Switch targeting to GPT-5 with prefix**:

Next execution result:

<img src="https://mintcdn.com/inworldai/e32_hYjhm66PgPOW/img/unreal/experiments/execution_gpt5_with_prefix.png?fit=max&auto=format&n=e32_hYjhm66PgPOW&q=85&s=c3209d5ebadec96272396b970787a631" alt="" width="1476" height="967" data-path="img/unreal/experiments/execution_gpt5_with_prefix.png" />

## Step 4 - Monitor & roll out

Monitor your experiment results and deploy the winner:

* **Watch metrics**: Monitor dashboards, traces, and logs while the experiment runs
* **Gradual rollout**: Increase the winning variant's allocation gradually (50/50 → 70/30 → 90/10), then set it to 100% and retire old rules
* **Rollback**: Roll back or tweak allocations if latency, errors, or business KPIs regress

## How Experiments work

When a request hits your graph, the runtime decides whether to use the local configuration or a remote variant from Experiments:

1. Remote config must be enabled
2. The graph ID must be registered in Experiments and have at least one active rule that returns a variant

```mermaid theme={"system"}
flowchart TD
    A[Graph Execution Request] --> B{Enable Remote Config == true}
    
    B -->|NO/DEFAULT| C[Static Config]
    C --> D[Use local graph configuration]
    
    B -->|YES| E[Remote Config]
    E --> F{Experiments returns a variant?}
    
    F -->|NO| G[Use local graph configuration]
    F -->|YES| H[Use Experiments variant]
    
    style A fill:#e1f5fe
    style D fill:#c8e6c9
    style G fill:#c8e6c9  
    style H fill:#fff3e0
```

**If remote config is enabled**, Experiments evaluates each request as follows:

1. **Local cache check**: If the compiled variant for this user is cached, it executes immediately; otherwise Experiments is queried
2. **Variant fetch**: Experiments evaluates your targeting rules, returns the selected variant, and falls back to the local configuration if no rule applies or the fetch fails
3. **Compile & cache**: The runtime compiles the variant payload, caches it, and executes the graph with the new configuration

## Troubleshooting

### Failed to resolve struct flag

**Error**: `LogInworldRuntime: Failed to resolve struct flag: ....... with targeting key: ....... with error: Flag not found`

If you see this error in the output log, it usually means one of the following:

* Remote Config is enabled, but the graph was not registered in Portal
* The Graph ID registered in Portal does not match the Graph ID in Unreal Engine

### Targeting changes not appearing

**Issue**: I changed targeting and don't see changes on the next executions

Sometimes targeting updates take time to propagate. Wait a few moments and retry—the new variant will be applied on the next graph execution once the change is fully propagated.

## Supported via Experiments

### Applied on next executions (no code redeploy)

* Switch LLM/STT/TTS models or providers
* Adjust node configuration (temperature, token limits, prompts)
* Reorder/add/remove nodes while preserving the same inputs/outputs
* Update processing logic (edges, preprocessing steps, data flow)
* Modify custom node parameters
* Modify custom edge conditions parameters

### Requires a code deployment

* Deploying new custom nodes/edges
* Changing processing functions for custom nodes/edges
* Changing the graph's input/output interface
