Starting Sessions - Pipecat (original) (raw)

Once you have made a successful deployment, you can start on-demand sessions to begin interacting with your agent. An active session is a running instance of your agent code that connects with you or your end-users. Sessions are created in response to a request and scaled up or down based on your deployment configuration (see Scaling).

Starting active sessions can be achieved programmatically via the REST API and Python library or directly via the CLI.

Running an agent

Requests to start an agent requires passing a public API key. Keys are used to ensure that only authorized users or apps can start sessions and can be cycled or revoked at any time.

Development pattern

A typical application will start a session in response to a user request (via a web UI, mobile app, phone call or other client). Pipecat Cloud takes care of your session infrastructure and scaling, so you can focus on building your application logic. Developers should:

  1. Provide a secure endpoint to receive requests that keeps your API key secret
  2. Pass any required data to the agent when starting a session (such as pipeline configuration, transport session data, etc.)
  3. Handle any errors that may occur during the start process

Using REST

The Pipecat Cloud REST API provides an endpoint to start a session with your agent over HTTP:

Using Python

The Pipecat Cloud Python library (uv add pipecatcloud) provides helper methods to start a session with your agent:

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

Using the CLI

To start an agent via the command line interface:

pipecat cloud agent start my-first-agent --api-key pk_...

You can select and use a default API key for the agent start command:

pipecat cloud organizations keys use my-default-key

See the CLI reference for more information.

Passing data

Most agents will require some initial data, such pipeline configuration, transport session credentials, etc. For sensitive data, we recommend using secrets to store and access your data securely. You pass a data blob through to the start request (please note that the data must be JSON-serializable):

pipecat cloud agent start my-first-agent --data '{"room": "my-room"}'

# or from a file
pipecat cloud agent start my-first-agent --data-file data.json

Data passed to your session can be accessed in your agent code via the bot() method, which receives session arguments:

# bot.py
from pipecat.runner.types import PipecatRunnerArguments

async def bot(args: PipecatRunnerArguments):
    # Access the session ID
    logger.info(f"Session started with ID: {args.session_id}")
    
    # Access the custom data passed to the session
    logger.info(f"Session data: {args.body}")
    
    # ...

# bot.py for voice agent
from loguru import logger
from pipecat.runner.types import DailyRunnerArguments

async def bot(args: DailyRunnerArguments):
    """Main bot entry point compatible with the FastAPI route handler.

    Args:
        room_url: The Daily room URL
        token: The Daily room token
        body: The configuration object from the request body
    """
    logger.info(f"Bot process initialized {args.room_url} {args.token}")
    logger.info(f"Custom data: {args.body}")
    logger.info(f"Session ID: {args.session_id}")

    try:
        await main(args.room_url, args.token)
        logger.info("Bot process completed")
    except Exception as e:
        logger.exception(f"Error in bot process: {str(e)}")
        raise

# bot.py for WebSocket agent
from loguru import logger
from pipecat.runner.types import WebSocketRunnerArguments

async def bot(args: WebSocketRunnerArguments):
    """Main bot entry point for WebSocket connections.

    Args:
        ws: The WebSocket connection
    """
    logger.info("WebSocket bot process initialized")
    logger.info(f"Custom data: {args.body}")
    logger.info(f"Session ID: {args.session_id}")

    try:
        await main(args.websocket)
        logger.info("WebSocket bot process completed")
    except Exception as e:
        logger.exception(f"Error in WebSocket bot process: {str(e)}")
        raise

For more advanced data requirements, your application should run its own data fetching logic before a session request is made. If you require your agent to fetch it’s own data, be mindful of any blocking requests that could slow down the start process.

Size limits

The maximum body size depends on the transport:

Requests exceeding the per-transport limit are rejected with 413 Payload Too Large before any bot is started.

Agent capacity

Deployments have an upper limit for the number of sessions that can be started concurrently. This helps developers implement cost control and workload management and can be adjusted per deployment. See Scaling for more information.

Developers are responsible for handling capacity errors when starting sessions. When your instance pool is at capacity, the start request will fail with a 429 status and code. Here is a simple example of how to handle a capacity error:

Logging and monitoring

Session observability can be accessed via the Dashboard or from the CLI.

Active sessions

To view active sessions via the CLI:

pipecat cloud agent sessions [my-first-agent]

This command will list all active sessions for the specified agent, alongside a session ID.

Session logs

To view individual session logs, use the following command:

pipecat cloud agent logs [my-first-agent] --session [session-id]

For more information, see Logging and Observability.

Stopping sessions

You can issue a termination request to stop an active session. This will immediately stop the instance so be aware of disrupting any ongoing user interactions.

pipecat cloud agent stop my-first-agent --session [session-id]

Deleting an agent deployment will block any new sessions from starting, but will not stop any active sessions. You must stop each session individually.

Session duration limits

Every service has a maximum session duration. When a session reaches this limit, its connection is forcibly closed — the session is cut off mid-flight with no notice to the bot. This is a platform-level safeguard, not a polite signal: the bot code receives a connection error the next time it tries to send or receive data. If you want the bot to say goodbye gracefully before the cap, you must implement your own timer in bot code that fires slightly earlier. By default, sessions are capped at 7200 seconds (2 hours). You can configure this per service between 60 seconds and 14400 seconds (4 hours):

pipecat cloud deploy my-agent your-docker-repository/my-agent:0.1 --max-session-duration 300

See --max-session-duration for details.

curl -X POST 'https://api.pipecat.daily.co/v1/agents/my-agent' \
  -H 'Authorization: Bearer PRIVATE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"maxSessionDuration": 300}'

See the agent update endpoint for the full schema.

Set the Max session duration field on your service’s settings page in the Dashboard .

Usage

You are charged for the duration of each session, see pricing. The exact duration of session is calculated based on:

You can monitor your usage on your Dashboard .