> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-pr-5482.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```python theme={null}
from pipecatcloud.session import Session, SessionParams

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

### Constructor Parameters

<ParamField path="agent_name" type="string" required>
  Name of the deployed agent to interact with. A `ValueError` is raised if it is
  empty.
</ParamField>

<ParamField path="api_key" type="string" required>
  Public API key for authentication.
</ParamField>

<ParamField path="params" type="SessionParams">
  Optional parameters to configure the session.
</ParamField>

### Methods

<ResponseField name="start()" type="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.
</ResponseField>

## SessionParams

The `SessionParams` class allows you to configure a session.

```python theme={null}
from pipecatcloud.session import SessionParams

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

### Parameters

<ParamField path="data" type="Dict[str, Any]" default="None">
  Optional dictionary of data to pass to the agent. Must be JSON-serializable.
</ParamField>

<ParamField path="use_daily" type="boolean" default="False">
  If True, creates a Daily WebRTC room for the session, enabling voice
  interaction.
</ParamField>

<ParamField path="daily_room_properties" type="Dict[str, Any]" default="None">
  Optional dictionary of properties to configure the Daily room. Only used when
  `use_daily=True`.

  See [Daily API
  documentation](https://docs.daily.co/reference/rest-api/rooms/config) for
  available properties.
</ParamField>

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

```python theme={null}
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

<ParamField path="timeout_seconds" type="int" default="120">
  How long `wait_for_webrtc()` waits before giving up.
</ParamField>

### Methods

<ResponseField name="wait_for_webrtc()" type="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.
</ResponseField>

<ResponseField name="complete_session()" type="bool">
  Releases a pending wait, cancelling its timeout. Returns `True` if there was a
  wait to complete, `False` otherwise.
</ResponseField>

<ResponseField name="cancel_timeout()" type="bool">
  Cancels the timeout without completing the wait. Returns `True` if there was a
  timeout to cancel, `False` otherwise.
</ResponseField>