added token auth, token expiry options, client stop

Author: digitallysavvy

docs/getting-started/authentication.md

@@ -68,11 +68,35 @@ client = AsyncAgora(
 )
 ```
 
+## Pre-built token
+
+Pass a manually generated `agora token=...` string via `auth_token`. Use this for debugging or when you want to control the REST API token lifecycle yourself:
+
+```python
+from agora_agent import Agora, Area
+from agora_agent.agentkit.token import generate_convo_ai_token
+
+raw_token = generate_convo_ai_token(
+    app_id='your-app-id',
+    app_certificate='your-app-certificate',
+    channel_name='your-channel',
+    account='1',
+)
+
+client = Agora(
+    area=Area.US,
+    app_id='your-app-id',
+    app_certificate='your-app-certificate',
+    auth_token=raw_token,  # SDK sets Authorization: agora token=<raw_token>
+)
+```
+
 ## Auth Mode Comparison
 
 | Mode | When to use | What you need |
 |---|---|---|
 | **App credentials** | Most applications. SDK manages ConvoAI tokens per request. | `app_id` + `app_certificate` |
+| **Pre-built token** | Debugging, or when you manage the REST API token lifecycle. | `app_id` + `app_certificate` + `auth_token` |
 | **Basic Auth** | When using customer-level credentials from the Agora Console. | `app_id` + `app_certificate` + `customer_id` + `customer_secret` |
 
 ## Advanced: Manual Token Generation
@@ -88,16 +112,16 @@ rtc_token = generate_rtc_token(
     app_certificate='your-app-certificate',
     channel='your-channel',
     uid=1,
-    expiry_seconds=3600,
+    expiry_seconds=86400,  # default; max allowed by Agora is 24 hours (86400 s)
 )
 
-# ConvoAI token (RTC + RTM combined, for REST API auth)
+# ConvoAI token (RTC + RTM combined, for REST API auth and channel join)
 convo_token = generate_convo_ai_token(
     app_id='your-app-id',
     app_certificate='your-app-certificate',
     channel_name='your-channel',
     account='1001',
-    token_expire=3600,
+    token_expire=86400,  # default; max allowed by Agora is 24 hours (86400 s)
 )
 auth_header = f'agora token={convo_token}'
 ```
@@ -111,7 +135,7 @@ auth_header = f'agora token={convo_token}'
 | `channel` | `str` | Yes | — | Channel name |
 | `uid` | `int` | Yes | — | User ID (0 = any) |
 | `role` | `int` | No | `ROLE_PUBLISHER` (1) | RTC role (`ROLE_PUBLISHER` or `ROLE_SUBSCRIBER`) |
-| `expiry_seconds` | `int` | No | `3600` | Token expiry in seconds |
+| `expiry_seconds` | `int` | No | `86400` | Token expiry in seconds (max: 86400 = 24 h) |
 
 ### `generate_convo_ai_token()` Reference
 
@@ -121,9 +145,28 @@ auth_header = f'agora token={convo_token}'
 | `app_certificate` | `str` | Yes | — | Agora App Certificate |
 | `channel_name` | `str` | Yes | — | Channel the agent will join |
 | `account` | `str` | Yes | — | Agent UID as a string (e.g. `"1001"`) |
-| `token_expire` | `int` | No | `3600` | Seconds until token expires |
+| `token_expire` | `int` | No | `86400` | Seconds until token expires (max: 86400 = 24 h) |
 | `privilege_expire` | `int` | No | `0` | Seconds until privileges expire (0 = same as `token_expire`) |
 
+## Token expiry
+
+When the SDK auto-generates a token (app credentials mode, or session without a pre-built `token`), the default lifetime is **86400 seconds (24 hours)** — the Agora maximum. You can customise this via `expires_in` on `create_session()`:
+
+```python
+from agora_agent.agentkit import expires_in_hours, expires_in_minutes
+
+session = agent.create_session(
+    client,
+    channel='room-123',
+    agent_uid='1',
+    remote_uids=['100'],
+    expires_in=expires_in_hours(12),    # 12-hour token
+    # expires_in=expires_in_minutes(30),  # 30-minute token
+)
+```
+
+`expires_in_hours()` and `expires_in_minutes()` validate the value and raise `ValueError` if it is ≤ 0, or warn and cap at 86400 if it exceeds 24 hours. Valid range: **1–86400 seconds**.
+
 ## Areas
 
 The `area` parameter determines which Agora region your requests are routed to:

docs/reference/agent.md

@@ -115,6 +115,7 @@ create_session(
     token: Optional[str] = None,
     idle_timeout: Optional[int] = None,
     enable_string_uid: Optional[bool] = None,
+    expires_in: Optional[int] = None,
 ) -> AgentSession
 ```
 
@@ -127,7 +128,8 @@ Creates an `AgentSession` bound to the given client and channel.
 | `agent_uid` | `str` | Yes | UID for the agent |
 | `remote_uids` | `List[str]` | Yes | UIDs of remote participants |
 | `name` | `Optional[str]` | No | Session name (defaults to agent name) |
-| `token` | `Optional[str]` | No | Pre-built RTC token |
+| `token` | `Optional[str]` | No | Pre-built RTC+RTM token |
+| `expires_in` | `Optional[int]` | No | Token lifetime in seconds (default: `86400` = 24 h, Agora max). Only applies when the token is auto-generated. Use `expires_in_hours()` or `expires_in_minutes()` for clarity. Valid range: 1–86400. |
 | `idle_timeout` | `Optional[int]` | No | Idle timeout in seconds |
 | `enable_string_uid` | `Optional[bool]` | No | Enable string UIDs |
 

src/agora_agent/agentkit/__init__.py

@@ -1,6 +1,14 @@
 from .agent import Agent
 from .agent_session import AgentSession, AgentSessionOptions, AsyncAgentSession
-from .token import GenerateConvoAITokenOptions, GenerateTokenOptions, generate_convo_ai_token, generate_rtc_token
+from .token import (
+    GenerateConvoAITokenOptions,
+    GenerateTokenOptions,
+    MAX_EXPIRY_SECONDS,
+    generate_convo_ai_token,
+    generate_rtc_token,
+    expires_in_hours,
+    expires_in_minutes,
+)
 from .vendors import (
     AkoolAvatar,
     AmazonSTT,
@@ -51,6 +59,9 @@
     "GenerateTokenOptions",
     "generate_convo_ai_token",
     "GenerateConvoAITokenOptions",
+    "MAX_EXPIRY_SECONDS",
+    "expires_in_hours",
+    "expires_in_minutes",
     "BaseLLM",
     "BaseTTS",
     "BaseSTT",

src/agora_agent/agentkit/agent.py

@@ -10,7 +10,7 @@
 from ..agents.types.start_agents_request_properties_turn_detection import StartAgentsRequestPropertiesTurnDetection
 from ..agents.types.start_agents_request_properties_sal import StartAgentsRequestPropertiesSal
 from ..agents.types.start_agents_request_properties_parameters import StartAgentsRequestPropertiesParameters
-from .token import generate_rtc_token
+from .token import generate_convo_ai_token, _validate_expires_in
 from .vendors.base import BaseAvatar, BaseLLM, BaseMLLM, BaseSTT, BaseTTS
 
 TurnDetectionConfig = StartAgentsRequestPropertiesTurnDetection
@@ -178,6 +178,7 @@ def create_session(
         token: typing.Optional[str] = None,
         idle_timeout: typing.Optional[int] = None,
         enable_string_uid: typing.Optional[bool] = None,
+        expires_in: typing.Optional[int] = None,
     ) -> "AgentSession":
         from .agent_session import AgentSession
 
@@ -194,6 +195,7 @@ def create_session(
             remote_uids=remote_uids,
             idle_timeout=idle_timeout,
             enable_string_uid=enable_string_uid,
+            expires_in=expires_in,
         )
 
     def create_async_session(
@@ -206,6 +208,7 @@ def create_async_session(
         token: typing.Optional[str] = None,
         idle_timeout: typing.Optional[int] = None,
         enable_string_uid: typing.Optional[bool] = None,
+        expires_in: typing.Optional[int] = None,
     ) -> "AsyncAgentSession":
         """Create an async session for use with :class:`~agora_agent.AsyncAgora`.
 
@@ -227,6 +230,7 @@ def create_async_session(
             remote_uids=remote_uids,
             idle_timeout=idle_timeout,
             enable_string_uid=enable_string_uid,
+            expires_in=expires_in,
         )
 
     def to_properties(
@@ -239,17 +243,23 @@ def to_properties(
         token: typing.Optional[str] = None,
         app_id: typing.Optional[str] = None,
         app_certificate: typing.Optional[str] = None,
-        token_expiry_seconds: typing.Optional[int] = None,
+        expires_in: typing.Optional[int] = None,
     ) -> StartAgentsRequestProperties:
         if token is None:
             if app_id is None or app_certificate is None:
                 raise ValueError("Either token or app_id+app_certificate must be provided")
-            token = generate_rtc_token(
+            validated_expires_in = _validate_expires_in(expires_in) if expires_in is not None else None
+            # Use generate_convo_ai_token (RTC + RTM) so the token works whether or
+            # not the caller enables advanced_features.enable_rtm.
+            token_kwargs: typing.Dict[str, typing.Any] = {}
+            if validated_expires_in is not None:
+                token_kwargs["token_expire"] = validated_expires_in
+            token = generate_convo_ai_token(
                 app_id=app_id,
                 app_certificate=app_certificate,
-                channel=channel,
-                uid=int(agent_uid),
-                expiry_seconds=token_expiry_seconds or 3600,
+                channel_name=channel,
+                account=agent_uid,
+                **token_kwargs,
             )
 
         is_mllm_mode = (

src/agora_agent/agentkit/agent_session.py

@@ -27,13 +27,14 @@ class AgentSessionOptions(_AgentSessionRequiredOptions, total=False):
 
     Optional fields
     ---------------
-    app_certificate, token, idle_timeout, enable_string_uid
+    app_certificate, token, idle_timeout, enable_string_uid, expires_in
     """
 
     app_certificate: str
     token: str
     idle_timeout: int
     enable_string_uid: bool
+    expires_in: int
 
 
 class _AgentSessionBase:
@@ -56,6 +57,7 @@ def __init__(
         token: typing.Optional[str] = None,
         idle_timeout: typing.Optional[int] = None,
         enable_string_uid: typing.Optional[bool] = None,
+        expires_in: typing.Optional[int] = None,
     ):
         self._client = client
         self._agent = agent
@@ -68,6 +70,7 @@ def __init__(
         self._remote_uids = remote_uids
         self._idle_timeout = idle_timeout
         self._enable_string_uid = enable_string_uid
+        self._expires_in = expires_in
         self._agent_id: typing.Optional[str] = None
         self._status: str = "idle"
         self._event_handlers: typing.Dict[str, typing.List[typing.Callable[..., None]]] = {}
@@ -241,6 +244,7 @@ def start(self) -> str:
                 token_opts = {
                     "app_id": self._app_id,
                     "app_certificate": self._app_certificate,
+                    "expires_in": self._expires_in,
                 }
 
             properties = self._agent.to_properties(
@@ -432,6 +436,7 @@ async def start(self) -> str:
                 token_opts = {
                     "app_id": self._app_id,
                     "app_certificate": self._app_certificate,
+                    "expires_in": self._expires_in,
                 }
 
             properties = self._agent.to_properties(

src/agora_agent/agentkit/token.py

@@ -7,12 +7,71 @@
 import typing
 import zlib
 
-DEFAULT_EXPIRY_SECONDS = 3600
+DEFAULT_EXPIRY_SECONDS = 86400
+MAX_EXPIRY_SECONDS = 86400
 
 ROLE_PUBLISHER = 1
 ROLE_SUBSCRIBER = 2
 
 
+def _validate_expires_in(seconds: float) -> int:
+    """Validate an ``expires_in`` value in seconds.
+
+    - Raises :class:`ValueError` if ``seconds <= 0``.
+    - Warns and caps at :data:`MAX_EXPIRY_SECONDS` if ``seconds > MAX_EXPIRY_SECONDS``.
+    """
+    import warnings
+
+    if seconds <= 0:
+        raise ValueError("expires_in must be between 1 and 86400 seconds (24h)")
+    if seconds > MAX_EXPIRY_SECONDS:
+        warnings.warn("agora-agent-sdk: expires_in capped at 24h (Agora max)", stacklevel=3)
+        return MAX_EXPIRY_SECONDS
+    return int(seconds)
+
+
+def expires_in_hours(hours: float) -> int:
+    """Convert hours to seconds for use as ``expires_in``.
+
+    Parameters
+    ----------
+    hours : float
+        Number of hours. Must be > 0 and result must not exceed 24 hours (86400 s).
+
+    Returns
+    -------
+    int
+        Equivalent seconds, capped at :data:`MAX_EXPIRY_SECONDS`.
+
+    Raises
+    ------
+    ValueError
+        If ``hours <= 0``.
+    """
+    return _validate_expires_in(hours * 3600)
+
+
+def expires_in_minutes(minutes: float) -> int:
+    """Convert minutes to seconds for use as ``expires_in``.
+
+    Parameters
+    ----------
+    minutes : float
+        Number of minutes. Must be > 0 and result must not exceed 24 hours (86400 s).
+
+    Returns
+    -------
+    int
+        Equivalent seconds, capped at :data:`MAX_EXPIRY_SECONDS`.
+
+    Raises
+    ------
+    ValueError
+        If ``minutes <= 0``.
+    """
+    return _validate_expires_in(minutes * 60)
+
+
 class GenerateTokenOptions(typing.TypedDict, total=False):
     app_id: str
     app_certificate: str
@@ -149,7 +208,7 @@ def generate_rtc_token(
     role : int
         RTC role (ROLE_PUBLISHER or ROLE_SUBSCRIBER).
     expiry_seconds : int
-        Token expiry in seconds (default 3600).
+        Token expiry in seconds (default 86400).
 
     Returns
     -------
@@ -206,7 +265,7 @@ def generate_convo_ai_token(
     account : str
         String account identity — pass the agent UID as a string (e.g. "1001").
     token_expire : int
-        Seconds until the token expires (default 3600).
+        Seconds until the token expires (default 86400).
     privilege_expire : int
         Seconds until privileges expire; 0 means same as token_expire (default 0).