Session Management

Start and manage Pipecat Cloud agent sessions programmatically with the pipecatcloud Python SDK’s session APIs.

The session management classes allow you to start and interact with agent sessions.

Session

The Session class is the primary way to start and interact with agent sessions.

from pipecatcloud.session import Session, SessionParams

session = Session(
    agent_name="my-agent",
    api_key="pk_...",
    params=SessionParams(use_daily=True)
)

Constructor Parameters

agent_name · string · required

Name of the deployed agent to interact with. A ValueError is raised if it is empty.

api_key · string · required

Public API key for authentication.

params · SessionParams

Optional parameters to configure the session.

Methods

start() · async

Starts a new session with the specified agent.

Returns

A dictionary containing session information. If use_daily is True, includes dailyRoom URL and dailyToken.

Raises

AgentStartError: If the session fails to start due to missing API key, agent not found, agent not ready, or capacity limits.

SessionParams

The SessionParams class allows you to configure a session.

from pipecatcloud.session import SessionParams

params = SessionParams(
    data={"custom_field": "value"},
    use_daily=True,
    daily_room_properties={"enable_recording": "cloud"}
)

Parameters

data · Dict[str, Any] · default: "None"

Optional dictionary of data to pass to the agent. Must be JSON-serializable.

use_daily · boolean · default: "False"

If True, creates a Daily WebRTC room for the session, enabling voice interaction.

daily_room_properties · Dict[str, Any] · default: "None"

Optional dictionary of properties to configure the Daily room. Only used when use_daily=True.

See Daily API documentation for available properties.

SmallWebRTCSessionManager

Coordinates the wait between a Pipecat Cloud session starting and a SmallWebRTCTransport connection arriving. A room-less SmallWebRTC bot is activated over HTTP before the WebRTC connection exists, so the entry point has to wait for it rather than proceed immediately.

from pipecatcloud import SmallWebRTCSessionManager

manager = SmallWebRTCSessionManager(timeout_seconds=120)

# In the bot entry point: block until the connection arrives
await manager.wait_for_webrtc()

# From wherever the connection is handled: release the wait
manager.complete_session()

Constructor Parameters

timeout_seconds · int · default: "120"

How long wait_for_webrtc() waits before giving up.

Methods

wait_for_webrtc() · async

Waits for the WebRTC connection.

Raises

TimeoutError if no connection arrives within timeout_seconds. RuntimeError if a wait is already in progress — one manager handles one wait at a time.

complete_session() · bool

Releases a pending wait, cancelling its timeout. Returns True if there was a wait to complete, False otherwise.

cancel_timeout() · bool

Cancels the timeout without completing the wait. Returns True if there was a timeout to cancel, False otherwise.