Scenario Configurations

Scenario configurations let you define custom fields on your scenarios and tests. Use them to store structured metadata like chatbot IDs, environment names, or data that vary between scenarios so that you can use it to configure and run your tests properly.

How It Works

A configuration is a reusable template that defines two sets of fields:

• Scenario fields: Appear on the scenario itself. Use these for values shared across all tests in a scenario.
• Test fields: Appear on each individual test. Use these for values that differ per test, such as a agent ID or specific input parameter.

You create configurations and fill in field values through the Voxli UI. When running tests via the API, the field values are available on the scenario and test objects so you can use them to configure your agent.

Reading Field Values

When you fetch tests for a scenario, each test includes a fields dictionary with the test-level values. The scenario object includes its own fields dictionary with scenario-level values.

# Get the scenario to read scenario-level fields
scenario = requests.get(
    f"{base_url}/scenarios/{scenario_id}",
    headers=headers
).json()

base_url_field = scenario["fields"]["base_url"]       # e.g. "https://api.example.com"
environment = scenario["fields"]["environment"]         # e.g. "production"

# Get all tests — each test has its own fields
tests = requests.get(
    f"{base_url}/scenarios/{scenario_id}/tests",
    headers=headers
).json()["data"]

for test in tests:
    customer_id = test["fields"].get("customer_id")     # e.g. "cust_12345"
    system_prompt = test["fields"].get("system_prompt")  # e.g. "You are a helpful..."

    # Use the fields to configure your agent for this test
    agent = create_agent(
        base_url=base_url_field,
        customer_id=customer_id,
        system_prompt=system_prompt,
    )