Pipecat Cloud SDK Overview

The Pipecat Cloud Python SDK (pipecatcloud): start and manage agent sessions, type bot() entry points, and handle SDK errors.

The Pipecat Cloud Python SDK provides a programmatic interface for managing and interacting with your agents. It allows you to start and manage agent sessions, handle different session types, and respond to various error conditions.

Installation

Install the SDK using uv:

uv add pipecatcloud

The session-argument types in pipecatcloud.agent subclass pipecat-ai’s runner types, and pipecat-ai is an optional dependency. If you use them outside an agent image, install the extra:

uv add "pipecatcloud[pipecat]"

Key Components

The SDK contains several main components:

• Session Management - Start and interact with agent sessions
• Session Arguments - Types of arguments received by bot() entry points
• Error Handling - Exception classes for handling different error scenarios
• SmallWebRTCSessionManager - Waits for a SmallWebRTC connection to arrive

Quick Start

Here’s a simple example to get started:

import asyncio

from pipecatcloud.exception import AgentStartError
from pipecatcloud.session import Session, SessionParams


async def main():
    try:
        # Create session object
        session = Session(
            agent_name="my-first-agent",
            api_key=API_KEY,  # Replace with your actual API key
            params=SessionParams(
                use_daily=True,  # Optional: Creates a Daily room
                daily_room_properties={"start_video_off": False},
                data={"key": "value"},
            ),
        )

        # Start the session
        response = await session.start()

        # Get Daily room URL
        daily_url = f"{response['dailyRoom']}?t={response['dailyToken']}"
        print(f"Join Daily room: {daily_url}")

    except AgentStartError as e:
        print(f"Error starting agent: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")


# Run the async function
if __name__ == "__main__":
    asyncio.run(main())

For more detailed examples and use cases, see the Examples section.