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

# Experimental config

<p className="lead">
  The experimental config file is an optional JSON file used to enable experimental features and advanced runtime settings for an agent.
</p>

Use it for:

* feature flags
* ASR tuning
* conversation control
* debug-oriented options

## Location

The file lives at:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
agent_settings/experimental_config.json
```

## What it contains

The file is a JSON object.

It may be:

* flat
* nested
* grouped by feature category

Top-level keys represent feature areas, and values contain the settings for those features.

## Example

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "asr": {
    "disable_itn": true,
    "eager_final": true
  },
  "conversation_control": {
    "enhanced_tts_preprocessing_enabled": false,
    "max_silence_count": 1000,
    "min_chunk_size": 1
  }
}
```

## Schema and validation

Available features and their types are defined in a bundled schema file:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
src/poly/resources/experimental_config_schema.yaml
```

The ADK validates `experimental_config.json` against this schema when you run:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly validate
```

Invalid configuration fails `poly validate` locally. Experimental config that fails validation is not read by the runtime in deployed agents.

### Custom schema path

If the bundled schema does not match the schema expected by your Agent Studio environment, you can point validation at a custom schema file by setting the `ADK_EXPERIMENTAL_CONFIG_SCHEMA_PATH` environment variable:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ADK_EXPERIMENTAL_CONFIG_SCHEMA_PATH=/path/to/your/experimental_config_schema.yaml
poly validate
```

When `ADK_EXPERIMENTAL_CONFIG_SCHEMA_PATH` is set, the ADK uses that file instead of the bundled schema. When the variable is unset or empty, validation falls back to the bundled schema.

<Info>
  **Validate before pushing**

  Experimental config can affect runtime behavior in subtle ways. Always run `poly validate` locally before pushing changes.
</Info>

## When to use it

Use experimental config when you need behavior that goes beyond the standard Agent Studio settings.

Common use cases include:

<CardGroup>
  <Card title="ASR and TTS tuning">
    Adjust speech recognition or speech output behavior beyond the standard channel settings.
  </Card>

  <Card title="Experimental platform features">
    Enable features before they are generally available.
  </Card>

  <Card title="Conversation control">
    Tune parameters such as silence handling or chunk size behavior.
  </Card>
</CardGroup>

## Feature reference

The following sections describe notable feature areas available in the schema.

### Audio enhancement

Configure audio enhancement processing applied to the incoming audio stream before speech recognition. Three providers are available: `ai-coustics`, `dolby`, and `krisp`.

#### `ai-coustics` VAD

The `ai-coustics` enhancer supports a `vad` (voice activity detection) sub-object for tuning how speech is detected in the audio stream.

| Field                     | Type   | Description                                                                                                                                      | Default | Range      |
| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ---------- |
| `sensitivity`             | number | Energy threshold for speech detection. Energy threshold = 10^(-sensitivity). Higher values detect quieter speech.                                | `6.0`   | 1.0 – 15.0 |
| `speech_hold_duration`    | number | How long the VAD continues to report speech after the audio signal no longer contains speech (in seconds). Useful for bridging short pauses.     | `0.03`  | ≥ 0.0      |
| `minimum_speech_duration` | number | How long speech must be present before the VAD considers it speech (in seconds). Helps filter out short non-speech sounds like clicks or coughs. | `0.0`   | 0.0 – 1.0  |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "audio_enhancement": {
    "ai-coustics": {
      "vad": {
        "sensitivity": 6.0,
        "speech_hold_duration": 0.03,
        "minimum_speech_duration": 0.0
      }
    }
  }
}
```

#### `krisp`

Krisp provides noise cancellation and voice isolation. Settings include:

| Field                     | Type    | Description                                                                                                            | Default            |
| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `model`                   | string  | Krisp model variant: `"noise-cancellation"`, `"voice-isolation"`, `"telephony"`, `"telephony-lite"`, `"transcription"` | `"telephony-lite"` |
| `noise_suppression_level` | integer | Noise suppression intensity. `0` = off, `100` = max.                                                                   | `100`              |
| `frame_duration_ms`       | integer | Audio frame duration in milliseconds. Allowed values: `10`, `15`, `20`, `30`, `32`.                                    | `20`               |
| `timeout_ms`              | integer | Max milliseconds to wait for enhancement per chunk before falling back to original audio. `0` = no timeout.            | `100`              |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "audio_enhancement": {
    "krisp": {
      "model": "telephony-lite",
      "noise_suppression_level": 100,
      "frame_duration_ms": 20,
      "timeout_ms": 100
    }
  }
}
```

### Barge-in

The barge-in section supports additional fields to control how interrupted speech is handled and displayed.

#### Interruption granularity

`interruption_granularity` controls where the split happens in agent speech when the user barges in.

| Value             | Behavior                                 |
| ----------------- | ---------------------------------------- |
| `"word"`          | Audio-timing split at the word boundary. |
| `"sentence"`      | Drop the interrupted sentence.           |
| `"sentence_keep"` | Keep the interrupted sentence.           |
| `"chunk"`         | Drop the entire TTS chunk.               |

#### Interruption display

`interruption_display` controls how interrupted text appears in Agent Studio `msg.Text` (and in LLM context if `interruption_display_llm` is not set).

| Value        | Behavior                                             |
| ------------ | ---------------------------------------------------- |
| `"ellipsis"` | Append `"..."` to the said portion.                  |
| `"tags"`     | Wrap the unsaid portion in `<interrupted>` XML tags. |
| `"strip"`    | Drop unsaid text silently.                           |
| `"none"`     | Keep the full text unchanged.                        |
| `"barge"`    | Append a `"[BARGE IN]"` marker.                      |

#### `interruption_display_llm`

An optional LLM-specific override for interrupted text display. Accepts the same values as `interruption_display`. When absent, inherits from `interruption_display`.

#### `truncate_interrupted_utterances`

| Field                             | Type    | Default | Description                                                                                                                                                                                                                                       |
| --------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `truncate_interrupted_utterances` | boolean | `false` | When `true`, function-output utterances on interrupted turns are truncated to only the said (heard) portion, dropping unsaid text. Useful when TTS utterances are attached to function outputs and should reflect what the caller actually heard. |

#### `annotate_interrupted_function_calls`

| Field                                 | Type    | Description                                                                                                                                                                                      |
| ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `annotate_interrupted_function_calls` | boolean | When `true`, function call results on interrupted turns are annotated with said/unsaid context so the LLM can judge whether the initiating question was fully communicated. Defaults to `false`. |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "barge_in": {
    "interruption_granularity": "sentence",
    "interruption_display": "ellipsis",
    "interruption_display_llm": "tags",
    "truncate_interrupted_utterances": true,
    "annotate_interrupted_function_calls": false
  }
}
```

### DTMF

Configure DTMF behavior, including disabling speech recognition for DTMF-only steps.

The `dtmf` object supports a `flow_overrides` map where each key is a flow name. Per-flow settings include:

| Field            | Type    | Description                                                               |
| ---------------- | ------- | ------------------------------------------------------------------------- |
| `disable_speech` | boolean | Whether to disable speech recognition when DTMF is enabled for this flow. |
| `steps`          | object  | Step-specific overrides. Each key is a step name.                         |

Per-step settings (nested under `steps`) include:

| Field                 | Type    | Description                                                                                        |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `disable_speech`      | boolean | Whether to disable speech recognition for this step. Takes precedence over the flow-level setting. |
| `first_digit_timeout` | integer | Timeout in seconds for the first DTMF digit input for this step. Minimum: `1`.                     |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "dtmf": {
    "flow_overrides": {
      "Payment Flow": {
        "disable_speech": true,
        "steps": {
          "Enter Card Number": {
            "disable_speech": true,
            "first_digit_timeout": 5
          }
        }
      }
    }
  }
}
```

### Language switching

Configure automatic language switching behavior.

| Field           | Type    | Default | Description                                                                                                                                                                                   |
| --------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `explicit_only` | boolean | `false` | When `true`, the agent only switches language when the user explicitly asks. When `false` (default), the agent may also switch spontaneously based on detected language in the transcription. |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "language_switching": {
    "explicit_only": true
  }
}
```

### Memory

Configure agent memory features, including repeat-caller identification.

#### `identifier_source`

By default, memory lookups use the caller or callee phone number as the identifier. The `identifier_source` field lets you supply a custom source instead.

| Field               | Type   | Description                                                                                                               |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `identifier_source` | string | Custom source for the memory lookup identifier. Must match the pattern `(sip_headers\|integration_attributes\|state):.+`. |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "memory": {
    "identifier_source": "sip_headers:X-Customer-Id"
  }
}
```

### OpenAI Realtime

Configure behavior for the OpenAI Realtime integration, including transcription settings.

#### `set_transcriber_language`

| Field                      | Type    | Description                                                                                                                                                                                                                                           | Default |
| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `set_transcriber_language` | boolean | When `true`, the conversation language code is passed to the transcriber in the session configuration, making the model adhere more strictly to the specified language. Do not use this in multilingual projects with a language detection component. | `false` |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "openai_realtime": {
    "transcription": {
      "set_transcriber_language": true
    }
  }
}
```

### Prompts

The `prompts` section supports channel-specific and language-related decorator overrides.

| Field                             | Type   | Description                                                                                                 |
| --------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `webchat_decorator`               | string | Optional webchat-specific decorator for the `webchat.polyai` channel.                                       |
| `sms_decorator`                   | string | Optional SMS-specific decorator for the `sms.polyai` channel.                                               |
| `voice_decorator`                 | string | Optional voice-specific decorator for `chat.polyai` or `sip.polyai` channels.                               |
| `language_switching_instructions` | string | Optional instructions for language switching behaviour. Must contain a `{available_languages}` placeholder. |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "prompts": {
    "sms_decorator": "Keep responses brief and suitable for SMS.",
    "language_switching_instructions": "You may switch to any of the following languages if the user requests it: {available_languages}."
  }
}
```

### Webhooks

Configure webhook behavior for deployment events, including custom payload templates.

#### `payload_template`

The `payload_template` field controls the JSON body sent to a webhook URL. If omitted, the default deployment payload is sent as-is.

| Field              | Type   | Description                                                                                                                    |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `payload_template` | object | Custom payload template. String values may contain `{{field}}` placeholders that are substituted with deployment event fields. |

**Available placeholder fields:**

* `deployment_id`
* `account_id`
* `project_id`
* `client_env`
* `artifact_version`
* `deployment_type`
* `timestamp`
* `user`

**Special placeholder:**

Use `{{payload}}` to inject the entire deployment payload object at a specific position in the template — for example, when a webhook receiver (such as GitHub's `repository_dispatch`) requires nesting under a specific key like `client_payload`.

When `{{payload}}` is not present in the template, the deployment payload fields are merged at the top level of the rendered result.

Example — GitHub `repository_dispatch`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "webhooks": {
    "payload_template": {
      "event_type": "deployment-{{client_env}}",
      "client_payload": "{{payload}}"
    }
  }
}
```

Example — flat template with individual fields:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "webhooks": {
    "payload_template": {
      "env": "{{client_env}}",
      "version": "{{artifact_version}}",
      "deployed_by": "{{user}}"
    }
  }
}
```

### `include_kb_functions_in_flows`

Controls whether knowledge base (KB) functions from retrieved RAG topics are shown to the model inside flows.

| Value             | Behavior                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `true`            | KB functions from retrieved RAG topics are shown to the model inside flows, even on steps that have their own `functions_referenced`. |
| `false` (default) | KB functions are hidden inside flows.                                                                                                 |

This setting only affects behavior inside flows. Outside flows, KB functions are always shown. It can be overridden per-flow or per-step.

## Best practices

* only set values you actually intend to override
* omit defaults rather than copying them unnecessarily
* validate locally with `poly validate` before pushing
* remove flags that are no longer needed
* treat the file as an advanced override layer, not a dumping ground for ordinary config

## Related pages

<CardGroup>
  <Card title="Agent settings" href="/adk/reference/agent_settings">
    See where experimental config sits within the broader agent settings area.
  </Card>

  <Card title="Speech recognition" href="/adk/reference/speech_recognition">
    Compare experimental ASR controls with standard voice speech-recognition settings.
  </Card>
</CardGroup>