Experimental config

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 pushing

Experimental 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

Related pages

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.