Starting Sessions

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:

curl --location --request POST 'https://api.pipecat.daily.co/v1/public/{agent_name}/start' \
  --header 'Authorization: Bearer PUBLIC_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "createDailyRoom": true,
    "body": {"custom": "data"}
  }'

​

Using Python

The Pipecat Python library provides helper methods to start a session with your agent:

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

try:
    # Create session object
    session = Session(
        agent_name="my-first-agent",
        api_key="pk_...",
        params=SessionParams(
            use_daily=True,  # Optional: Creates a Daily room
            data={"custom": "data"}  # Optional: Data to pass to your agent
        )
    )

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

    # Process the response
    print(f"Session started successfully")
    if "dailyRoom" in response:
        print(f"Daily room: {response['dailyRoom']}")

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

​

Using the CLI

To start an agent via the command line interface:

pcc agent start my-first-agent --api-key pk_...

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

pcc 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):

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

# or from a file
pcc 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 pipecatcloud.agent import PipecatSessionArguments

async def bot(args: PipecatSessionArguments):
    # 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}")
    
    # ...

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.

​

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:

curl --location --request POST 'https://api.pipecat.daily.co/v1/public/{agent_name}/start' \
--header 'Authorization: Bearer PUBLIC_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{}'

>> {
>>	"status": 429,
>>	"code": "429",
>>	"message": "Rate limit exceeded. Please try again later"
>> }

​

Logging and monitoring

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

​

Active sessions

To view active sessions via the CLI:

pcc 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:

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

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

​

Usage

You are charged for the duration of each session, see pricing.

The exact duration of session is calculated based on:

• Time spent instantiating the agent
• Time spent running the agent
• Time spent tearing down the agent

You can monitor your usage on your Dashboard .