Merge pull request #37 from seymourtang/feat/add-cn-prefix

feat:add CN vendor support

Author: plutoless

.gitignore

@@ -3,3 +3,4 @@
 __pycache__/
 dist/
 poetry.toml
+.venv/

README.md

@@ -19,7 +19,7 @@ pip install agora-agents
 
 ## Quick Start
 
-Start with the `Agent` builder: create a client with app credentials, choose your ASR, LLM, and TTS providers, then start a session. Omit vendor API keys for supported Agora-managed models, or provide keys when you want BYOK.
+Start with the `Agent` builder: create a client with app credentials, pass it to `Agent(client=client, ...)`, choose your ASR, LLM, and TTS providers, then start a session. Omit vendor API keys for supported Agora-managed global models, or provide keys when you want BYOK.
 Set Agora interaction language with `turn_detection.language`; provider-specific STT language values remain under `asr.params`. Ares uses only the REST `asr.language` value sourced from `turn_detection.language`.
 
 ```python
@@ -31,8 +31,8 @@ from agora_agent import (
     Agora,
     Area,
     DeepgramSTT,
-    MiniMaxTTS,
     OpenAI,
+    MiniMaxTTS,
     expires_in_hours,
 )
 
@@ -54,7 +54,7 @@ def start_conversation() -> str:
         app_certificate=app_certificate,
     )
 
-    agent = Agent(name=f"conversation-{int(time.time())}", turn_detection={"language": "en-US"}).with_stt(
+    agent = Agent(client=client, turn_detection={"language": "en-US"}).with_stt(
         DeepgramSTT(
             model="nova-3",
             language="en",
@@ -80,10 +80,10 @@ def start_conversation() -> str:
     )
 
     session = agent.create_session(
-        client,
         channel=f"demo-channel-{int(time.time())}",
         agent_uid="123456",
         remote_uids=["*"],
+        name=f"conversation-{int(time.time())}",
         idle_timeout=30,
         expires_in=expires_in_hours(1),
         debug=False,
@@ -94,35 +94,42 @@ def start_conversation() -> str:
 
 ### Why no token or vendor key in the example?
 
-`Agora` generates the required ConvoAI REST auth and RTC join tokens automatically when you provide `app_id` and `app_certificate`. For supported Agora-managed models, leave vendor API keys unset; provide keys when you want BYOK.
+`Agora` generates the required ConvoAI REST auth and RTC join tokens automatically when you provide `app_id` and `app_certificate`. For supported Agora-managed global models, leave vendor API keys unset; provide keys when you want BYOK. CN MiniMax TTS is not Agora-managed in the same way and typically includes `key`.
+
+### Regional agent builders
+
+Bind the client once with `Agent(client=client, ...)` and pass vendor classes directly such as `OpenAI(...)` or `MiniMaxTTS(...)`. The bound client selects the API routing region and provides IDE hints via `CNAgent` / `GlobalAgent`, but does not restrict which vendor classes you can use. See `[docs/guides/regional-routing.md](./docs/guides/regional-routing.md)` for regional examples.
 
 ## AI Studio pipeline IDs
 
 Use `pipeline_id` when you want a published AI Studio pipeline to provide the base agent configuration:
 
 ```python
+import time
+# client = Agora(area=Area.US, app_id="...", app_certificate="...")
 agent = Agent(
-    name="support",
+    client=client,
     pipeline_id="studio-pipeline-id",
 )
 
 session = agent.create_session(
-    client,
-    channel="support-room",
+    channel=f"demo-channel-{int(time.time())}",
     agent_uid="1",
     remote_uids=["100"],
+    name=f"conversation-{int(time.time())}",
 )
 ```
 
 You can override it per session:
 
 ```python
+import time
 session = agent.create_session(
-    client,
-    channel="support-room",
+    channel=f"demo-channel-{int(time.time())}",
     agent_uid="1",
     remote_uids=["100"],
     pipeline_id="session-pipeline-id",
+    name=f"conversation-{int(time.time())}",
 )
 ```
 
@@ -133,7 +140,7 @@ AgentKit sends the resolved value as the top-level `/join` field `pipeline_id`,
 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(turn_detection={"language": "en-US"}).with_stt(
+agent = Agent(client=client, turn_detection={"language": "en-US"}).with_stt(
     DeepgramSTT(
         api_key=os.environ["DEEPGRAM_API_KEY"],
         model="nova-3",
@@ -151,12 +158,11 @@ agent = Agent(turn_detection={"language": "en-US"}).with_stt(
         top_p=0.95,
     )
 ).with_tts(
-    MiniMaxTTS(
-        key=os.environ["MINIMAX_API_KEY"],
-        group_id=os.environ["MINIMAX_GROUP_ID"],
-        model="speech_2_6_turbo",
-        voice_id="English_captivating_female1",
-        url="wss://api-uw.minimax.io/ws/v1/t2a_v2",
+    ElevenLabsTTS(
+        key=os.environ["ELEVENLABS_API_KEY"],
+        model_id="eleven_flash_v2_5",
+        voice_id=os.environ["ELEVENLABS_VOICE_ID"],
+        base_url="wss://api.elevenlabs.io/v1",
     )
 )
 ```
@@ -174,15 +180,30 @@ If you want to bring your own vendor credentials instead of using Agora-managed
 Use `with_mllm()` for OpenAI Realtime, Gemini Live, Vertex AI, or xAI Grok. No STT, LLM, or TTS vendor is needed when MLLM mode is enabled.
 
 ```python
-from agora_agent import Agent, OpenAIRealtime
+from agora_agent import Agent, Agora, Area, OpenAIRealtime
+import time
 
-agent = Agent(name="realtime-assistant").with_mllm(
+client = Agora(
+    area=Area.US,
+    app_id=os.environ["AGORA_APP_ID"],
+    app_certificate=os.environ["AGORA_APP_CERTIFICATE"],
+)
+
+agent = Agent(client=client).with_mllm(
     OpenAIRealtime(
         api_key=os.environ["OPENAI_API_KEY"],
         model="gpt-4o-realtime-preview",
         greeting_message="Hello! Ready to chat.",
     )
 )
+
+session = agent.create_session(
+    channel=f"demo-channel-{int(time.time())}",
+    agent_uid="1",
+    remote_uids=["*"],
+    name=f"conversation-{int(time.time())}",
+)
+session.start()
 ```
 
 See the [MLLM Flow guide](./docs/guides/mllm-flow.md) for full examples with Gemini Live and Vertex AI.
@@ -333,4 +354,4 @@ otherwise they would be overwritten upon the next generated release. Feel free t
 a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
 an issue first to discuss with us!
 
-On the other hand, contributions to the README are always very welcome!
+On the other hand, contributions to the README are always very welcome!

docs/concepts/agent.md

@@ -6,15 +6,17 @@ description: The Agent builder — configure an AI agent with LLM, TTS, STT, and
 
 # Agent
 
-The `Agent` class is a fluent builder for configuring AI agent properties. It collects vendor settings (LLM, TTS, STT, MLLM, avatar) and session parameters, then produces a fully configured `AgentSession` when you call `create_session()`.
+The `Agent` class is a fluent builder for configuring AI agent properties. Pass a bound `Agora` or `AsyncAgora` client with `client=...` — it is required for `create_session()` and `create_async_session()`. The builder collects vendor settings (LLM, TTS, STT, MLLM, avatar) and produces a fully configured `AgentSession` when you call `create_session()`. The agent instance name is set on `create_session(name=...)`, not on the `Agent` constructor.
 
 ## Constructor
 
 <!-- snippet: executable -->
 ```python
-from agora_agent import Agent, OpenAI
+from agora_agent import Agent, Agora, Area, OpenAI
 
-agent = Agent(name='support-assistant').with_llm(
+client = Agora(area=Area.US, app_id='your-app-id', app_certificate='your-app-certificate')
+
+agent = Agent(client=client).with_llm(
     OpenAI(
         api_key='your-openai-key',
         base_url='https://api.openai.com/v1/chat/completions',
@@ -29,7 +31,8 @@ agent = Agent(name='support-assistant').with_llm(
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `name` | `str` | No | Agent display name (used as session name if not overridden) |
+| `client` | `Agora` / `AsyncAgora` | Yes | Authenticated client from `Agora(...)` or `AsyncAgora(...)`. Required for `create_session()` and `create_async_session()`. |
+| `pipeline_id` | `str` | No | Published AI Studio pipeline ID used as this agent's base configuration |
 | `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. |
@@ -43,6 +46,8 @@ agent = Agent(name='support-assistant').with_llm(
 | `rtc` | `RtcConfig` | No | RTC media encryption |
 | `filler_words` | `FillerWordsConfig` | No | Filler words while waiting for LLM |
 
+When `client` is provided, `Agent(client=...)` returns `CNAgent` for `Area.CN` and `GlobalAgent` for global areas.
+
 ## Builder Methods
 
 Each `with_*` method returns a **new** `Agent` instance — the original is unchanged. This immutability lets you safely reuse a base configuration for multiple sessions.
@@ -63,7 +68,6 @@ Each `with_*` method returns a **new** `Agent` instance — the original is unch
 |---|---|---|
 | `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` | Configure `turn_detection.language` and 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 |
@@ -79,11 +83,12 @@ Each `with_*` method returns a **new** `Agent` instance — the original is unch
 
 <!-- snippet: executable -->
 ```python
-from agora_agent import Agent
-from agora_agent import OpenAI, ElevenLabsTTS, DeepgramSTT
+from agora_agent import Agent, Agora, Area, DeepgramSTT, ElevenLabsTTS, OpenAI
+
+client = Agora(area=Area.US, app_id='your-app-id', app_certificate='your-app-certificate')
 
 agent = (
-    Agent(name='my-agent')
+    Agent(client=client)
     .with_llm(OpenAI(
         api_key='your-openai-key',
         base_url='https://api.openai.com/v1/chat/completions',
@@ -101,12 +106,13 @@ Because each `with_*` call returns a new `Agent`, you can build a base configura
 
 <!-- snippet: executable -->
 ```python
-from agora_agent import Agent, Agora, Area, OpenAI, ElevenLabsTTS, DeepgramSTT
+from agora_agent import Agent, Agora, Area, DeepgramSTT, ElevenLabsTTS, OpenAI
+import time
 
 client = Agora(area=Area.US, app_id='your-app-id', app_certificate='your-app-certificate')
 
 base = (
-    Agent()
+    Agent(client=client)
     .with_llm(OpenAI(
         api_key='your-openai-key',
         base_url='https://api.openai.com/v1/chat/completions',
@@ -117,23 +123,23 @@ base = (
     .with_stt(DeepgramSTT(api_key='your-deepgram-key', language='en-US'))
 )
 
-# Same agent config, different channels
-session_a = base.create_session(client, channel='room-a', agent_uid='1', remote_uids=['100'])
-session_b = base.create_session(client, channel='room-b', agent_uid='1', remote_uids=['200'])
+# Same agent config, different channels and session names
+session_a = base.create_session(channel=f"demo-channel-{int(time.time())}", agent_uid='1', remote_uids=['100'], name=f"conversation-{int(time.time())}")
+session_b = base.create_session(channel=f"demo-channel-{int(time.time())}", agent_uid='1', remote_uids=['200'], name=f"conversation-{int(time.time())}")
 ```
 
 ## `create_session()`
 
-Creates a new `AgentSession` bound to a client and channel.
+Creates a new `AgentSession` using the client already bound to the agent. Pass the agent instance name via the `name` parameter here — it is sent to the Start Agent API when the session starts.
 
 <!-- snippet: fragment -->
 ```python
+import time
 session = agent.create_session(
-    client,
-    channel='my-channel',
+    channel=f"demo-channel-{int(time.time())}",
     agent_uid='1',
     remote_uids=['100'],
-    name='optional-session-name',
+    name=f"conversation-{int(time.time())}",
     token='optional-pre-built-token',
     idle_timeout=300,
     enable_string_uid=True,
@@ -142,11 +148,10 @@ session = agent.create_session(
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `client` | `Agora` or `AsyncAgora` | Yes | The authenticated client |
 | `channel` | `str` | Yes | Agora channel name |
 | `agent_uid` | `str` | Yes | UID for the agent in the channel |
 | `remote_uids` | `List[str]` | Yes | UIDs of remote participants to listen to |
-| `name` | `str` | No | Session name (defaults to agent name or auto-generated) |
+| `name` | `str` | No | Agent instance name for the Start Agent API (defaults to `agent-{timestamp}` if omitted) |
 | `token` | `str` | No | Pre-built RTC token (if not provided, generated from client credentials) |
 | `idle_timeout` | `int` | No | Idle timeout in seconds |
 | `enable_string_uid` | `bool` | No | Enable string UIDs |
@@ -165,7 +170,6 @@ See [Avatar Integration](../guides/avatars.md) for details.
 
 | Property | Type | Description |
 |---|---|---|
-| `agent.name` | `Optional[str]` | Agent name |
 | `agent.instructions` | `Optional[str]` | System prompt |
 | `agent.greeting` | `Optional[str]` | Greeting message |
 | `agent.failure_message` | `Optional[str]` | Message spoken when LLM fails |

docs/concepts/architecture.md

@@ -26,7 +26,7 @@ The Python SDK has three layers:
 
 This is the primary developer-facing API. It provides:
 
-- **`Agent`** — a fluent builder for configuring AI agents with LLM, TTS, STT, MLLM, and avatar vendors
+- **`Agent`** — a fluent builder for configuring AI agents with LLM, TTS, STT, MLLM, and avatar vendors. Requires a bound `Agora` / `AsyncAgora` client via `client=...`.
 - **`AgentSession` / `AsyncAgentSession`** — lifecycle management for running agents (start, stop, say, interrupt)
 - **Vendor classes** — typed configuration for 28+ vendor integrations across 5 categories
 - **`generate_rtc_token()`** — helper for building RTC tokens

docs/concepts/session.md

@@ -8,6 +8,8 @@ description: Manage the full lifecycle of a running Agora Conversational AI agen
 
 `AgentSession` (sync) and `AsyncAgentSession` (async) manage the lifecycle of a running AI agent. They handle starting, stopping, sending speech, interrupting, updating configuration, and retrieving history.
 
+Presets are configured at session creation time when you use them explicitly. Most applications should configure vendors on the `Agent` builder instead — see [Quick Start](../getting-started/quick-start.md).
+
 ## State Machine
 
 An agent session moves through these states:
@@ -31,16 +33,17 @@ You can check the current state with `session.status`.
 
 ## Creating a Session
 
-Use `Agent.create_session()` to create a session:
+Use `Agent.create_session()` to create a session. The parent `Agent` must be constructed with `client=...`. Set the agent instance name with the `name` parameter — this value is sent to the Start Agent API when you call `session.start()`.
 
 <!-- snippet: executable -->
 ```python
-from agora_agent import Agent, Agora, Area, OpenAI, ElevenLabsTTS, DeepgramSTT
+from agora_agent import Agent, Agora, Area, DeepgramSTT, ElevenLabsTTS, OpenAI
+import time
 
 client = Agora(area=Area.US, app_id='your-app-id', app_certificate='your-app-certificate')
 
 agent = (
-    Agent(name='my-agent')
+    Agent(client=client)
     .with_llm(OpenAI(
         api_key='your-openai-key',
         base_url='https://api.openai.com/v1/chat/completions',
@@ -51,7 +54,7 @@ agent = (
     .with_stt(DeepgramSTT(api_key='your-deepgram-key', language='en-US'))
 )
 
-session = agent.create_session(client, channel='my-channel', agent_uid='1', remote_uids=['100'])
+session = agent.create_session(channel=f"demo-channel-{int(time.time())}", agent_uid='1', remote_uids=['100'], name=f"conversation-{int(time.time())}")
 ```
 
 ## Sync Methods
@@ -110,6 +113,32 @@ await session.stop()
 | Update | `session.update(props)` → `None` | `await session.update(props)` → `None` |
 | History | `session.get_history()` → response | `await session.get_history()` → response |
 | Info | `session.get_info()` → response | `await session.get_info()` → response |
+| Think | `session.think(options)` → response | `await session.think(options)` → response |
+| Turns | `session.get_turns(options)` → response | `await session.get_turns(options)` → response |
+| All turns | `session.get_all_turns(options)` → response | `await session.get_all_turns(options)` → response |
+
+## Agora-managed models and BYOK
+
+When you omit credentials for supported Agora-managed global models on the builder, AgentKit sends the matching Agora-managed configuration at session start. Pass your own vendor API keys when you need BYOK. CN MiniMax TTS is not Agora-managed in the same way and typically includes `key`.
+
+<!-- snippet: fragment -->
+```python
+from agora_agent import Agent, Agora, Area, DeepgramSTT, OpenAI, OpenAITTS
+
+client = Agora(area=Area.US, app_id='your-app-id', app_certificate='your-app-certificate')
+
+agent = (
+    Agent(client=client)
+    .with_stt(DeepgramSTT(model="nova-3", language="en-US"))
+    .with_llm(OpenAI(
+        model="gpt-4o-mini",
+        system_messages=[{"role": "system", "content": "Be concise."}],
+    ))
+    .with_tts(OpenAITTS(voice="alloy"))
+)
+```
+
+For explicit project-specific preset values and the full list of Agora-managed models, see [AgentSession Reference](../reference/session.md).
 
 ## Events
 
@@ -166,7 +195,8 @@ Session methods raise `RuntimeError` if called in an invalid state:
 
 <!-- snippet: fragment -->
 ```python
-session = agent.create_session(client, channel='my-channel', agent_uid='1', remote_uids=['100'])
+import time
+session = agent.create_session(channel=f"demo-channel-{int(time.time())}", agent_uid='1', remote_uids=['100'], name=f"conversation-{int(time.time())}")
 
 # This raises RuntimeError — session hasn't started yet
 session.say('Hello!')  # RuntimeError: Cannot say in idle state