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).
You must have an active billing account to start sessions. Usage is billed for
the duration of each session, please refer to
pricing for more information.
Starting active sessions can be achieved programmatically via the REST API and Python library or directly via the CLI.
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.
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:
Provide a secure endpoint to receive requests that keeps your API key secret
Pass any required data to the agent when starting a session (such as pipeline configuration, transport session data, etc.)
Handle any errors that may occur during the start process
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):
Copy
Ask AI
pcc agent start my-first-agent --data '{"room": "my-room"}'# or from a filepcc 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:
Copy
Ask AI
# bot.pyfrom pipecatcloud.agent import PipecatSessionArgumentsasync 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.
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.
While in beta, the default instance pool capacity is 50 active sessions per
deployment. Please contact us at help@daily.co or via
Discord if you require more capacity.
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:
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.
Deleting an agent deployment will block any new sessions from starting, but will not stop any active sessions. You must stop each session individually.