*** id: aaae7930-f829-4a3b-9be6-49f45f9069ec title: Ai Parameters sidebar-title: Ai Parameters slug: /python/reference/ai-parameters-reference max-toc-depth: 3 ---------------- # Appendix Reference materials, patterns, best practices, and troubleshooting guides for the SignalWire Agents SDK. ## About This Chapter This appendix provides supplementary reference materials to support your development with the SignalWire Agents SDK. | Section | Description | | --------------- | ---------------------------------------------- | | AI Parameters | Complete reference for all AI model parameters | | Design Patterns | Common architectural patterns and solutions | | Best Practices | Guidelines for production-quality agents | | Troubleshooting | Common issues and their solutions | | Migration Guide | Upgrading between SDK versions | | Changelog | Version history and release notes | ## Quick Reference | Task | See Section | | --------------------------- | --------------------------------- | | Configure AI model behavior | AI Parameters → LLM Parameters | | Set speech recognition | AI Parameters → ASR Parameters | | Adjust timing/timeouts | AI Parameters → Timing Parameters | | Implement common patterns | Design Patterns | | Optimize for production | Best Practices | | Debug agent issues | Troubleshooting | | Upgrade SDK version | Migration Guide | ## Chapter Contents | Section | Description | | -------------------------------------------------------------------------- | ------------------------------- | | [AI Parameters](/docs/agents-sdk/python/reference/ai-parameters-reference) | Complete AI parameter reference | | [Design Patterns](/docs/agents-sdk/python/reference/patterns) | Common architectural patterns | | [Best Practices](/docs/agents-sdk/python/reference/best-practices) | Production guidelines | | [Troubleshooting](/docs/agents-sdk/python/reference/troubleshooting) | Common issues and solutions | | [Migration Guide](/docs/agents-sdk/python/reference/migration) | Version upgrade guide | | [Changelog](/docs/agents-sdk/python/reference/changelog) | Version history | ## Overview | Category | Description | Where to Set | | --------- | ---------------------------------- | ------------------- | | LLM API | Model behavior (temperature, etc.) | prompt/post\_prompt | | ASR | Speech recognition settings | prompt or params | | Timing | Timeouts and delays | params | | Behavior | Agent behavior toggles | params | | Interrupt | Interruption handling | params | | Audio | Volume and background audio | params | | Video | Video display options | params | ## Setting Parameters in Python ```python from signalwire_agents import AgentBase agent = AgentBase(name="assistant", route="/assistant") # Set AI parameters agent.set_params({ "temperature": 0.7, "confidence": 0.6, "end_of_speech_timeout": 2000, "attention_timeout": 10000 }) ``` ## LLM API Parameters These parameters control the AI model's behavior. Set in `prompt` or `post_prompt` sections. | Parameter | Type | Range | Default | Description | | ----------------------- | ------- | ---------- | ------- | ------------------- | | temperature | number | 0.0 - 2.0 | 0.3 | Output randomness | | top\_p | number | 0.0 - 1.0 | 1.0 | Nucleus sampling | | frequency\_penalty | number | -2.0 - 2.0 | 0.1 | Repeat penalty | | presence\_penalty | number | -2.0 - 2.0 | 0.1 | New topic bonus | | max\_tokens | integer | 1 - 16385 | 256 | Max response size | | max\_completion\_tokens | integer | 1 - 2048 | 256 | For o1-style models | | reasoning\_effort | string | - | "low" | o1 reasoning level | | verbosity | string | - | "low" | Response length | ### Temperature Controls randomness in output generation: * **0.0**: Deterministic, consistent responses * **0.3** (default): Balanced creativity * **1.0+**: More creative, less predictable ### Reasoning Effort For o1-style models only: * `"low"`: Quick responses * `"medium"`: Balanced reasoning * `"high"`: Deep analysis ## ASR (Speech Recognition) Parameters Control automatic speech recognition behavior. | Parameter | Type | Range | Default | Description | | ---------------------- | ------- | ------- | ------- | ------------------ | | energy\_level | number | 0 - 100 | 52 | Minimum audio (dB) | | asr\_smart\_format | boolean | - | false | Smart formatting | | asr\_diarize | boolean | - | false | Speaker detection | | asr\_speaker\_affinity | boolean | - | false | Speaker tracking | ## Timing Parameters Control various timeouts and timing behaviors. | Parameter | Type | Range | Default | Description | | ----------------------------- | ------- | --------------- | ------- | -------------------- | | end\_of\_speech\_timeout | integer | 250 - 10000 | 700 | End silence (ms) | | first\_word\_timeout | integer | - | 1000 | First word wait (ms) | | speech\_timeout | integer | - | 60000 | Max speech (ms) | | speech\_event\_timeout | integer | - | 1400 | Event wait (ms) | | turn\_detection\_timeout | integer | - | 250 | Turn detection (ms) | | attention\_timeout | integer | 0 - 600000 | 5000 | Idle prompt (ms) | | outbound\_attention\_timeout | integer | 10000 - 600000 | 120000 | Outbound (ms) | | inactivity\_timeout | integer | 10000 - 3600000 | 600000 | Exit delay (ms) | | digit\_timeout | integer | - | 3000 | DTMF wait (ms) | | initial\_sleep\_ms | integer | - | 0 | Start delay (ms) | | transparent\_barge\_max\_time | integer | 0 - 60000 | 3000 | Barge time (ms) | ### Key Timeouts * **end\_of\_speech\_timeout**: Milliseconds of silence to detect end of speech * **attention\_timeout**: How long to wait before prompting user (0 disables) * **inactivity\_timeout**: How long before auto-hangup (default 10 minutes) ### Hard Stop Time ```python # Time expression format agent.set_params({ "hard_stop_time": "5m", # 5 minutes "hard_stop_time": "1h30m", # 1 hour 30 minutes "hard_stop_prompt": "We need to wrap up now." }) ``` ## Behavior Parameters Control various AI agent behaviors. | Parameter | Type | Default | Description | | ----------------------- | ----------- | ------- | --------------------------- | | direction | string | natural | Force inbound/outbound | | wait\_for\_user | boolean | false | Wait before speaking | | conscience | boolean/str | true | Safety enforcement | | strict\_mode | boolean/str | - | Alias for conscience | | transparent\_barge | boolean | true | Transparent barge mode | | enable\_pause | boolean | false | Allow pausing | | start\_paused | boolean | false | Start paused | | speak\_when\_spoken\_to | boolean | false | Only respond when spoken to | | enable\_turn\_detection | boolean | varies | Turn detection | | enable\_vision | boolean | false | Vision/video AI | | enable\_thinking | boolean | false | Complex reasoning | | save\_conversation | boolean | false | Save summary | | persist\_global\_data | boolean | true | Persist data | | transfer\_summary | boolean | false | Summary on transfer | ## SWAIG Control Parameters | Parameter | Type | Default | Description | | ------------------------------- | ------- | ------- | -------------------- | | swaig\_allow\_swml | boolean | true | Allow SWML returns | | swaig\_allow\_settings | boolean | true | Allow settings mods | | swaig\_post\_conversation | boolean | false | Post conversation | | swaig\_set\_global\_data | boolean | true | Allow global data | | hold\_on\_process | boolean | false | Hold during process | | barge\_functions | boolean | true | Allow function barge | | function\_wait\_for\_talking | boolean | false | Wait for speech | | functions\_on\_no\_response | boolean | false | Run on no response | | functions\_on\_speaker\_timeout | boolean | true | Run on timeout | ## Interrupt Parameters | Parameter | Type | Default | Description | | -------------------------- | ------- | ------- | ------------------------------ | | acknowledge\_interruptions | boolean | false | Acknowledge interrupts | | interrupt\_prompt | string | - | Custom interrupt message | | interrupt\_on\_noise | boolean | false | Allow noise interrupts | | max\_interrupts | integer | 0 | Max before interrupt\_prompt | | barge\_min\_words | integer | 0 | Min words before barge allowed | ## Debug Parameters | Parameter | Type | Default | Description | | --------------------- | ------- | ------- | ------------------------ | | debug\_webhook\_url | string | - | URL to send debug data | | debug\_webhook\_level | integer | 1 | Debug verbosity (0-2) | | audible\_debug | boolean | false | Enable audible debugging | | audible\_latency | boolean | false | Make latency audible | | verbose\_logs | boolean | false | Enable verbose logging | ## Audio Parameters | Parameter | Type | Range | Default | Description | | ------------------------ | ------- | -------- | ------- | ------------------------ | | ai\_volume | integer | -50 - 50 | 0 | AI voice volume | | background\_file | string | - | - | Background audio URL | | background\_file\_volume | integer | -50 - 50 | 0 | Background volume | | background\_file\_loops | integer | - | -1 | Loop count (-1=infinite) | | hold\_music | string | - | - | Hold audio/tone | | max\_emotion | integer | 1 - 30 | 30 | TTS emotion level | ### Hold Music with Tone ```python # Use tone generator agent.set_params({ "hold_music": "tone:440" # 440Hz tone }) # Use audio file agent.set_params({ "hold_music": "https://example.com/hold-music.mp3" }) ``` ## Video Parameters | Parameter | Type | Description | | ---------------------- | ------ | -------------------------- | | video\_talking\_file | string | Video when AI is talking | | video\_idle\_file | string | Video when AI is idle | | video\_listening\_file | string | Video when AI is listening | ## String Parameters | Parameter | Default | Description | | -------------------------- | --------------- | ------------------------------- | | local\_tz | "US/Central" | Timezone for agent | | conversation\_id | - | ID for cross-call persistence | | digit\_terminators | - | DTMF end characters (e.g., "#") | | barge\_match\_string | - | Barge pattern matching | | tts\_number\_format | "international" | Phone format: national/intl | | ai\_model | "gpt-4o-mini" | AI model to use | | thinking\_model | - | Model for thinking mode | | vision\_model | - | Model for vision | | pom\_format | "markdown" | Prompt format: markdown/xml | | attention\_timeout\_prompt | - | Custom attention prompt | | hard\_stop\_prompt | - | Prompt at hard stop time | | static\_greeting | - | Pre-recorded greeting | | summary\_mode | - | string/og/function | ## VAD Configuration Voice Activity Detection uses a string format: `silero_thresh:frame_ms` ```python agent.set_params({ "vad_config": "0.5:30" # threshold 0.5, 30ms frames }) ``` ## Post-Prompt Parameter Defaults Parameters have different defaults in `post_prompt` for more deterministic summaries: | Parameter | Prompt Default | Post-Prompt Default | Reason | | ------------------ | -------------- | ------------------- | ------------- | | temperature | 0.3 | 0.0 | Deterministic | | frequency\_penalty | 0.1 | 0.0 | No penalty | | presence\_penalty | 0.1 | 0.0 | No penalty | ## Model-Specific Overrides Different models support different parameters: | Model Type | Supported Parameters | | -------------- | ---------------------------------------------------------- | | OpenAI | frequency\_penalty, presence\_penalty, max\_tokens, top\_p | | Bedrock Claude | max\_completion\_tokens instead of max\_tokens | | o1-style | reasoning\_effort, max\_completion\_tokens | ## Complete Example ```python #!/usr/bin/env python3 # configured_agent.py - Agent with all AI parameters configured from signalwire_agents import AgentBase agent = AgentBase(name="configured", route="/configured") agent.prompt_add_section("Role", "You are a customer service agent.") agent.add_language("English", "en-US", "rime.spore") # Configure all parameters agent.set_params({ # LLM settings "max_tokens": 300, # Timing "end_of_speech_timeout": 1500, "attention_timeout": 8000, "inactivity_timeout": 300000, # Behavior "wait_for_user": False, "conscience": True, "local_tz": "America/New_York", # Audio "background_file": "https://example.com/ambient.mp3", "background_file_volume": -30 }) if __name__ == "__main__": agent.run() ``` ## SWML Example ```json { "version": "1.0.0", "sections": { "main": [{ "ai": { "params": { "end_of_speech_timeout": 2000, "attention_timeout": 10000, "inactivity_timeout": 600000, "wait_for_user": false, "conscience": true, "local_tz": "America/Chicago", "background_file": "https://example.com/music.mp3", "background_file_volume": -25 }, "prompt": { "temperature": 0.3, "top_p": 1.0, "frequency_penalty": 0.1, "presence_penalty": 0.1, "text": "You are a helpful assistant." }, "post_prompt": { "temperature": 0.0, "frequency_penalty": 0.0, "presence_penalty": 0.0, "text": "Summarize the conversation." } } }] } } ```