Python SDK API reference

Full API reference for the Agora Conversational AI Python SDK.

Agora (sync) and AsyncAgora (async) extend the Fern-generated base client with regional domain pool support and three authentication modes. Use Agora for synchronous applications and AsyncAgora for asyncio-based applications.

_6

from agora_agent import Agora, Area

_6

client = Agora(

_6

area=Area.US,

_6

app_id='your-app-id',

_6

app_certificate='your-app-certificate',

_6

)

See Sync vs. Async to choose the right client for your application.

_12

Agora(

_12

area: Area,

_12

app_id: str = None,

_12

app_certificate: str = None,

_12

username: str = None,

_12

password: str = None,

_12

auth_token: str = None,

_12

headers: Dict[str, str] = None,

_12

timeout: float = 60,

_12

follow_redirects: bool = True,

_12

httpx_client: httpx.Client = None,

_12

)

Provide either app_id + app_certificate for app-credentials mode, or username + password for Basic Auth.

Parameter	Type	Required	Default	Description
area	Area	Yes	—	Region for API routing
app_id	str	Yes*	—	Agora App ID
app_certificate	str	Yes*	—	Agora App Certificate (app-credentials mode). Keep this secret and never expose it client-side
username	str	Yes*	—	Customer ID (Basic Auth mode)
password	str	Yes*	—	Customer Secret (Basic Auth mode)
auth_token	str	No	—	Pre-built agora token=<value> string
headers	Dict[str, str]	No	None	Additional headers sent with every request
timeout	float	No	60	Request timeout in seconds
follow_redirects	bool	No	True	Whether to follow HTTP redirects
httpx_client	httpx.Client	No	None	Custom httpx client instance

* Provide either app_id + app_certificate, or username + password.

Authentication mode is resolved from the parameters you provide:

Parameters provided	Resolved mode
app_id + app_certificate	"app-credentials"
auth_token	"token"
username + password	"basic"

AsyncAgora has the same constructor signature, except httpx_client accepts httpx.AsyncClient instead of httpx.Client.

_6

from agora_agent import AsyncAgora, Area

_6

client = AsyncAgora(

_6

area=Area.US,

_6

app_id='your-app-id',

_6

app_certificate='your-app-certificate',

_6

)

See Authentication for details on each mode.

Access the underlying Pool object for advanced domain management.

_2

pool = client.pool

_2

pool.get_area() # Area.US

• Returns: Pool

The following methods are available in addition to the Fern-generated sub-client methods.

Cycles to the next region prefix in the domain pool. Call this after a request failure to try a different regional endpoint. Synchronous on both Agora and AsyncAgora.

_1

client.next_region()

Triggers DNS-based domain selection to find the fastest-responding domain suffix. Results are cached for 30 seconds.

_5

# Sync (Agora)

_5

client.select_best_domain()

_5

_5

# Async (AsyncAgora) — requires await

_5

await client.select_best_domain()

Returns the full API URL currently in use as a str. Synchronous on both Agora and AsyncAgora.

_2

url = client.get_current_url()

_2

# Example: 'https://api-us-west-1.agora.io/api/conversational-ai-agent'

Both Agora and AsyncAgora expose Fern-generated sub-clients for direct REST API access. You typically do not need these when using the agentkit layer.

Property	Sync type	Async type	Description
client.agents	AgentsClient	AsyncAgentsClient	Start, stop, list, update agents
client.telephony	TelephonyClient	AsyncTelephonyClient	Telephony operations
client.phone_numbers	PhoneNumbersClient	AsyncPhoneNumbersClient	Phone number management

Sub-clients are lazily initialized on first access. For most use cases, prefer the AgentSession API over calling client.agents directly.

For full method signatures and request parameters, see the REST API reference.

Agent is an immutable configuration object. Each builder method returns a new Agent instance — the original is never modified. Define one Agent at startup and call create_session() on it for each user conversation.

_1

from agora_agent import Agent

_16

Agent(

_16

name: Optional[str] = None,

_16

instructions: Optional[str] = None,

_16

turn_detection: Optional[TurnDetectionConfig] = None,

_16

interruption: Optional[InterruptionConfig] = None,

_16

sal: Optional[SalConfig] = None,

_16

advanced_features: Optional[Dict[str, Any]] = None,

_16

parameters: Optional[SessionParams] = None,

_16

greeting: Optional[str] = None,

_16

failure_message: Optional[str] = None,

_16

max_history: Optional[int] = None,

_16

geofence: Optional[GeofenceConfig] = None,

_16

labels: Optional[Dict[str, str]] = None,

_16

rtc: Optional[RtcConfig] = None,

_16

filler_words: Optional[FillerWordsConfig] = None,

_16

)

All parameters are optional. Use the builder methods to set vendor configuration after construction.

Parameter	Type	Default	Description
name	Optional[str]	None	Agent name, used as the default session name
instructions	Optional[str]	None	LLM system prompt
turn_detection	Optional[TurnDetectionConfig]	None	Voice activity detection settings
interruption	Optional[InterruptionConfig]	None	Unified interruption control configuration
sal	Optional[SalConfig]	None	Selective Attention Locking configuration
advanced_features	Optional[Dict[str, Any]]	None	Advanced features, for example {'enable_rtm': True}
parameters	Optional[SessionParams]	None	Additional session parameters
greeting	Optional[str]	None	Auto-spoken greeting when agent joins
failure_message	Optional[str]	None	Message spoken when an LLM call fails
max_history	Optional[int]	None	Maximum conversation turns kept in LLM context
geofence	Optional[GeofenceConfig]	None	Regional access restriction
labels	Optional[Dict[str, str]]	None	Custom key-value labels returned in notification callbacks
rtc	Optional[RtcConfig]	None	RTC media encryption
filler_words	Optional[FillerWordsConfig]	None	Filler words played while waiting for the LLM response

All builder methods return a new Agent instance. The original is never modified.

Sets the LLM vendor for the cascading flow. Pass an instance of OpenAI, AzureOpenAI, Anthropic, or Gemini.

_1

with_llm(vendor: BaseLLM) -> Agent

Sets the TTS vendor. Records the vendor's sample_rate for avatar validation.

_1

with_tts(vendor: BaseTTS) -> Agent

Sets the STT vendor. Pass an instance of any STT vendor class.

_1

with_stt(vendor: BaseSTT) -> Agent

Sets the MLLM vendor for multimodal flow. Calling with_mllm() automatically sets mllm.enable = True. MLLM sessions do not require TTS, STT, or LLM vendors.

_1

with_mllm(vendor: BaseMLLM) -> Agent

Sets the avatar vendor. Raises ValueError if the TTS sample rate does not match the avatar's required rate.

_1

with_avatar(vendor: BaseAvatar) -> Agent

Raises: ValueError — if TTS sample rate does not match the avatar's required_sample_rate.

Configures cascading-flow SOS/EOS voice activity detection. Use config.start_of_speech and config.end_of_speech for SOS/EOS detection. Use with_interruption() for interruption behavior and MLLM vendor turn_detection for MLLM turn detection.

_1

with_turn_detection(config: TurnDetectionConfig) -> Agent

Configures unified interruption behavior using the top-level interruption object. Use this for start_of_speech and keywords interruption modes.

_1

with_interruption(config: InterruptionConfig) -> Agent

Overrides the LLM system prompt on a new Agent instance.

_1

with_instructions(instructions: str) -> Agent

Overrides the greeting message on a new Agent instance.

_1

with_greeting(greeting: str) -> Agent

Overrides the agent name on a new Agent instance.

_1

with_name(name: str) -> Agent

The following methods follow the same pattern — each returns a new Agent instance with the updated configuration.

Method	Parameter type	Description
with_sal(config)	SalConfig	Set Selective Attention Locking configuration
with_advanced_features(features)	Dict[str, Any]	Set advanced features
with_tools(enabled)	bool	Enable or disable MCP tool invocation
with_parameters(parameters)	SessionParams	Set session parameters
with_failure_message(message)	str	Set the message spoken when the LLM fails
with_max_history(n)	int	Set the maximum conversation history length
with_geofence(geofence)	GeofenceConfig	Set geofence configuration
with_labels(labels)	Dict[str, str]	Set custom labels
with_rtc(rtc)	RtcConfig	Set RTC configuration
with_filler_words(filler_words)	FillerWordsConfig	Set filler words configuration

Creates an AgentSession bound to a specific client and channel. Does not start the agent — call session.start() to join the channel.

_11

create_session(

_11

client: Agora | AsyncAgora,

_11

channel: str,

_11

agent_uid: str,

_11

remote_uids: List[str],

_11

name: Optional[str] = None,

_11

token: Optional[str] = None,

_11

idle_timeout: Optional[int] = None,

_11

enable_string_uid: Optional[bool] = None,

_11

expires_in: Optional[int] = None,

_11

) -> AgentSession

create_session() fields:

Parameter	Type	Required	Description
client	Agora or AsyncAgora	Yes	Authenticated client
channel	str	Yes	Channel name to join
agent_uid	str	Yes	The agent's RTC UID
remote_uids	List[str]	Yes	Remote user UIDs the agent listens and responds to
name	Optional[str]	No	Session name. Defaults to agent name
token	Optional[str]	No	Pre-built RTC+RTM token. Omit to auto-generate from app credentials
expires_in	Optional[int]	No	Token lifetime in seconds. Only applies when the token is auto-generated. Valid range: 1–86400. Use expires_in_hours() for clarity
idle_timeout	Optional[int]	No	Seconds before the agent auto-exits when no audio is detected
enable_string_uid	Optional[bool]	No	Use string UIDs instead of numeric UIDs

Converts the agent configuration into a StartAgentsRequestProperties object for the Agora API. Called internally by AgentSession.start().

_11

to_properties(

_11

channel: str,

_11

agent_uid: str,

_11

remote_uids: List[str],

_11

idle_timeout: Optional[int] = None,

_11

enable_string_uid: Optional[bool] = None,

_11

token: Optional[str] = None,

_11

app_id: Optional[str] = None,

_11

app_certificate: Optional[str] = None,

_11

expires_in: Optional[int] = None,

_11

) -> StartAgentsRequestProperties

Raises: ValueError if neither token nor app_id+app_certificate is provided, or if required vendors (LLM, TTS) are missing in cascading mode.

Read-only properties available on any Agent instance.

Property	Type	Description
name	Optional[str]	Agent name
instructions	Optional[str]	LLM system prompt
greeting	Optional[str]	Greeting message
failure_message	Optional[str]	Message spoken when LLM fails
max_history	Optional[int]	Maximum conversation history length
llm	Optional[Dict[str, Any]]	LLM config dict (from to_config())
tts	Optional[Dict[str, Any]]	TTS config dict
stt	Optional[Dict[str, Any]]	STT config dict
mllm	Optional[Dict[str, Any]]	MLLM config dict
avatar	Optional[Dict[str, Any]]	Avatar config dict
turn_detection	Optional[TurnDetectionConfig]	Turn detection configuration
interruption	Optional[InterruptionConfig]	Unified interruption control configuration
sal	Optional[SalConfig]	SAL configuration
advanced_features	Optional[Dict[str, Any]]	Advanced features
parameters	Optional[SessionParams]	Session parameters
geofence	Optional[GeofenceConfig]	Geofence configuration
labels	Optional[Dict[str, str]]	Custom labels
rtc	Optional[RtcConfig]	RTC configuration
filler_words	Optional[FillerWordsConfig]	Filler words configuration
config	Dict[str, Any]	Full configuration snapshot

Public aliases over Fern-generated types: LlmConfig, SttConfig, AsrConfig (= SttConfig), MllmConfig, AvatarConfig, session/conversation types, and think types (ThinkOnListeningAction, etc.).

Think value constants: ThinkOnListeningActionInject, ThinkOnListeningActionInterrupt, ThinkOnListeningActionIgnore, ThinkOnThinkingActionInterrupt, ThinkOnThinkingActionIgnore, ThinkOnSpeakingActionInterrupt, ThinkOnSpeakingActionIgnore.

AgentSession (sync) and AsyncAgentSession (async) manage the full lifecycle of a running agent. Obtain a session by calling agent.create_session() — direct construction is available for advanced use cases.

_4

from agora_agent import AgentSession

_4

from agora_agent import AsyncAgentSession

_4

# or from top-level:

_4

from agora_agent import AgentSession, AsyncAgentSession

Sessions are normally created via Agent.create_session(). Direct construction is available for advanced use:

_13

AgentSession(

_13

client: Any,

_13

agent: Agent,

_13

app_id: str,

_13

name: str,

_13

channel: str,

_13

agent_uid: str,

_13

remote_uids: List[str],

_13

app_certificate: Optional[str] = None,

_13

token: Optional[str] = None,

_13

idle_timeout: Optional[int] = None,

_13

enable_string_uid: Optional[bool] = None,

_13

)

AsyncAgentSession has the same constructor signature.

Parameter	Type	Required	Description
client	Agora or AsyncAgora	Yes	Authenticated client
agent	Agent	Yes	Agent configuration
app_id	str	Yes	Agora App ID
name	str	Yes	Session name
channel	str	Yes	Channel name
agent_uid	str	Yes	UID for the agent
remote_uids	List[str]	Yes	UIDs of remote participants
app_certificate	Optional[str]	No	App Certificate (for auto token generation)
token	Optional[str]	No	Pre-built RTC token
idle_timeout	Optional[int]	No	Idle timeout in seconds
enable_string_uid	Optional[bool]	No	Enable string UIDs

The following methods are available on both AgentSession and AsyncAgentSession. Methods that make API calls require await on AsyncAgentSession.

Starts the agent session. Generates an RTC token if not provided, validates avatar/TTS config for cascading sessions, and calls the Agora API. MLLM sessions do not require TTS; an enabled avatar is rejected when MLLM is configured (a disabled avatar is allowed).

	Sync (AgentSession)	Async (AsyncAgentSession)
Signature	start() -> str	async start() -> str
Returns	Agent ID	Agent ID
Raises	RuntimeError if not in idle, stopped, or error state	Same
Raises	ValueError if avatar/TTS sample rate mismatch or an enabled avatar is used with MLLM	Same

_5

# Sync

_5

agent_id = session.start()

_5

_5

# Async

_5

agent_id = await session.start()

Stops the agent session and removes the agent from the channel. If the agent has already stopped (404 from API), transitions to stopped without raising.

	Sync	Async
Signature	stop() -> None	async stop() -> None
Raises	RuntimeError if not in running state	Same

_5

# Sync

_5

session.stop()

_5

_5

# Async

_5

await session.stop()

Instructs the agent to speak the given text.

	Sync	Async
Signature	say(text: str, priority: Optional[str] = None, interruptable: Optional[bool] = None) -> None	Same with async
Raises	RuntimeError if not in running state	Same

Parameter	Type	Required	Description
text	str	Yes	Text to speak
priority	str	No	INTERRUPT, APPEND, or IGNORE
interruptable	bool	No	Whether the message can be interrupted

_5

# Sync

_5

session.say('One moment while I look that up.', priority='INTERRUPT', interruptable=False)

_5

_5

# Async

_5

await session.say('One moment while I look that up.', priority='INTERRUPT', interruptable=False)

Interrupts the agent while speaking or thinking.

	Sync	Async
Signature	interrupt() -> None	async interrupt() -> None
Raises	RuntimeError if not in running state	Same

_5

# Sync

_5

session.interrupt()

_5

_5

# Async

_5

await session.interrupt()

Updates the agent configuration mid-session without restarting. Accepts a partial properties object in REST API format.

	Sync	Async
Signature	update(properties: Any) -> None	async update(properties: Any) -> None
Raises	RuntimeError if not in running state	Same

_7

from agora_agent.agents.types import UpdateAgentsRequestProperties

_7

_7

# Sync

_7

session.update(properties)

_7

_7

# Async

_7

await session.update(properties)

Injects a custom text instruction into the running agent.

In API v2.7, omitting on_listening_action uses the server default interrupt. Pass on_listening_action='inject' explicitly to preserve the pre-v2.7 behavior.

_1

session.think('Summarize the last answer', on_listening_action='inject')

Fetches the conversation history for this session. Requires a valid agent ID — start() must have been called successfully.

	Sync	Async
Signature	get_history() -> Any	async get_history() -> Any
Raises	RuntimeError if no agent ID	Same

_5

# Sync

_5

history = session.get_history()

_5

_5

# Async

_5

history = await session.get_history()

Retrieves paginated turn analytics for a completed or running session. In v2.7, the API defaults to page 1 and up to 50 turns per page. Responses include agent_id, name, channel, total_turn_count, pagination, and turns.

_1

page = session.get_turns(page_index=1, page_size=50)

Fetches all turn pages and returns a single GetTurnsAgentsResponse with the combined turns list.

_1

all_turns = session.get_all_turns(page_size=50)

Fetches current agent metadata from the API. Requires a valid agent ID.

	Sync	Async
Signature	get_info() -> Any	async get_info() -> Any
Raises	RuntimeError if no agent ID	Same

_5

# Sync

_5

info = session.get_info()

_5

_5

# Async

_5

info = await session.get_info()

Registers an event handler. Synchronous on both AgentSession and AsyncAgentSession. Register handlers before calling start() to avoid missing the started event.

_1

session.on('started', lambda data: print(f'Started: {data}'))

Parameter	Type	Description
event	str	Event type: started, stopped, or error
handler	Callable[..., None]	Callback function

Removes a previously registered event handler. Synchronous on both AgentSession and AsyncAgentSession.

_1

session.off('started', my_handler)

The following read-only properties are available on both AgentSession and AsyncAgentSession instances.

Property	Type	Description
id	Optional[str]	Agent ID, populated after start() resolves
status	str	Current session state: 'idle', 'starting', 'running', 'stopping', 'stopped', 'error'
agent	Agent	The agent configuration this session was created from
app_id	str	The Agora App ID for this session
raw	AgentsClient or AsyncAgentsClient	Direct access to the Fern-generated agents client for advanced operations

Current state	Allowed actions
idle	start()
starting	(waiting for API)
running	stop(), say(), interrupt(), update(), get_history(), get_info()
stopping	(waiting for API)
stopped	start() (restart)
error	start() (retry)

All vendor classes are imported from agora_agent.agentkit.vendors.

_1

from agora_agent import OpenAI, ElevenLabsTTS, DeepgramTTS, DeepgramSTT, OpenAIRealtime, XaiGrok, GenericAvatar

Use with with_llm().

info

greeting_configs accepts either a dict or LlmGreetingConfigs. In v2.7, greeting_configs.interruptable=False makes the greeting uninterruptible; True follows the global interruption settings.

_3

from agora_agent import OpenAI

_3

_3

llm = OpenAI(api_key='your-key', model='gpt-4o-mini', temperature=0.7)

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	OpenAI API key
model	str	No	'gpt-4o-mini'	Model name
base_url	str	No	None	Custom base URL
temperature	float	No	None	Sampling temperature (0.0–2.0)
top_p	float	No	None	Nucleus sampling (0.0–1.0)
max_tokens	int	No	None	Maximum tokens to generate
system_messages	List[Dict]	No	None	Additional system messages
greeting_message	str	No	None	Agent greeting message
failure_message	str	No	None	Message spoken when the LLM call fails
input_modalities	List[str]	No	None	Input modalities
output_modalities	List[str]	No	None	Output modalities
greeting_configs	Dict[str, Any]	No	None	Greeting configuration
template_variables	Dict[str, str]	No	None	Template variables for system prompt interpolation
headers	Dict[str, str]	No	None	Custom HTTP headers forwarded to the LLM provider
params	Dict[str, Any]	No	None	Additional model parameters

_7

from agora_agent import AzureOpenAI

_7

_7

llm = AzureOpenAI(

_7

api_key='your-azure-key',

_7

endpoint='https://your-resource.openai.azure.com',

_7

deployment_name='gpt-4o-mini',

_7

)

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Azure OpenAI API key
endpoint	str	Yes	—	Azure endpoint URL
deployment_name	str	Yes	—	Azure deployment name
api_version	str	No	'2024-08-01-preview'	Azure API version
temperature	float	No	None	Sampling temperature (0.0–2.0)
top_p	float	No	None	Nucleus sampling (0.0–1.0)
max_tokens	int	No	None	Maximum tokens to generate
system_messages	List[Dict]	No	None	Additional system messages
greeting_message	str	No	None	Agent greeting message
failure_message	str	No	None	Message spoken when the LLM call fails
input_modalities	List[str]	No	None	Input modalities
output_modalities	List[str]	No	None	Output modalities
params	Dict[str, Any]	No	None	Additional model parameters
headers	Dict[str, str]	No	None	Custom HTTP headers forwarded to the LLM provider
greeting_configs	Dict[str, Any]	No	None	Greeting configuration
template_variables	Dict[str, str]	No	None	Template variables for system prompt interpolation

_3

from agora_agent import Anthropic

_3

_3

llm = Anthropic(api_key='your-anthropic-key', model='claude-3-5-sonnet-20241022')

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Anthropic API key
model	str	No	'claude-3-5-sonnet-20241022'	Model name
max_tokens	int	No	None	Maximum tokens to generate
temperature	float	No	None	Sampling temperature (0.0–1.0)
top_p	float	No	None	Nucleus sampling (0.0–1.0)
system_messages	List[Dict]	No	None	Additional system messages
greeting_message	str	No	None	Agent greeting message
failure_message	str	No	None	Message spoken when the LLM call fails
input_modalities	List[str]	No	None	Input modalities
output_modalities	List[str]	No	None	Output modalities
params	Dict[str, Any]	No	None	Additional model parameters
headers	Dict[str, str]	No	None	Custom HTTP headers forwarded to the LLM provider
greeting_configs	Dict[str, Any]	No	None	Greeting configuration
template_variables	Dict[str, str]	No	None	Template variables for system prompt interpolation

_3

from agora_agent import Gemini

_3

_3

llm = Gemini(api_key='your-google-key', model='gemini-2.0-flash-exp')

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Google AI API key
model	str	No	'gemini-2.0-flash-exp'	Model name
temperature	float	No	None	Sampling temperature (0.0–2.0)
top_p	float	No	None	Nucleus sampling (0.0–1.0)
top_k	int	No	None	Top-k sampling
max_output_tokens	int	No	None	Maximum output tokens
system_messages	List[Dict]	No	None	Additional system messages
greeting_message	str	No	None	Agent greeting message
failure_message	str	No	None	Message spoken when the LLM call fails
input_modalities	List[str]	No	None	Input modalities
output_modalities	List[str]	No	None	Output modalities
params	Dict[str, Any]	No	None	Additional model parameters
headers	Dict[str, str]	No	None	Custom HTTP headers forwarded to the LLM provider
greeting_configs	Dict[str, Any]	No	None	Greeting configuration
template_variables	Dict[str, str]	No	None	Template variables for system prompt interpolation

The SDK also includes named helpers for the remaining Agora-supported LLM providers. These helpers choose the correct request format internally.

Class	Provider	Key parameters
Groq	Groq	apiKey, model, url?
VertexAILLM	Google Vertex AI	apiKey, model, projectId, location, url?
AmazonBedrock	Amazon Bedrock	apiKey, url, model
Dify	Dify	apiKey, url, user?, conversationId?
CustomLLM	OpenAI-compatible LLM	apiKey, model, url

Use with with_tts(). The sample_rate option determines avatar compatibility — see with_avatar().

_1

from agora_agent.agentkit.vendors import ElevenLabsTTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	ElevenLabs API key
model_id	str	Yes	—	Model ID, for example 'eleven_flash_v2_5'
voice_id	str	Yes	—	Voice ID
sample_rate	int	No	None	Sample rate in Hz: 16000, 22050, 24000, or 44100
base_url	str	No	None	Custom WebSocket base URL
skip_patterns	List[int]	No	None	Skip patterns for bracketed content
optimize_streaming_latency	int	No	None	Latency optimization level (0–4)
stability	float	No	None	Voice stability (0.0–1.0)
similarity_boost	float	No	None	Similarity boost (0.0–1.0)
style	float	No	None	Style exaggeration (0.0–1.0)
use_speaker_boost	bool	No	None	Enable speaker boost

_1

from agora_agent.agentkit.vendors import MicrosoftTTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	Azure subscription key
region	str	Yes	—	Azure region, for example 'eastus'
voice_name	str	Yes	—	Voice name, for example 'en-US-JennyNeural'
sample_rate	int	No	None	Sample rate in Hz: 8000, 16000, 24000, or 48000
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

Fixed sample rate: 24000 Hz.

_1

from agora_agent.agentkit.vendors import OpenAITTS

Parameter	Type	Required	Default	Description
api_key	str	No	None	OpenAI API key. Omit to use Agora-managed credentials for supported models
voice	str	Yes	—	Voice name: 'alloy', 'echo', 'fable', 'onyx', 'nova', or 'shimmer'
model	str	No	None	Model: 'tts-1' or 'tts-1-hd'
response_format	str	No	None	Audio format, for example 'pcm'
speed	float	No	None	Speech speed multiplier
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import CartesiaTTS

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Cartesia API key
voice_id	str	Yes	—	Voice ID
model_id	str	No	None	Model ID
sample_rate	int	No	None	Sample rate in Hz: 8000–48000
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import GoogleTTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	Google Cloud API key
voice_name	str	Yes	—	Voice name
language_code	str	No	None	Language code, for example 'en-US'
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import AmazonTTS

Parameter	Type	Required	Default	Description
access_key	str	Yes	—	AWS access key
secret_key	str	Yes	—	AWS secret key
region	str	Yes	—	AWS region, for example 'us-east-1'
voice_id	str	Yes	—	Amazon Polly voice ID
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import HumeAITTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	Hume AI API key
config_id	str	No	None	Configuration ID
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import RimeTTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	Rime API key
speaker	str	Yes	—	Speaker ID
model_id	str	No	None	Model ID
lang	str	No	None	Language code
sampling_rate	int	No	None	Sampling rate in Hz (serialized as samplingRate)
speed_alpha	float	No	None	Speed multiplier (serialized as speedAlpha)
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import FishAudioTTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	Fish Audio API key
reference_id	str	Yes	—	Reference ID
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import MiniMaxTTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	MiniMax API key
group_id	str	Yes	—	MiniMax group ID
model	str	Yes	—	Model name, for example 'speech-02-turbo'
voice_id	str	Yes	—	Voice style identifier
url	str	Yes	—	WebSocket endpoint
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import DeepgramTTS

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Deepgram API key
model	str	Yes	—	Model name, for example 'aura-2-thalia-en'
base_url	str	No	None	WebSocket endpoint. Defaults server-side to wss://api.deepgram.com/v1/speak
sample_rate	int	No	None	Sample rate in Hz
params	Dict[str, Any]	No	None	Additional Deepgram TTS parameters
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import MurfTTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	Murf API key
voice_id	str	Yes	—	Voice ID, for example 'Ariana' or 'Natalie'
style	str	No	None	Voice style, for example 'Conversational'
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

_1

from agora_agent.agentkit.vendors import SarvamTTS

Parameter	Type	Required	Default	Description
key	str	Yes	—	Sarvam API key
speaker	str	Yes	—	Speaker name
target_language_code	str	Yes	—	Target language code
skip_patterns	List[int]	No	None	Skip patterns for bracketed content

Use with with_stt().

All parameters are optional.

_1

from agora_agent.agentkit.vendors import DeepgramSTT

Parameter	Type	Required	Default	Description
api_key	str	No	None	Deepgram API key. Omit to use Agora-managed credentials for supported models
model	str	No	None	Model name, for example 'nova-2'
language	str	No	None	Language code, for example 'en-US'
smart_format	bool	No	None	Enable smart formatting
punctuation	bool	No	None	Enable punctuation
additional_params	Dict[str, Any]	No	None	Additional vendor parameters

_1

from agora_agent.agentkit.vendors import SpeechmaticsSTT

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Speechmatics API key
language	str	Yes	—	Language code, for example 'en'
additional_params	Dict[str, Any]	No	None	Additional parameters

_1

from agora_agent.agentkit.vendors import MicrosoftSTT

Parameter	Type	Required	Default	Description
key	str	Yes	—	Azure subscription key
region	str	Yes	—	Azure region, for example 'eastus'
language	str	No	None	Language code, for example 'en-US'
additional_params	Dict[str, Any]	No	None	Additional parameters

_1

from agora_agent.agentkit.vendors import OpenAISTT

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	OpenAI API key
model	str	No	None	Model name. Default: 'whisper-1'
language	str	No	None	Language code
additional_params	Dict[str, Any]	No	None	Additional parameters

_1

from agora_agent.agentkit.vendors import GoogleSTT

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Google Cloud API key
language	str	No	None	Language code, for example 'en-US'
additional_params	Dict[str, Any]	No	None	Additional parameters

_1

from agora_agent.agentkit.vendors import AmazonSTT

Parameter	Type	Required	Default	Description
access_key	str	Yes	—	AWS access key ID
secret_key	str	Yes	—	AWS secret access key
region	str	Yes	—	AWS region, for example 'us-east-1'
language	str	No	None	Language code
additional_params	Dict[str, Any]	No	None	Additional parameters

_1

from agora_agent.agentkit.vendors import AssemblyAISTT

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	AssemblyAI API key
language	str	No	None	Language code
additional_params	Dict[str, Any]	No	None	Additional parameters

_1

from agora_agent.agentkit.vendors import AresSTT

Parameter	Type	Required	Default	Description
language	str	No	None	Language code
additional_params	Dict[str, Any]	No	None	Additional parameters

_1

from agora_agent.agentkit.vendors import SarvamSTT

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Sarvam API key
language	str	Yes	—	Language code, for example 'en' or 'hi'
additional_params	Dict[str, Any]	No	None	Additional parameters

Use with with_mllm() for multimodal end-to-end audio processing without separate STT or TTS steps. Requires advanced_features={'enable_mllm': True} in the Agent constructor.

_1

from agora_agent.agentkit.vendors import OpenAIRealtime

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	OpenAI API key
model	str	No	None	Model name, for example 'gpt-4o-realtime-preview'
url	str	No	None	Custom WebSocket URL
greeting_message	str	No	None	Agent greeting message
failure_message	str	No	None	Message played when the model call fails
input_modalities	List[str]	No	None	Input modalities, for example ['audio']
output_modalities	List[str]	No	None	Output modalities, for example ['text', 'audio']
messages	List[Dict]	No	None	Conversation messages for short-term memory
params	Dict[str, Any]	No	None	Additional parameters
turn_detection	MllmTurnDetectionConfig	No	None	MLLM turn detection configuration; overrides top-level turn_detection

_1

from agora_agent.agentkit.vendors import GeminiLive

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Google Gemini API key
model	str	Yes	—	Gemini Live model name
url	str	No	None	Custom WebSocket URL
instructions	str	No	None	System instructions
voice	str	No	None	Voice name
greeting_message	str	No	None	Agent greeting message
failure_message	str	No	None	Message played when the model call fails
input_modalities	List[str]	No	None	Input modalities
output_modalities	List[str]	No	None	Output modalities
messages	List[Dict]	No	None	Conversation messages for short-term memory
additional_params	Dict[str, Any]	No	None	Additional parameters
turn_detection	MllmTurnDetectionConfig	No	None	MLLM turn detection configuration; overrides top-level turn_detection

_1

from agora_agent.agentkit.vendors import VertexAI

Parameter	Type	Required	Default	Description
model	str	Yes	—	Model name, for example 'gemini-2.0-flash-exp'
project_id	str	Yes	—	Google Cloud project ID
location	str	Yes	—	Google Cloud location, for example 'us-central1'
adc_credentials_string	str	Yes	—	Application Default Credentials JSON string
instructions	str	No	None	System instructions for the model
voice	str	No	None	Voice name, for example 'Aoede' or 'Charon'
greeting_message	str	No	None	Agent greeting message
failure_message	str	No	None	Message played when the model call fails
input_modalities	List[str]	No	None	Input modalities
output_modalities	List[str]	No	None	Output modalities
messages	List[Dict]	No	None	Conversation messages for short-term memory
additional_params	Dict[str, Any]	No	None	Additional parameters
turn_detection	MllmTurnDetectionConfig	No	None	MLLM turn detection configuration; overrides top-level turn_detection

xAI Grok MLLM vendor (mllm.vendor: "xai").

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	xAI API key
url	str	No	wss://api.x.ai/v1/realtime	xAI realtime WebSocket URL
voice	str	No	None	Voice identifier, for example eve or rex
language	str	No	None	Language code, for example en
sample_rate	int	No	None	Audio sample rate in Hz
greeting_message	str	No	None	Greeting message
failure_message	str	No	None	Message played when the model call fails
input_modalities	List[str]	No	None	Input modalities
output_modalities	List[str]	No	None	Output modalities
messages	List[Dict]	No	None	Conversation messages
params	Dict[str, Any]	No	None	Additional xAI parameters
turn_detection	MllmTurnDetectionConfig	No	None	Supports agora_vad and server_vad for xAI

Use with with_avatar(). Each avatar vendor requires a specific TTS sample rate enforced at runtime.

Requires TTS at 24,000 Hz.

_1

from agora_agent.agentkit.vendors import HeyGenAvatar

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	HeyGen API key
quality	str	Yes	—	Video quality: 'low', 'medium', or 'high'
agora_uid	str	Yes	—	Agora UID for the avatar video stream
agora_token	str	No	None	Avatar token. When omitted, AgentSession.start() generates one for agora_uid using the same token path as the agent.
avatar_id	str	No	None	HeyGen avatar ID
enable	bool	No	True	Enable or disable the avatar
disable_idle_timeout	bool	No	None	Disable the idle timeout
activity_idle_timeout	int	No	None	Idle timeout in seconds. Default: 120

Requires TTS at 16,000 Hz.

_1

from agora_agent.agentkit.vendors import AkoolAvatar

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Akool API key
avatar_id	str	No	None	Avatar ID

Required TTS sample rate: 24000 Hz

Same options as HeyGenAvatar, but serializes vendor: "liveavatar". agora_token is optional and generated by AgentSession.start() when omitted.

_1

from agora_agent.agentkit.vendors import AnamAvatar

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Anam API key
persona_id	str	No	None	Persona ID
enable	bool	No	True	Enable or disable the avatar

_1

from agora_agent.agentkit.vendors import GenericAvatar

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Generic avatar provider API key
agora_uid	str	Yes	—	Avatar RTC UID. Must differ from the agent UID.
api_base_url	str	Yes	—	Avatar provider API base URL
avatar_id	str	Yes	—	Avatar ID
agora_token	str	No	None	Optional avatar token. Generated by AgentSession.start() when omitted.
agora_appid	str	No	None	Optional; filled from the session App ID when omitted.
agora_channel	str	No	None	Optional; filled from the session channel when omitted.
enable	bool	No	True	Enable or disable the avatar

Avatar tokens are separate from the agent join token but generated with the same generate_convo_ai_token path, using the avatar's agora_uid as uid.

Helper functions for generating and managing tokens. Use these when you need control over token lifetime or when generating tokens outside of a session.

_2

from agora_agent.agentkit.token import generate_convo_ai_token, generate_rtc_token

_2

from agora_agent.agentkit import expires_in_hours, expires_in_minutes

Generates a Conversational AI token combining RTC and RTM privileges. This is the same token the SDK generates automatically in app-credentials mode. Use this when passing a pre-built token to create_session().

_8

generate_convo_ai_token(

_8

app_id: str,

_8

app_certificate: str,

_8

channel_name: str,

_8

account: str,

_8

token_expire: int = 86400,

_8

privilege_expire: int = 0,

_8

) -> str

Parameter	Type	Required	Default	Description
app_id	str	Yes	—	Agora App ID
app_certificate	str	Yes	—	Agora App Certificate
channel_name	str	Yes	—	The channel the token grants access to
account	str	Yes	—	The UID this token is issued for, as a string
token_expire	int	No	86400	Token lifetime in seconds. Valid range: 1–86400
privilege_expire	int	No	0	Seconds until privileges expire. 0 means same as token_expire

Returns: str — the generated token.

_10

from agora_agent.agentkit.token import generate_convo_ai_token

_10

from agora_agent.agentkit import expires_in_hours

_10

_10

token = generate_convo_ai_token(

_10

app_id='your-app-id',

_10

app_certificate='your-app-certificate',

_10

channel_name='support-room-123',

_10

account='1',

_10

token_expire=expires_in_hours(12),

_10

)

Generates an RTC-only token for channel join. Use generate_convo_ai_token() instead for most Conversational AI use cases.

_8

generate_rtc_token(

_8

app_id: str,

_8

app_certificate: str,

_8

channel: str,

_8

uid: int,

_8

role: int = 1,

_8

expiry_seconds: int = 86400,

_8

) -> str

Parameter	Type	Required	Default	Description
app_id	str	Yes	—	Agora App ID
app_certificate	str	Yes	—	Agora App Certificate
channel	str	Yes	—	Channel name
uid	int	Yes	—	User ID. Use 0 for any user
role	int	No	1	RTC role: 1 for publisher, 2 for subscriber
expiry_seconds	int	No	86400	Token lifetime in seconds. Valid range: 1–86400

Returns: str — the generated token.

Helper functions for specifying token lifetimes. Use with create_session() or token generation functions. Values are validated and capped at the Agora maximum of 86400 seconds (24 hours).

_2

expires_in_hours(hours: int) -> int

_2

expires_in_minutes(minutes: int) -> int

Function	Returns	Behavior
expires_in_hours(n)	int — seconds	Raises ValueError if n ≤ 0. Warns and caps at 86400 if result exceeds 24 h
expires_in_minutes(n)	int — seconds	Raises ValueError if n ≤ 0. Warns and caps at 86400 if result exceeds 24 h

_9

from agora_agent.agentkit import expires_in_hours, expires_in_minutes

_9

_9

session = agent.create_session(

_9

client,

_9

channel='support-room-123',

_9

agent_uid='1',

_9

remote_uids=['100'],

_9

expires_in=expires_in_hours(12),

_9

)

Shared types and enums used across Agora, AsyncAgora, Agent, AgentSession, and vendor classes.

Region used for API routing. Pass to Agora or AsyncAgora via the area parameter.

_1

from agora_agent import Area

Value	Region
Area.US	United States
Area.EU	Europe
Area.AP	Asia-Pacific
Area.CN	China mainland

Valid event names for session.on() and session.off().

_1

'started' | 'stopped' | 'error'

Value	Payload	Description
'started'	dict with agent_id: str	Agent successfully joined the channel
'stopped'	dict with agent_id: str	Agent left the channel
'error'	Exception	An unrecoverable error occurred

Controls how the agent handles a say() call relative to its current activity. Pass as a string to session.say().

Value	Description
'INTERRUPT'	Agent immediately stops current speech and delivers the message
'APPEND'	Message is queued and delivered after current speech ends
'IGNORE'	Message is discarded if the agent is currently speaking

Raised when the API returns a 4xx or 5xx response. Catch this to inspect the status code and response body.

_7

from agora_agent.core.api_error import ApiError

_7

_7

try:

_7

agent_id = session.start()

_7

except ApiError as e:

_7

print(e.status_code)

_7

print(e.body)

Property	Type	Description
status_code	int	HTTP status code returned by the API
body	Any	Raw response body from the API

The Python SDK provides two parallel client and session hierarchies — synchronous and asynchronous. Choose based on your application's runtime model.

	Sync	Async
Client	Agora	AsyncAgora
Session	AgentSession	AsyncAgentSession
HTTP backend	httpx.Client	httpx.AsyncClient

Use Agora (sync) when:

• You are writing scripts, CLI tools, or batch jobs
• Your web framework is synchronous, for example Flask or Django without async views
• You want the simplest possible code

Use AsyncAgora (async) when:

• Your application uses asyncio, for example FastAPI, Starlette, or aiohttp
• You need to manage multiple concurrent agent sessions efficiently
• You want non-blocking I/O

The Agent builder class is the same for both — it does not make HTTP calls, so it has no async variant. Pass an AsyncAgora client to agent.create_session() to receive an AsyncAgentSession.