Skip to content

session.md

Latest commit

 

History

History
303 lines (228 loc) · 9.27 KB

session.md

File metadata and controls

303 lines (228 loc) · 9.27 KB
Raw
sidebar_position 3
title AgentSession
description Full API reference for the Python AgentSession class.

AgentSession / AsyncAgentSession Reference

Import:

from agora_agent import AgentSession
from agora_agent import AsyncAgentSession
# or from top-level:
from agora_agent import AgentSession, AsyncAgentSession

Constructor

Sessions are normally created via Agent(client=client, ...).create_session(). The agent builder must have a bound client. Direct AgentSession construction is available for advanced use:

AgentSession(
    client: Any,
    agent: Agent,
    app_id: str,
    name: str,
    channel: str,
    agent_uid: str,
    remote_uids: List[str],
    app_certificate: Optional[str] = None,
    token: Optional[str] = None,
    idle_timeout: Optional[int] = None,
    enable_string_uid: Optional[bool] = None,
    preset: Optional[Union[str, Sequence[str]]] = None,
    pipeline_id: Optional[str] = None,
    expires_in: Optional[int] = None,
    debug: Optional[bool] = None,
    warn: Optional[Callable[[str], None]] = None,
)

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 Agent instance name sent to the Start Agent API
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
preset Optional[Union[str, Sequence[str]]] No Advanced preset value for project-specific routing
pipeline_id Optional[str] No Published AI Studio pipeline ID for this session. Overrides agent.pipeline_id.
expires_in Optional[int] No Auto-generated token lifetime in seconds
debug Optional[bool] No Enable debug logging of the start request
warn Optional[Callable[[str], None]] No Custom warning sink

pipeline_id is sent as the top-level /join field pipeline_id, not inside properties. If unset, AgentSession.start() uses the agent-level value from Agent(..., pipeline_id=...).

For normal SDK usage, prefer binding the client on the agent first. Pass the agent instance name via create_session(name=...):

import time
agent = Agent(client=client)
session = agent.create_session(
    channel=f"demo-channel-{int(time.time())}",
    agent_uid="1",
    remote_uids=["100"],
    name=f"conversation-{int(time.time())}",
)

Methods

start()

Start 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 
# Sync
agent_id = session.start()

# Async
agent_id = await session.start()

stop()

Stop the agent session. 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 
# Sync
session.stop()

# Async
await session.stop()

say(text, priority=None, interruptable=None)

Send text to be spoken by the agent's TTS.

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 
# Sync
session.say('Hello!', priority='INTERRUPT', interruptable=False)

# Async
await session.say('Hello!', priority='INTERRUPT', interruptable=False)

interrupt()

Interrupt the agent while speaking or thinking.

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

# Async
await session.interrupt()

update(properties)

Update the agent configuration at runtime.

Sync Async
Signature update(properties: Any) -> None async update(properties: Any) -> None
Raises RuntimeError if not in running state Same 
from agora_agent.agents.types import UpdateAgentsRequestProperties

# Sync
session.update(properties)

# Async
await session.update(properties)

think(text, ...)

Inject 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.

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

get_history()

Retrieve the conversation history.

Sync Async
Signature get_history() -> Any async get_history() -> Any
Raises RuntimeError if no agent ID Same 
# Sync
history = session.get_history()

# Async
history = await session.get_history()

get_info()

Retrieve the current session info.

Sync Async
Signature get_info() -> Any async get_info() -> Any
Raises RuntimeError if no agent ID Same 
# Sync
info = session.get_info()

# Async
info = await session.get_info()

get_turns(page_index=None, page_size=None)

Retrieve 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.

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

get_all_turns(page_size=None)

Fetch all turn pages and return a single GetTurnsAgentsResponse with the combined turns list.

all_turns = session.get_all_turns(page_size=50)

on(event, handler)

Register an event handler. This method is synchronous on both AgentSession and AsyncAgentSession.

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

off(event, handler)

Remove a previously registered event handler.

session.off('started', my_handler)

Presets and BYOK

Prefer configuring vendors on the Agent builder. When you omit credentials for supported Agora-managed global models, AgentKit sends the matching Agora-managed configuration at session start. CN MiniMax TTS is not Agora-managed in the same way and typically includes key.

preset is an advanced session option for project-specific settings, not for selecting Agora-managed models. Most applications should use the builder instead.

  • Omit vendor credentials on the builder for supported Agora-managed global models.
  • Provide vendor API keys when you want BYOK.
  • Pass preset on agent.create_session(...) only when you need to access specific project-specific settings.

Supported Agora-managed models:

  • Deepgram STT: nova-2, nova-3
  • OpenAI LLM: gpt-4o-mini, gpt-4.1-mini, gpt-5-nano, gpt-5-mini
  • OpenAI TTS: tts-1
  • MiniMax TTS: speech-2.6-turbo, speech-2.8-turbo, speech_2_6_turbo, speech_2_8_turbo

Properties

Property Type Description
id Optional[str] Agent ID (set after start())
status str Current state: idle, starting, running, stopping, stopped, error
agent Agent The agent configuration
app_id str Agora App ID
raw AgentsClient / AsyncAgentsClient Direct access to Fern-generated agents client

State Transitions

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)