Move prompt and greeting docs to vendor config

digitallysavvy · digitallysavvy · commit eeac05d03f83 · 2026-06-01T17:09:14.000-04:00
Update AgentKit examples and reference docs to configure prompts,
  greetings, failure messages, and max history on LLM or MLLM vendor
  options instead of the top-level Agent fields.

  Mark the Agent-level helpers as compatibility shims and keep examples
  aligned with the serialized request shape.
diff --git a/README.md b/README.md
@@ -58,10 +58,6 @@ def start_conversation() -> str:
 
     agent = Agent(
         name=f"conversation-{int(time.time())}",
-        instructions=AGENT_PROMPT,
-        greeting=GREETING,
-        failure_message="Please wait a moment.",
-        max_history=50,
         turn_detection={
             "config": {
                 "speech_threshold": 0.5,
@@ -96,9 +92,10 @@ def start_conversation() -> str:
     ).with_llm(
         OpenAI(
             model="gpt-4o-mini",
+            system_messages=[{"role": "system", "content": AGENT_PROMPT}],
             greeting_message=GREETING,
             failure_message="Please wait a moment.",
-            max_history=15,
+            max_history=50,
             params={
                 "max_tokens": 1024,
                 "temperature": 0.7,
@@ -134,10 +131,7 @@ def start_conversation() -> str:
 Use the same `Agent` builder shape, but provide credentials explicitly when you want vendor-managed billing and routing instead of Agora-managed models.
 
 ```python
-agent = Agent(
-    instructions=AGENT_PROMPT,
-    greeting=GREETING,
-).with_stt(
+agent = Agent().with_stt(
     DeepgramSTT(
         api_key=os.environ["DEEPGRAM_API_KEY"],
         model="nova-3",
@@ -147,6 +141,8 @@ agent = Agent(
     OpenAI(
         api_key=os.environ["OPENAI_API_KEY"],
         model="gpt-4o-mini",
+        system_messages=[{"role": "system", "content": AGENT_PROMPT}],
+        greeting_message=GREETING,
         max_tokens=1024,
         temperature=0.7,
         top_p=0.95,
diff --git a/docs/concepts/agent.md b/docs/concepts/agent.md
@@ -12,24 +12,27 @@ The `Agent` class is a fluent builder for configuring AI agent properties. It co
 
 <!-- snippet: executable -->
 ```python
-from agora_agent import Agent
-
-agent = Agent(
-    name='support-assistant',
-    instructions='You are a helpful voice assistant.',
-    greeting='Hello! How can I help you?',
-    failure_message='Sorry, something went wrong.',
-    max_history=20,
+from agora_agent import Agent, OpenAI
+
+agent = Agent(name='support-assistant').with_llm(
+    OpenAI(
+        api_key='your-openai-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are a helpful voice assistant.'}],
+        greeting_message='Hello! How can I help you?',
+        failure_message='Sorry, something went wrong.',
+        max_history=20,
+    )
 )
 ```
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
 | `name` | `str` | No | Agent display name (used as session name if not overridden) |
-| `instructions` | `str` | No | System prompt for the LLM |
-| `greeting` | `str` | No | Message spoken when the agent joins |
-| `failure_message` | `str` | No | Message spoken on error |
-| `max_history` | `int` | No | Maximum conversation history length |
+| `instructions` | `str` | No | Deprecated. Use LLM vendor `system_messages` instead. |
+| `greeting` | `str` | No | Deprecated. Use LLM/MLLM vendor `greeting_message` instead. |
+| `failure_message` | `str` | No | Deprecated. Use LLM/MLLM vendor `failure_message` instead. |
+| `max_history` | `int` | No | Deprecated. Use LLM vendor `max_history` instead. |
 | `turn_detection` | `TurnDetectionConfig` | No | Turn detection settings |
 | `sal` | `SalConfig` | No | SAL (Speech Activity Level) configuration |
 | `advanced_features` | `Dict[str, Any]` | No | Advanced features (e.g., `{'enable_rtm': True}`) |
@@ -57,15 +60,15 @@ Each `with_*` method returns a **new** `Agent` instance — the original is unch
 
 | Method | Accepts | Purpose |
 |---|---|---|
-| `with_instructions(text)` | `str` | Override the system prompt |
-| `with_greeting(text)` | `str` | Override the greeting message |
+| `with_instructions(text)` | `str` | Deprecated. Use LLM vendor `system_messages` instead. |
+| `with_greeting(text)` | `str` | Deprecated. Use LLM/MLLM vendor `greeting_message` instead. |
 | `with_name(name)` | `str` | Override the agent name |
 | `with_turn_detection(config)` | `TurnDetectionConfig` | Override cascading-flow SOS/EOS detection; use `with_interruption()` for interruption behavior |
 | `with_sal(config)` | `SalConfig` | Set SAL configuration |
 | `with_advanced_features(features)` | `Dict[str, Any]` | Set advanced features |
 | `with_parameters(parameters)` | `SessionParams` | Set session parameters |
-| `with_failure_message(message)` | `str` | Set failure message |
-| `with_max_history(max_history)` | `int` | Set max history length |
+| `with_failure_message(message)` | `str` | Deprecated. Use LLM/MLLM vendor `failure_message` instead. |
+| `with_max_history(max_history)` | `int` | Deprecated. Use LLM vendor `max_history` instead. |
 | `with_geofence(geofence)` | `GeofenceConfig` | Set geofence configuration |
 | `with_labels(labels)` | `Dict[str, str]` | Set custom labels |
 | `with_rtc(rtc)` | `RtcConfig` | Set RTC configuration |
@@ -79,8 +82,12 @@ from agora_agent import Agent
 from agora_agent import OpenAI, ElevenLabsTTS, DeepgramSTT
 
 agent = (
-    Agent(name='my-agent', instructions='You are a helpful assistant.')
-    .with_llm(OpenAI(api_key='your-openai-key', model='gpt-4o-mini'))
+    Agent(name='my-agent')
+    .with_llm(OpenAI(
+        api_key='your-openai-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are a helpful assistant.'}],
+    ))
     .with_tts(ElevenLabsTTS(key='your-elevenlabs-key', model_id='eleven_flash_v2_5', voice_id='your-voice-id'))
     .with_stt(DeepgramSTT(api_key='your-deepgram-key', language='en-US'))
 )
@@ -97,8 +104,12 @@ from agora_agent import Agent, Agora, Area, OpenAI, ElevenLabsTTS, DeepgramSTT
 client = Agora(area=Area.US, app_id='your-app-id', app_certificate='your-app-certificate')
 
 base = (
-    Agent(instructions='You are a helpful assistant.')
-    .with_llm(OpenAI(api_key='your-openai-key', model='gpt-4o-mini'))
+    Agent()
+    .with_llm(OpenAI(
+        api_key='your-openai-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are a helpful assistant.'}],
+    ))
     .with_tts(ElevenLabsTTS(key='your-elevenlabs-key', model_id='eleven_flash_v2_5', voice_id='your-voice-id'))
     .with_stt(DeepgramSTT(api_key='your-deepgram-key', language='en-US'))
 )
diff --git a/docs/concepts/session.md b/docs/concepts/session.md
@@ -40,8 +40,12 @@ from agora_agent import Agent, Agora, Area, OpenAI, ElevenLabsTTS, DeepgramSTT
 client = Agora(area=Area.US, app_id='your-app-id', app_certificate='your-app-certificate')
 
 agent = (
-    Agent(name='my-agent', instructions='You are helpful.')
-    .with_llm(OpenAI(api_key='your-openai-key', model='gpt-4o-mini'))
+    Agent(name='my-agent')
+    .with_llm(OpenAI(
+        api_key='your-openai-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are helpful.'}],
+    ))
     .with_tts(ElevenLabsTTS(key='your-elevenlabs-key', model_id='eleven_flash_v2_5', voice_id='your-voice-id'))
     .with_stt(DeepgramSTT(api_key='your-deepgram-key', language='en-US'))
 )
diff --git a/docs/getting-started/authentication.md b/docs/getting-started/authentication.md
@@ -20,9 +20,12 @@ client = Agora(
 )
 
 agent = (
-    Agent(instructions="Be concise.")
+    Agent()
     .with_stt(DeepgramSTT(model="nova-3"))
-    .with_llm(OpenAI(model="gpt-4o-mini"))
+    .with_llm(OpenAI(
+        model="gpt-4o-mini",
+        system_messages=[{"role": "system", "content": "Be concise."}],
+    ))
     .with_tts(MiniMaxTTS(model="speech_2_6_turbo", voice_id="English_captivating_female1"))
 )
 
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -27,14 +27,14 @@ def main() -> None:
     )
 
     agent = (
-        Agent(
-            name="support-assistant",
-            instructions="You are a concise support voice assistant.",
-            greeting="Hello! How can I help you today?",
-            max_history=10,
-        )
+        Agent(name="support-assistant")
         .with_stt(DeepgramSTT(model="nova-3", language="en"))
-        .with_llm(OpenAI(model="gpt-4o-mini"))
+        .with_llm(OpenAI(
+            model="gpt-4o-mini",
+            system_messages=[{"role": "system", "content": "You are a concise support voice assistant."}],
+            greeting_message="Hello! How can I help you today?",
+            max_history=10,
+        ))
         .with_tts(MiniMaxTTS(model="speech_2_6_turbo", voice_id="English_captivating_female1"))
     )
 
diff --git a/docs/guides/agent-builder-features.md b/docs/guides/agent-builder-features.md
@@ -18,8 +18,8 @@ For string values with a finite set of options (e.g. `data_channel`, `sal_mode`,
 | `advanced_features` | `with_advanced_features(features)` | Enable MLLM, RTM, SAL, tools |
 | `tools` | `with_tools(enabled=True)` | Enable MCP tool invocation |
 | `parameters` | `with_parameters(params)` | Silence config, farewell config, data channel |
-| `failure_message` | `with_failure_message(msg)` | Message spoken when LLM fails |
-| `max_history` | `with_max_history(n)` | Max conversation turns in LLM context |
+| `failure_message` | LLM/MLLM vendor option | Message spoken when LLM fails |
+| `max_history` | LLM vendor option | Max conversation turns in LLM context |
 | `geofence` | `with_geofence(config)` | Restrict backend server regions |
 | `labels` | `with_labels(labels)` | Custom key-value labels (returned in callbacks) |
 | `rtc` | `with_rtc(config)` | RTC media encryption |
@@ -45,14 +45,17 @@ from agora_agent import (
 agent = (
     Agent(
         name='sal-assistant',
-        instructions='You are a helpful assistant.',
         advanced_features=AdvancedFeatures(enable_sal=True),
     )
     .with_sal(SalConfig(
         sal_mode=SalModeValues.LOCKING,
         sample_urls={'primary-speaker': 'https://example.com/voiceprint.pcm'},
     ))
-    .with_llm(OpenAI(api_key='your-key', model='gpt-4o-mini'))
+    .with_llm(OpenAI(
+        api_key='your-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are a helpful assistant.'}],
+    ))
     .with_tts(ElevenLabsTTS(key='your-key', model_id='eleven_flash_v2_5', voice_id='your-voice-id', sample_rate=24000))
     .with_stt(DeepgramSTT(api_key='your-key', model='nova-2', language='en-US'))
 )
@@ -114,23 +117,14 @@ agent = (
 ## Failure Message and Max History
 
 ```python
-agent = (
-    Agent(
-        name='assistant',
-        failure_message='Sorry, I encountered an error. Please try again.',
-        max_history=20,
-    )
-    .with_llm(OpenAI(api_key='...', model='gpt-4o-mini'))
-    .with_tts(ElevenLabsTTS(key='...', model_id='...', voice_id='...', sample_rate=24000))
-    .with_stt(DeepgramSTT(api_key='...', model='nova-2'))
-)
-
-# Or via builder methods
 agent = (
     Agent()
-    .with_failure_message('Something went wrong.')
-    .with_max_history(15)
-    .with_llm(OpenAI(api_key='...', model='gpt-4o-mini'))
+    .with_llm(OpenAI(
+        api_key='...',
+        model='gpt-4o-mini',
+        failure_message='Something went wrong.',
+        max_history=15,
+    ))
     .with_tts(ElevenLabsTTS(key='...', model_id='...', voice_id='...', sample_rate=24000))
     .with_stt(DeepgramSTT(api_key='...', model='nova-2'))
 )
@@ -245,13 +239,12 @@ Read back configuration via properties:
 from agora_agent import Agent, GeofenceConfig, GeofenceArea
 
 agent = (
-    Agent(max_history=20)
+    Agent()
     .with_geofence(GeofenceConfig(area=GeofenceArea.EUROPE))
     .with_labels({'env': 'staging'})
 )
 
 agent.name           # str | None
-agent.max_history    # 20
 agent.geofence       # GeofenceConfig(area='EUROPE')
 agent.labels         # {'env': 'staging'}
 agent.sal            # SalConfig | None
@@ -293,14 +286,15 @@ client = Agora(
 )
 
 agent = (
-    Agent(
-        name='full-featured-assistant',
-        instructions='You are a helpful voice assistant.',
-        greeting='Hello! How can I help?',
+    Agent(name='full-featured-assistant')
+    .with_llm(OpenAI(
+        api_key='your-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are a helpful voice assistant.'}],
+        greeting_message='Hello! How can I help?',
         failure_message='Sorry, I had trouble processing that.',
         max_history=20,
-    )
-    .with_llm(OpenAI(api_key='your-key', model='gpt-4o-mini'))
+    ))
     .with_tts(ElevenLabsTTS(key='your-key', model_id='eleven_flash_v2_5', voice_id='your-voice-id', sample_rate=24000))
     .with_stt(DeepgramSTT(api_key='your-key', model='nova-2', language='en-US'))
     .with_advanced_features(AdvancedFeatures(enable_rtm=True))
diff --git a/docs/guides/avatars.md b/docs/guides/avatars.md
@@ -54,8 +54,12 @@ client = Agora(
 )
 
 agent = (
-    Agent(name='avatar-agent', instructions='You are a helpful assistant with a visual avatar.')
-    .with_llm(OpenAI(api_key='your-openai-key', model='gpt-4o-mini'))
+    Agent(name='avatar-agent')
+    .with_llm(OpenAI(
+        api_key='your-openai-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are a helpful assistant with a visual avatar.'}],
+    ))
     .with_tts(ElevenLabsTTS(
         key='your-elevenlabs-key',
         model_id='eleven_flash_v2_5',
@@ -100,8 +104,12 @@ Akool requires a TTS vendor configured at 16000 Hz:
 from agora_agent import ElevenLabsTTS, AkoolAvatar
 
 agent = (
-    Agent(name='akool-agent', instructions='You are a helpful assistant.')
-    .with_llm(OpenAI(api_key='your-openai-key', model='gpt-4o-mini'))
+    Agent(name='akool-agent')
+    .with_llm(OpenAI(
+        api_key='your-openai-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are a helpful assistant.'}],
+    ))
     .with_tts(ElevenLabsTTS(
         key='your-elevenlabs-key',
         model_id='eleven_flash_v2_5',
@@ -124,8 +132,12 @@ This example shows what happens when the TTS sample rate does not match the avat
 ```python
 # This raises ValueError at build time
 agent = (
-    Agent(name='broken-agent', instructions='You are a helpful assistant.')
-    .with_llm(OpenAI(api_key='your-openai-key', model='gpt-4o-mini'))
+    Agent(name='broken-agent')
+    .with_llm(OpenAI(
+        api_key='your-openai-key',
+        model='gpt-4o-mini',
+        system_messages=[{'role': 'system', 'content': 'You are a helpful assistant.'}],
+    ))
     .with_tts(ElevenLabsTTS(
         key='your-elevenlabs-key',
         model_id='eleven_flash_v2_5',
@@ -152,7 +164,7 @@ The `with_avatar()` call validates against the currently configured TTS. Always
 ```python
 # Correct order: TTS first, then avatar
 agent = (
-    Agent(name='my-agent', instructions='You are helpful.')
+    Agent(name='my-agent')
     .with_tts(ElevenLabsTTS(key='your-elevenlabs-key', model_id='eleven_flash_v2_5', voice_id='your-voice-id', sample_rate=24000))
     .with_avatar(HeyGenAvatar(api_key='your-heygen-key', quality='medium', agora_uid='2'))
 )
diff --git a/docs/guides/byok.md b/docs/guides/byok.md
@@ -32,12 +32,7 @@ def main() -> None:
 
     # In BYOK mode, each vendor carries its own credentials.
     agent = (
-        Agent(
-            name="support-assistant",
-            instructions="You are a concise support voice assistant.",
-            greeting="Hello! How can I help you today?",
-            max_history=10,
-        )
+        Agent(name="support-assistant")
         .with_stt(
             DeepgramSTT(
                 api_key=os.environ["DEEPGRAM_API_KEY"],
@@ -49,6 +44,9 @@ def main() -> None:
             OpenAI(
                 api_key=os.environ["OPENAI_API_KEY"],
                 model="gpt-4o-mini",
+                system_messages=[{"role": "system", "content": "You are a concise support voice assistant."}],
+                greeting_message="Hello! How can I help you today?",
+                max_history=10,
             )
         )
         .with_tts(
diff --git a/docs/guides/cascading-flow.md b/docs/guides/cascading-flow.md
diff --git a/docs/reference/agent.md b/docs/reference/agent.md

Original file line number	Diff line number	Diff line change
`@@ -20,9 +20,12 @@ client = Agora(`
`20`	`20`	`)`
`21`	`21`
`22`	`22`	`agent = (`
`23`		`- Agent(instructions="Be concise.")`
	`23`	`+ Agent()`
`24`	`24`	`.with_stt(DeepgramSTT(model="nova-3"))`
`25`		`- .with_llm(OpenAI(model="gpt-4o-mini"))`
	`25`	`+ .with_llm(OpenAI(`
	`26`	`+ model="gpt-4o-mini",`
	`27`	`+ system_messages=[{"role": "system", "content": "Be concise."}],`
	`28`	`+ ))`
`26`	`29`	`.with_tts(MiniMaxTTS(model="speech_2_6_turbo", voice_id="English_captivating_female1"))`
`27`	`30`	`)`
`28`	`31`