Issue Description
When integrating the Agora Conversational AI (ConvAI) Engine, users may encounter issues during the Join API call.
Common symptoms include:
API call failing with the error:
"agent_rtc_uid: Input should be a valid string"Agent joining successfully, but the avatar audio/video does not render
The client shows a phantom user (e.g., UID
10053) or mismatchedagora_uid
These issues are related to incorrect UID formatting in the Join API request payload.
Platform/SDK
Product: Agora Conversational AI Engine
API Type: RESTful API (Join API)
Client Platform: Web
Error Message
"agent_rtc_uid: Input should be a valid string"
Step-by-Step Solution
✅ To fix the issue:
-
In your Join API request payload, keep:
"enable_string_uid": falseThis ensures the SDK operates in integer UID mode.
-
However, wrap both
agent_rtc_uidandremote_rtc_uidsvalues as strings:"agent_rtc_uid": "1299282093", "remote_rtc_uids": ["1519147601"] -
Ensure that:
The same UID values are used on the client side when joining the RTC channel.
All UIDs are below 2147483647 (valid 32-bit integer range).
Re-run the Join API request.
The response should now return HTTP200 OKand the agent will join the RTC channel correctly.-
Once connected:
Avatar video and audio should render correctly.
The “phantom” UID issue should disappear.
Root Cause
The Join API validates UID fields as strings, but internally, the ConvAI engine still uses integer-based RTC mode when enable_string_uid is set to false.
Passing numeric (non-string) UIDs directly leads to schema validation errors.
On the other hand, enabling enable_string_uid=true can cause avatar rendering issues due to string UID handling mismatch.
Prevention / Best Practice
Always use string-typed UIDs in the JSON payload, even when
enable_string_uidis set tofalse.Keep UIDs consistent and within the 32-bit integer range across both REST and client SDK joins.
Avoid toggling
enable_string_uidfrequently between requests; keep it consistent per project integration.