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.

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