session.md

sidebar_position	3
title	AgentSession
description	Full API reference for the Python AgentSession class.

AgentSession / AsyncAgentSession Reference

Import:

from shengwang_agent.agentkit import AgentSession
from shengwang_agent.agentkit.agent_session import AsyncAgentSession
# or from top-level:
from shengwang_agent import AgentSession, AsyncAgentSession

Constructor

Sessions are normally created via Agent.create_session(). Direct 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,
)

AsyncAgentSession has the same constructor signature.

Parameter	Type	Required	Description
client	AgentClient or AsyncAgentClient	Yes	Authenticated client
agent	Agent	Yes	Agent configuration
app_id	str	Yes	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

Methods

start()

Start the agent session. Generates an RTC token if not provided, validates avatar/TTS config, and calls the API.

	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	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 shengwang_agent.agents.types import UpdateAgentsRequestProperties

# Sync
session.update(properties)

# Async
await session.update(properties)

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()

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)

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	The 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)