Experimental config - PolyAI Platform

The experimental config file is an optional JSON file used to enable experimental features and advanced runtime settings for an agent.

Use it for:

feature flags
ASR tuning
conversation control
debug-oriented options

Location

The file lives at:

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

{
  "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:

src/poly/resources/experimental_config_schema.yaml

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

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:

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.

Validate before pushingExperimental config can affect runtime behavior in subtle ways. Always run poly validate locally before pushing changes.

When to use it

Use experimental config when you need behavior that goes beyond the standard Agent Studio settings. Common use cases include:

ASR and TTS tuning

Adjust speech recognition or speech output behavior beyond the standard channel settings.

Experimental platform features

Enable features before they are generally available.

Conversation control

Tune parameters such as silence handling or chunk size behavior.

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "webhooks": {
    "payload_template": {
      "event_type": "deployment-{{client_env}}",
      "client_payload": "{{payload}}"
    }
  }
}

Example — flat template with individual fields:

{
  "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

Agent settings

See where experimental config sits within the broader agent settings area.

Speech recognition

Compare experimental ASR controls with standard voice speech-recognition settings.

​Location

​What it contains

​Example

​Schema and validation

​Custom schema path

​When to use it

ASR and TTS tuning

Experimental platform features

Conversation control

​Feature reference

​Audio enhancement

​ai-coustics VAD

​krisp

​Barge-in

​Interruption granularity

​Interruption display

​interruption_display_llm

​truncate_interrupted_utterances

​annotate_interrupted_function_calls

​DTMF

​Language switching

​Memory

​identifier_source

​OpenAI Realtime

​set_transcriber_language

​Prompts

​Webhooks

​payload_template

​include_kb_functions_in_flows

​Best practices

​Related pages

Agent settings

Speech recognition

Location

What it contains

Example

Schema and validation

Custom schema path

When to use it

Feature reference

Audio enhancement

`ai-coustics` VAD

`krisp`

Barge-in

Interruption granularity

Interruption display

`interruption_display_llm`

`truncate_interrupted_utterances`

`annotate_interrupted_function_calls`

DTMF

Language switching

Memory

`identifier_source`

OpenAI Realtime

`set_transcriber_language`

Prompts

Webhooks

`payload_template`

`include_kb_functions_in_flows`

Best practices

Related pages