Pipecat Cloud

https://docs.pipecat.ai/pipecat-cloud/
Admin
Pipecat Cloud is a managed platform for deploying and scaling AI agents in production with...
Tokens:39,909
Snippets:556
Trust Score:8.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Run XML Server

Source: https://docs.pipecat.ai/pipecat-cloud/guides/telephony/plivo-websocket

Install the necessary Python packages and start the FastAPI server for your Plivo XML responses.

```bash
uv add fastapi uvicorn
python server.py
```

--------------------------------

### Pre-Application Script for Datadog Agent Setup (`pre-app.sh`)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/using-datadog

This script runs before the agent launcher. It writes the Datadog API key to the agent configuration, starts the Datadog Agent service, and optionally restarts the trace agent. Debugging commands are included as comments.

```bash
#!/bin/bash

# Write the Datadog API key to the config file
echo "api_key: $DD_API_KEY" >> /etc/datadog-agent/datadog.yaml

# Start the Datadog Agent service
service datadog-agent start || true

# Include the below line only if you need traces (see "Enabling Traces")
# HACK: here we restart the Datadog Trace Agent specifically, since we know it failed to start above
service datadog-agent-trace restart || true

## DEBUGGING

# Check the status of the Datadog Agent subsystems for logging, custom metrics, and traces
# service datadog-agent status
# service datadog-agent-trace status
# datadog-agent status

# Display the Datadog agent log
# cat /var/log/datadog/agent.log
```

--------------------------------

### Handle Capacity Errors with Python

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Shows how to use the pipecatcloud library to start a session and catch AgentStartError, which includes capacity errors. Ensure you have the pipecatcloud library installed.

```python
from pipecatcloud import Session, SessionParams
from pipecatcloud.exception import AgentStartError

try:
    session = Session(
        agent_name="my-first-agent",
        api_key="pk_...",
        params=SessionParams(
            use_daily=False,
            data={}
        )
    )
except AgentStartError as e:
    # This will catch capacity errors and other start failures
    print(f"Error starting agent: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

--------------------------------

### Start Agent

Source: https://docs.pipecat.ai/pipecat-cloud/cli-reference/agent

Starts a deployed agent instance, creating an active session. This command allows for various configurations such as specifying an API key, passing data, forcing the start without confirmation, and enabling Daily WebRTC sessions with custom properties.

```APIDOC
## Start Agent

### Description
Starts a deployed agent instance, creating an active session.

### Usage
```
pipecat cloud agent start [agent-name] [OPTIONS]
```

### Arguments
#### agent-name
- **agent-name** (string) - Required - Unique string identifier for the agent deployment. Must not contain spaces.

### Options
#### --config-file
- **--config-file** (string) - Optional - Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.

#### --api-key / -k
- **--api-key** / **-k** (string) - Optional - Public API key to authenticate the agent deployment. Will default to any key set in your config.

#### --data / -d
- **--data** / **-d** (string) - Optional - Stringified JSON object to pass to the agent deployment. This data will be available to the agent as a `data` parameter in your `bot()` method.

#### --force / -f
- **--force** / **-f** (boolean) - Optional - Skip summary confirmation before issuing start request. Defaults to `false`.

#### --use-daily / -D
- **--use-daily** / **-D** (boolean) - Optional - Create a Daily WebRTC session for the agent. Defaults to `false`.

#### --daily-properties / -p
- **--daily-properties** / **-p** (string) - Optional - Stringified JSON object with Daily room properties to customize the WebRTC session. Only used when `--use-daily` is set to true.

#### --organization / -o
- **--organization** / **-o** (string) - Optional - Organization to start the agent for. If not provided, uses the current organization from your configuration.
```

--------------------------------

### Start a Deployed Agent Instance

Source: https://docs.pipecat.ai/pipecat-cloud/cli-reference/agent

Use this command to start a deployed agent instance, creating an active session. You can specify the agent name, configuration file, API key, and data to pass to the agent.

```bash
pipecat cloud agent start [ARGS] [OPTIONS]

```

--------------------------------

### Start Agent Session (REST API)

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

This snippet demonstrates how to start a new agent session using the REST API. It includes an example of the request and the expected response when the capacity is exceeded (429 status code).

```APIDOC
## POST /v1/public/{agent_name}/start

### Description
Starts a new agent session for a given agent.

### Method
POST

### Endpoint
/v1/public/{agent_name}/start

### Parameters
#### Path Parameters
- **agent_name** (string) - Required - The name of the agent to start a session for.

#### Request Body
- **data** (object) - Optional - Additional data to pass to the session.

### Request Example
```json
{
  "data": {}
}
```

### Response
#### Success Response (200)
- **session_id** (string) - The ID of the newly created session.

#### Error Response (429)
- **status** (integer) - The HTTP status code, which will be 429 for capacity errors.
- **code** (string) - A specific error code, "429" for capacity errors.
- **message** (string) - A message indicating that the rate limit has been exceeded.

### Response Example (429)
```json
{
  "status": 429,
  "code": "429",
  "message": "Rate limit exceeded. Please try again later"
}
```
```

--------------------------------

### Call Center Example Calculation

Source: https://docs.pipecat.ai/pipecat-cloud/guides/capacity-planning

This example demonstrates the application of the optimal reserved agent formula for a voice AI call center with specific baseline, growth rate, and creation delay parameters.

```text
Optimal Reserved = MAX(10, 1 × 30)
                 = MAX(10, 30)
                 = 30
```

--------------------------------

### Start Session and Connect with WebSocket (Token Authentication)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/generic-websocket

This Python snippet demonstrates how to start a WebSocket session using the `/start` API when token authentication is enabled. It retrieves the WebSocket URL and token, then connects using the `websockets` library.

```python
import requests
import websockets

resp = requests.post(
    "https://api.pipecat.daily.co/v1/public/my-agent/start",
    headers={"Authorization": "Bearer pk_your_public_key"},
    json={"transport": "websocket", "body": {"caller_id": "abc123"}},
).json()

ws_url = resp["wsUrl"]
if resp.get("body"):
    ws_url = f"{ws_url}?body={resp['body']}"

async with websockets.connect(
    ws_url,
    additional_headers={"Authorization": f"Bearer {resp['token']}"},
) as ws:
    ...
```

--------------------------------

### Start Agent Session (Python SDK)

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

This snippet shows how to start a new agent session using the Python SDK. It includes error handling for `AgentStartError`, which covers capacity errors and other potential failures during session initiation.

```APIDOC
## pipecatcloud.Session.start()

### Description
Initiates a new session for an agent using the Python SDK. This method handles potential errors during the agent start process, including capacity limitations.

### Method Signature
`Session(agent_name: str, api_key: str, params: SessionParams = None)`

### Parameters
- **agent_name** (str) - Required - The name of the agent for which to start a session.
- **api_key** (str) - Required - Your public API key for authentication.
- **params** (SessionParams, optional) - Parameters for the session, such as `use_daily` and custom `data`.
  - **use_daily** (bool) - Whether to use Daily services.
  - **data** (dict) - Additional data to pass to the session.

### Exception Handling
- **AgentStartError**: Catches errors specifically related to starting an agent, including capacity errors.
- **Exception**: Catches any other unexpected errors during the process.

### Example Usage
```python
from pipecatcloud import Session, SessionParams
from pipecatcloud.exception import AgentStartError

try:
    session = Session(
        agent_name="my-first-agent",
        api_key="pk_...",
        params=SessionParams(
            use_daily=False,
            data={}
        )
    )
    # Proceed with using the session object
except AgentStartError as e:
    # Handle capacity errors or other agent start failures
    print(f"Error starting agent: {e}")
except Exception as e:
    # Handle unexpected errors
    print(f"Unexpected error: {e}")
```
```

--------------------------------

### Start Agent with JSON Data

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Pass JSON data directly to the agent start command. Ensure the data is JSON-serializable.

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

--------------------------------

### Start Pipecat Agent with Daily Transport (CLI)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/daily-webrtc

Use the `--use-daily` flag to start an agent with Daily transport. Custom Daily room properties can be provided using `--daily-properties`.

```bash
pipecat cloud agent start my-agent-name --use-daily
```

```bash
pipecat cloud agent start my-agent-name --use-daily --daily-properties '{"enable_recording": "cloud"}'
```

--------------------------------

### Start Pipecat Agent with Daily Transport (REST API)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/daily-webrtc

Initiate an agent start request via the REST API, setting `createDailyRoom` to true and providing optional `dailyRoomProperties`.

```bash
curl --location --request POST 'https://api.pipecat.daily.co/v1/public/my-agent-name/start' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "createDailyRoom": true,
    "dailyRoomProperties": {
      "enable_recording": "cloud"
    }
  }'
```

--------------------------------

### GitLab CI with PAT

Source: https://docs.pipecat.ai/pipecat-cloud/guides/personal-access-tokens

Set up a GitLab CI pipeline to use a PAT by adding `PIPECAT_TOKEN` as a masked CI/CD variable. This example installs the Pipecat CLI and deploys an agent.

```yaml
deploy:
  image: python:3.12
  script:
    - curl -LsSf https://astral.sh/uv/install.sh | sh
    - source $HOME/.local/bin/env
    - uv tool install "pipecat-ai[cli]" --with pipecatcloud
    - pipecat cloud deploy my-agent --yes
```

--------------------------------

### List Available Regions via CLI

Source: https://docs.pipecat.ai/pipecat-cloud/guides/regions

Use this command to list all available geographic regions for agent deployment. No specific setup is required beyond having the Pipecat CLI installed.

```bash
pipecat cloud regions list
```

--------------------------------

### Start Agent Session via Pipecat Cloud Python Library

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Utilize the Pipecat Cloud Python library to start a session with your agent. This method simplifies session creation, allowing you to configure Daily room properties and pass custom data. Error handling for `AgentStartError` is included.

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

--------------------------------

### Start Agent Session via CLI

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Initiates a session with your agent using the Pipecat Cloud command-line interface. This command allows starting an agent by its name and authenticating with an API key.

```APIDOC
## pipecat cloud agent start

### Description
Starts a session with a specified agent via the CLI.

### Command
`pipecat cloud agent start <agent_name> --api-key <api_key>`

### Parameters
- **agent_name** (string) - Required - The name of the agent to start.
- **--api-key** (string) - Required - Your public API key (e.g., `pk_...`).

### Usage Example
```shell
pipecat cloud agent start my-first-agent --api-key pk_...
```

### Default API Key
To use a default API key, set it first:
```shell
pipecat cloud organizations keys use <key_name>
```
Then the command can be simplified to:
```shell
pipecat cloud agent start <agent_name>
```

### See Also
- [CLI reference](../cli-reference/agent#start)
```

--------------------------------

### Start Agent with Data from File

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Load JSON data for the agent from a specified file. This is useful for larger or more complex data structures.

```bash
pipecat cloud agent start my-first-agent --data-file data.json
```

--------------------------------

### Install Pipecat CLI with Cloud Plugin

Source: https://docs.pipecat.ai/pipecat-cloud/introduction

Install the Pipecat CLI along with the Pipecat Cloud plugin. This command is used to set up the necessary tools for deploying agents to Pipecat Cloud.

```bash
uv tool install "pipecat-ai[cli]" --with pipecatcloud
```

--------------------------------

### Regional WebSocket Endpoint Example

Source: https://docs.pipecat.ai/pipecat-cloud/guides/telephony/exotel-websocket

When deploying your agent to a specific region, use the regional WebSocket endpoint. This example shows the format for a European deployment.

```text
wss://eu-central.api.pipecat.daily.co/ws/exotel?serviceHost=my-agent.my-org
```

--------------------------------

### Start Agent Session via CLI

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Initiate an agent session directly from your command line using the Pipecat Cloud CLI. Replace `my-first-agent` with your agent's name and `pk_...` with your API key.

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

--------------------------------

### Start Pipecat Agent with Daily Transport (Python SDK)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/daily-webrtc

Initiate a Pipecat Cloud session with Daily transport enabled using the `use_daily=True` parameter. Custom Daily room properties can be passed in `daily_room_properties`.

```python
from pipecatcloud import Session, SessionParams

# Create and start a session
session = Session(
    agent_name="my-agent",
    api_key="pk_...",
    params=SessionParams(
        use_daily=True,
        # Optionally customize the Daily room
        daily_room_properties={
            "enable_recording": "cloud"
        }
    )
)
response = await session.start()

# Access the Daily room URL and token
daily_url = f"{response['dailyRoom']}?t={response['dailyToken']}"
print(f"Join the call at: {daily_url}")
```

--------------------------------

### Start Agent Session via Python Library

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Initiates a session with your agent using the Pipecat Cloud Python library. This method simplifies session creation and allows configuration of Daily room properties and custom data.

```APIDOC
## Session.start()

### Description
Starts a session with the agent configured in the Session object.

### Method
`session.start()`

### Parameters
This method is called on a `Session` object which is initialized with:
- **agent_name** (string) - Required - The name of the agent to start.
- **api_key** (string) - Required - Your public API key.
- **params** (SessionParams) - Optional - Parameters for the session.
  - **use_daily** (boolean) - Optional - If true, creates a Daily room.
  - **daily_room_properties** (object) - Optional - Properties for the Daily room (e.g., `{"start_video_off": False}`).
  - **data** (object) - Optional - Custom data to pass to your agent (e.g., `{"key": "value"}`).

### Response
#### Success Response
Returns a dictionary containing session details, including Daily room URL and token if `use_daily` is true.
- **dailyRoom** (string) - URL for the Daily room.
- **dailyToken** (string) - Token for accessing the Daily room.

#### Response Example
```json
{
  "dailyRoom": "https://api.daily.co/v1/rooms/some-room-id",
  "dailyToken": "some-token"
}
```

### Error Handling
- **AgentStartError**: Raised if there is an error starting the agent.
- **Exception**: Raised for other unexpected errors.
```

--------------------------------

### Start Agent Session via cURL

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Use this cURL command to start an agent session programmatically via the REST API. Ensure you replace `{agent_name}` with your agent's name and `PUBLIC_API_KEY` with your actual public API key. The `createDailyRoom` flag and `body` data are optional.

```bash
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"}
    }'
```

--------------------------------

### Update Dockerfile with Datadog Agent Installation

Source: https://docs.pipecat.ai/pipecat-cloud/guides/using-datadog

Modify your Dockerfile to install the Datadog Agent, configure its settings by copying `datadog.yaml` and `python.d` configurations, prepare the filesystem for Unix sockets, and place the pre-app script.

```dockerfile
# Install the Datadog Agent
# (note that you can literally use "dummy"—or anything else—as the API key)
RUN apt-get -y update; apt-get -y install curl
RUN DD_API_KEY=dummy \
    DD_INSTALL_ONLY=true \
    bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

# Configure Datadog Agent
COPY ./datadog.yaml /etc/datadog-agent
# Include the below line if you need logging (see "Enabling Logging")
COPY ./python.d /etc/datadog-agent/conf.d/python.d

# Include the below lines only if you need traces or custom metrics (see "Enabling Traces" or "Enabling Custom Metrics")
# Prepare file system for the Datadog Agent to use for Unix Sockets
RUN mkdir -p /var/run/datadog/
RUN chown dd-agent:dd-agent /var/run/datadog/

# Start Datadog Agent (move pre-app script to expected place where it'll be invoked by Pipecat Cloud base image)
COPY --chmod=755 ./pre-app.sh /app/
```

--------------------------------

### Build and Deploy with Pipecat Cloud Action v1

Source: https://docs.pipecat.ai/pipecat-cloud/guides/ci-with-github-actions

Use this action to build, tag, and push Docker images as part of your workflow. Ensure you have registry credentials and the `packages: write` permission for GHCR. This setup is recommended for users who need to run `docker build` and push to their own container registry.

```yaml
- name: Build and Deploy to Pipecat Cloud
  uses: daily-co/pipecat-cloud-deploy-action@v1
  with:
    api-key: ${{ secrets.PCC_API_KEY }}
    agent-name: ${{ github.event.repository.name }}
    build: true
    image: ${{ secrets.DOCKERHUB_USERNAME }}/${{ github.event.repository.name }}
    registry-username: ${{ secrets.DOCKERHUB_USERNAME }}
    registry-password: ${{ secrets.DOCKERHUB_TOKEN }}
    secret-set: my-secret-set
    image-credentials: my-image-pull-secret

```

--------------------------------

### Check Agent Deployment Status

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/deploy

Verify the status of your deployed agent. A 'ready' status indicates it is available to be started.

```bash
pipecat cloud agent status my-first-agent
```

--------------------------------

### Start Agent Session via Python aiohttp

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Initiate an agent session using Python's `aiohttp` library. This asynchronous approach sends a POST request to the Pipecat Cloud API. You can specify `createDailyRoom` and pass custom data in the request body.

```python
endpoint = "https://api.pipecat.daily.co/v1/public/{service}/start"
agent_name = "my-first-agent"
api_key = "pk_..."

async with aiohttp.ClientSession() as session:
    response = await session.post(
        f"{endpoint.format(service=agent_name)}",
        headers={"Authorization": f"Bearer {api_key}"},
        json={
            "createDailyRoom": True,  # Creates a Daily room
            "body": {"custom": "data"}  # Data to pass to your agent
        }
    )
```

--------------------------------

### List Available Pipecat API Keys

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/accounts-and-organizations

Use this command to view all available API keys associated with your Pipecat organization. No setup is required.

```bash
pipecat cloud organizations keys list
```

--------------------------------

### Start Agent Session via REST API

Source: https://docs.pipecat.ai/pipecat-cloud/introduction

Start an agent session on demand using the Pipecat Cloud REST API. Ensure you replace {agentName} with your agent's name and <token> with your authentication token.

```bash
curl --request POST \
--url https://api.pipecat.daily.co/v1/public/{agentName}/start \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \

```

--------------------------------

### GitHub Actions Example for Pipecat Cloud Deployment

Source: https://docs.pipecat.ai/pipecat-cloud/guides/cloud-builds

This GitHub Actions workflow deploys to Pipecat Cloud using the `pipecat cloud deploy --yes` command and requires the `PIPECAT_CLOUD_API_KEY` environment secret.

```yaml
- name: Deploy to Pipecat Cloud
  run: pipecat cloud deploy --yes
  env:
    PIPECAT_CLOUD_API_KEY: ${{ secrets.PIPECAT_CLOUD_API_KEY }}
```

--------------------------------

### Handle Capacity Errors with cURL

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Demonstrates how to make a POST request to start an agent and shows the expected JSON response for a capacity error (429 status code).

```bash
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"
>> }
```

--------------------------------

### List Available Secret Sets

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets

Use this command to view all available secret sets within your current workspace or organization. No setup is required.

```bash
pipecat cloud secrets list
```

--------------------------------

### Set Default API Key for CLI

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Configure a default API key for subsequent `pipecat cloud agent start` commands to avoid repeatedly specifying the key. Use `my-default-key` as a placeholder for your key's name.

```shell
pipecat cloud organizations keys use my-default-key
```

--------------------------------

### Dockerfile for Agent using uv

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/agent-images

Use this Dockerfile to containerize your agent project with uv for dependency management. It installs project dependencies from a lockfile and pyproject.toml.

```dockerfile
FROM dailyco/pipecat-base:latest

# Enable bytecode compilation
ENV UV_COMPILE_BYTECODE=1

# Copy from the cache instead of linking since it's a mounted volume
ENV UV_LINK_MODE=copy

# Uncomment this if you wish to print a summary of the features available in the base image.
# ENV PCC_LOG_FEATURES_SUMMARY=true

# Install the project's dependencies using the lockfile and settings
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev

# Copy the application code
COPY ./bot.py bot.py
```

--------------------------------

### List active sessions for an agent

Source: https://docs.pipecat.ai/pipecat-cloud/cli-reference/agent

Lists active sessions for a given agent. If no sessions are active, it provides instructions to start a new one. With the --id option, it shows detailed metrics for a specific session.

```bash
pipecat cloud agent sessions [ARGS] [OPTIONS]
```

--------------------------------

### Monorepo Configuration for GitHub Actions Deployment

Source: https://docs.pipecat.ai/pipecat-cloud/guides/ci-with-github-actions

Configure your GitHub Actions workflow to deploy an agent located in a subdirectory of your monorepo. This example specifies the build context and Dockerfile path, and uses `paths` to trigger the workflow only on changes within the specified directory.

```yaml
name: Deploy to Pipecat Cloud

on:
  push:
    branches: ["main"]
    paths:
      - "server/**"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build and Deploy to Pipecat Cloud
        uses: daily-co/pipecat-cloud-deploy-action@v2
        with:
          api-key: ${{ secrets.PCC_API_KEY }}
          agent-name: ${{ github.event.repository.name }}
          cloud-build: true
          build-context: ./server
          dockerfile: Dockerfile
          secret-set: my-secret-set
```

--------------------------------

### Deploy Agent Maintaining One Warm Instance

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/scaling

Deploys an agent and configures it to maintain at least one warm instance at all times to reduce cold starts. Note: This incurs charges even when the agent is not in use.

```shell
pipecat cloud deploy [agent-name] --min-agents 1
```

--------------------------------

### Create Cloud Build Configuration

Source: https://docs.pipecat.ai/pipecat-cloud/guides/cloud-builds

Create a `pcc-deploy.toml` file in your project root to configure agent deployment. Specify the agent name and the secret set to use.

```toml
agent_name = "my-agent"
secret_set = "my-secrets"
```

--------------------------------

### GitHub Actions Workflow with PAT

Source: https://docs.pipecat.ai/pipecat-cloud/guides/personal-access-tokens

Configure a GitHub Actions workflow to use a PAT stored as a repository secret named `PIPECAT_TOKEN`. This example installs the Pipecat CLI and deploys an agent.

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      PIPECAT_TOKEN: ${{ secrets.PIPECAT_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5

      - name: Install CLI
        run: uv tool install "pipecat-ai[cli]" --with pipecatcloud

      - name: Deploy
        run: pipecat cloud deploy my-agent --yes
```

--------------------------------

### Basic pcc-deploy.toml Configuration

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/deploy

Use a `pcc-deploy.toml` file for shareable deployment configurations. CLI arguments override these settings.

```toml
agent_name = "my-agent"
secret_set = "my-agent-secrets"
agent_profile = "agent-1x"
region = "us-west"

[scaling]
    min_agents = 1
```

--------------------------------

### List, Status, and Logs for Cloud Builds

Source: https://docs.pipecat.ai/pipecat-cloud/guides/cloud-builds

Use these commands to monitor the status and retrieve logs for your cloud builds.

```shell
# List recent builds
pipecat cloud build list
```

```shell
# Check build status
pipecat cloud build status <build-id>
```

```shell
# View build logs
pipecat cloud build logs <build-id>
```

--------------------------------

### Regional WebSocket Endpoint Example

Source: https://docs.pipecat.ai/pipecat-cloud/guides/telephony/telnyx-websocket

When deploying your agent to a specific region, use the corresponding regional WebSocket endpoint for the Telnyx integration. This example shows the European endpoint.

```xml
wss://eu-central.api.pipecat.daily.co/ws/telnyx?serviceHost=my-agent.my-org
```

--------------------------------

### Daily Webhook Payload Example

Source: https://docs.pipecat.ai/pipecat-cloud/guides/telephony/daily-dial-in

This is an example of the JSON payload received from Daily when an external call is initiated. It contains essential information about the call, such as caller and receiver phone numbers.

```json
{
  "To": "+15559876543",
  "From": "+15551234567",
  "callId": "uuid",
  "callDomain": "uuid"
}
```

--------------------------------

### Deploy Agent using Docker Hub Configuration

Source: https://docs.pipecat.ai/pipecat-cloud/guides/container-registries/docker-hub

Initiate the deployment of your agent using the settings defined in your `pcc-deploy.toml` file.

```bash
pipecat cloud deploy
```

--------------------------------

### Cloud Build Configuration in pcc-deploy.toml

Source: https://docs.pipecat.ai/pipecat-cloud/guides/cloud-builds

Define build settings such as context directory, Dockerfile path, and exclusion patterns in the `pcc-deploy.toml` file.

```toml
agent_name = "my-agent"
secret_set = "my-secrets"

[build]
context_dir = "."           # Build context directory (default: ".")
dockerfile = "Dockerfile"   # Dockerfile path (default: "Dockerfile")

[build.exclude]
patterns = ["*.md", "tests/"]  # Additional exclusion patterns
```

--------------------------------

### Customize Readiness Check

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/health-checks

Override the default readiness behavior by defining a `readyz()` function. It can return a boolean or a dictionary with a 'ready' key. Use this to gate on agent dependencies.

```python
# Simple boolean
def readyz() -> bool:
    return is_healthy()
```

```python
# With additional detail (returned in the response body)
def readyz() -> dict:
    if not database_connected():
        return {"ready": False, "reason": "database unavailable"}
    return {"ready": True}
```

--------------------------------

### Regional WebSocket Endpoint Example

Source: https://docs.pipecat.ai/pipecat-cloud/guides/regions

Connect to a specific region's WebSocket endpoint to reduce latency and keep traffic within a geographic area. This example shows connecting to Twilio in the 'eu-central' region.

```bash
wss://eu-central.api.pipecat.daily.co/ws/twilio
```

--------------------------------

### Expose Session Status via GET Endpoint

Source: https://docs.pipecat.ai/pipecat-cloud/guides/session-api

This Python snippet shows how to create a GET endpoint that exposes session state, such as message count and user name, without directly interacting with the pipeline.

```python
from pipecatcloud_system import app

session_data = {"messages": [], "user_name": None}

@app.get("/status")
def get_status():
    return {
        "message_count": len(session_data["messages"]),
        "user_name": session_data["user_name"],
    }
```

--------------------------------

### Enable Krisp VIVA via CLI

Source: https://docs.pipecat.ai/pipecat-cloud/guides/krisp-viva

Use the `pipecat cloud deploy` command with the `--krisp-viva-audio-filter` flag to enable Krisp VIVA. Specify 'tel' for 16kHz or 'pro' for 32kHz audio support.

```bash
pipecat cloud deploy --krisp-viva-audio-filter tel
```

--------------------------------

### Deploy Agent with Default Minimum Agents

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/scaling

Deploys an agent with the default minimum agents setting, which is zero warm instances.

```shell
pipecat cloud deploy [agent-name]
```

--------------------------------

### Get Agent Status

Source: https://docs.pipecat.ai/pipecat-cloud/cli-reference/agent

Shows the current status of an agent deployment, including its health and conditions. Requires the agent name.

```bash
pipecat cloud agent status [ARGS]
```

--------------------------------

### Call Endpoint to Get Session Status

Source: https://docs.pipecat.ai/pipecat-cloud/guides/session-api

This curl command demonstrates how to call the /status endpoint to retrieve the current session status.

```bash
curl -X GET \
  'https://api.pipecat.daily.co/v1/public/my-agent/sessions/{session_id}/status' \
  -H 'Authorization: Bearer pk_...'
```

--------------------------------

### Enable Krisp VIVA via REST API (Create Agent)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/krisp-viva

When creating a new agent using the REST API, include the `krispViva` object with the `audioFilter` parameter set to 'tel' or 'pro'.

```bash
curl -X POST https://api.pipecat.daily.co/v1/agents \
  -H "Authorization: Bearer YOUR_PRIVATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceName": "voice-starter",
    "image": "your-repo/voice-starter:0.1",
    "secretSet": "voice-starter-secrets",
    "krispViva": {
      "audioFilter": "tel"
    },
    "autoScaling": {
      "minAgents": 1,
      "maxAgents": 10
    }
  }'
```

--------------------------------

### Dockerfile for Agent using pip

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/agent-images

Use this Dockerfile to containerize your agent project with pip for dependency management. It installs dependencies from a requirements.txt file.

```dockerfile
FROM dailyco/pipecat-base:latest

COPY ./requirements.txt requirements.txt

# Uncomment this if you wish to print a summary of the features available in the base image.
# ENV PCC_LOG_FEATURES_SUMMARY=true

RUN pip install --no-cache-dir --upgrade -r requirements.txt

COPY ./bot.py bot.py
```

--------------------------------

### Expose Local Server with ngrok

Source: https://docs.pipecat.ai/pipecat-cloud/guides/telephony/plivo-websocket

Use ngrok to create a public URL for your local XML server, which is necessary for Plivo to access it during testing.

```bash
ngrok http 7860
```

--------------------------------

### Prepare Datadog Agent File System

Source: https://docs.pipecat.ai/pipecat-cloud/guides/using-datadog

Create and set ownership for the Datadog agent's run directory in your Dockerfile. This is necessary for the agent to function correctly.

```dockerfile
RUN mkdir -p /var/run/datadog/
RUN chown dd-agent:dd-agent /var/run/datadog/
```

--------------------------------

### View Session CPU and Memory Metrics via CLI

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/logging

Use the 'sessions' command with a specific session ID to view CPU and memory usage metrics, including sparkline visualizations and percentile summaries.

```bash
pipecat cloud agent sessions my-agent --id <session-id>
```

--------------------------------

### Deploying Pre-built Image from Own Container Registry

Source: https://docs.pipecat.ai/pipecat-cloud/guides/ci-with-github-actions

Deploy an agent using a pre-built Docker image hosted in your own container registry. This bypasses the cloud build process. Ensure the image is built for `linux/arm64` and provide `image-credentials` if the registry is private.

```yaml
- name: Deploy to Pipecat Cloud
  uses: daily-co/pipecat-cloud-deploy-action@v2
  with:
    api-key: ${{ secrets.PCC_API_KEY }}
    agent-name: ${{ github.event.repository.name }}
    image: my-registry.example.com/my-agent:v1.2.3
    image-credentials: my-image-pull-secret
    secret-set: my-secret-set
```

--------------------------------

### Authenticate Docker with ECR

Source: https://docs.pipecat.ai/pipecat-cloud/guides/container-registries/aws-ecr

Authenticates your Docker client with your AWS ECR registry using the AWS CLI. Ensure you have the AWS CLI installed and configured.

```bash
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.amazonaws.com
```

--------------------------------

### Create Public API Key

Source: https://docs.pipecat.ai/pipecat-cloud/security/security-and-compliance

Use this command to create a public API key for client applications. This key can then be associated with specific agents.

```bash
pipecat cloud organizations keys create

pipecat cloud organizations keys use
```

--------------------------------

### Record Custom Metrics in Python

Source: https://docs.pipecat.ai/pipecat-cloud/guides/using-datadog

Use the `statsd.increment()` function from the `datadog` library to record custom metrics. This example increments a counter named 'myagent.my_function_call'.

```python
from datadog import statsd

def my_function_call():
    statsd.increment("myagent.my_function_call")

```

--------------------------------

### Delete an agent deployment

Source: https://docs.pipecat.ai/pipecat-cloud/cli-reference/agent

Deletes an agent deployment irreversibly, preventing new agent starts and removing all associated data. The --force option bypasses confirmation prompts.

```bash
pipecat cloud agent delete [ARGS] [OPTIONS]
```

--------------------------------

### Get Agent Logs

Source: https://docs.pipecat.ai/pipecat-cloud/cli-reference/agent

Displays combined logs from all agent instances for debugging. Requires the agent name. Logs can be filtered by level, limit, deployment ID, or session ID.

```bash
pipecat cloud agent logs [ARGS] [OPTIONS]
```

--------------------------------

### Initiate Outbound Call with curl

Source: https://docs.pipecat.ai/pipecat-cloud/guides/telephony/daily-dial-out

Use this curl command to initiate an outbound call. Ensure `enable_dialout` is set to true in `dailyRoomProperties` and provide the target phone number in `dialout_settings`.

```bash
curl --request POST \
--url https://api.pipecat.daily.co/v1/public/{service}/start \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{ \
    'createDailyRoom': true, \
    'dailyRoomProperties': { \
        'enable_dialout': true, \
        'exp': 1742353929 \
    }, \
    'body': { \
        'dialout_settings': \
        [{'phoneNumber': '+1TARGET', 'callerId': 'UUID_OF_PURCHASED_NUM'}] \
    } \
}'
```

--------------------------------

### Configure Log Collection for Agent (`python.d/conf.yaml`)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/using-datadog

Define the log collection settings for your agent by creating a `python.d/conf.yaml` file. Specify the log file path, service name, and source details for Datadog.

```yaml
# Use whatever agent name would be useful for you to see in the Datadog dashboard
logs:
  - type: file
    path: /var/log/<my-agent-name>/datadog.log
    service: <my-agent-name>
    source: python
    sourcecategory: sourcecode
```

--------------------------------

### List Agent Deployments

Source: https://docs.pipecat.ai/pipecat-cloud/cli-reference/agent

Lists the deployment history for an agent, including image versions and timestamps. Requires the agent name.

```bash
pipecat cloud agent deployments [ARGS]
```

--------------------------------

### Datadog Agent Configuration (`datadog.yaml`)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/using-datadog

Configure the Datadog Agent for logging, traces, and custom metrics. Ensure `site` and `hostname` are set appropriately. Uncomment specific sections to enable or disable features like logging, APM tracing, and DogStatsD.

```yaml
site: <your-datadog-site> # e.g. us5.datadoghq.com
hostname: pipecat.daily.co # (or whatever would be useful for you to see in the Datadog dashboards)

# Include the following line only if you need logging (see "Enabling Logging")
logs_enabled: true

# Uncomment the below lines if you DON'T need traces (see "Enabling Traces")
# apm_config:
#   enabled: false

# Uncomment the below lines if you DON'T need custom metrics (see "Enabling Custom Metrics")
# use_dogstatsd: false

kubelet_tls_verify: false
autoconfig_exclude_features:
  - kubernetes
  - orchestratorexplorer
```

--------------------------------

### Start Agent Session via REST API

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions

Initiates a session with your agent using the Pipecat Cloud REST API. This endpoint requires your public API key for authorization and allows passing custom data to the agent.

```APIDOC
## POST /v1/public/{agent_name}/start

### Description
Starts a session with your agent.

### Method
POST

### Endpoint
`https://api.pipecat.daily.co/v1/public/{agent_name}/start`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer PUBLIC_API_KEY`)
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **createDailyRoom** (boolean) - Optional - If true, creates a Daily room for the session.
- **body** (object) - Optional - Custom data to pass to your agent.
  - **custom** (string) - Example of custom data.

### Request Example
```json
{
  "createDailyRoom": true,
  "body": {"custom": "data"}
}
```

### Response
#### Success Response (200)
- **dailyRoom** (string) - URL for the Daily room.
- **dailyToken** (string) - Token for accessing the Daily room.

#### Response Example
```json
{
  "dailyRoom": "https://api.daily.co/v1/rooms/some-room-id",
  "dailyToken": "some-token"
}
```
```

--------------------------------

### Basic GitHub Actions Workflow for Pipecat Cloud Deployment

Source: https://docs.pipecat.ai/pipecat-cloud/guides/ci-with-github-actions

This workflow triggers on pushes to the main branch, checks out the code, and uses the pipecat-cloud-deploy-action to build and deploy the agent. Ensure your GitHub secrets are configured with your Pipecat Cloud API key.

```yaml
name: Deploy to Pipecat Cloud

on:
  push:
    branches: ["main"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build and Deploy to Pipecat Cloud
        uses: daily-co/pipecat-cloud-deploy-action@v2
        with:
          api-key: ${{ secrets.PCC_API_KEY }}
          agent-name: ${{ github.event.repository.name }}
          cloud-build: true
          secret-set: my-secret-set
          region: us-east
```

--------------------------------

### Deploy Agent with Specific Profile (CLI)

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/deploy

Specify the agent profile for resource allocation via the CLI. Choose the smallest profile that meets performance requirements.

```bash
pipecat cloud deploy --profile agent-2x
```

--------------------------------

### pcc-deploy.toml Configuration with Custom Image

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/deploy

Configure custom image deployment in `pcc-deploy.toml`, including credentials for private registries.

```toml
agent_name = "my-agent"
image = "your-docker-repository/my-agent:0.1"
image_credentials = "dockerhub-access"
secret_set = "my-agent-secrets"
```

--------------------------------

### Twilio Function to Connect to Pipecat Cloud

Source: https://docs.pipecat.ai/pipecat-cloud/guides/websocket-authentication

This Twilio Function calls the Pipecat Cloud `/start` endpoint to get a WebSocket authentication token. It then returns TwiML that includes the authenticated WebSocket URL. Store your Pipecat Cloud public API key as an environment variable (e.g., `PCC_PUBLIC_KEY`) in your Twilio Function settings.

```javascript
exports.handler = async function (context, event, callback) {
  // Call PCC /start to get a websocket auth token
  const startResponse = await fetch(
    "https://api.pipecat.daily.co/v1/public/my-agent/start",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${context.PCC_PUBLIC_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ transport: "websocket" }),
    },
  );
  const { token, wsUrl } = await startResponse.json();

  // Return TwiML with the authenticated WebSocket URL
  const twiml = new Twilio.twiml.VoiceResponse();
  const connect = twiml.connect();
  connect.stream({ url: `${wsUrl}/${token}` });
  callback(null, twiml);
};
```

--------------------------------

### Docker Hub Deployment Configuration

Source: https://docs.pipecat.ai/pipecat-cloud/guides/container-registries/docker-hub

Define your agent's name, Docker Hub image, and associated secret credentials in a `pcc-deploy.toml` file for deployment.

```toml
agent_name = "my-agent"
image = "your-username/my-agent:0.1"
secret_set = "my-agent-secrets"
image_credentials = "my-dockerhub-creds"

[scaling]
    min_agents = 0
```

--------------------------------

### Plivo XML Server using FastAPI

Source: https://docs.pipecat.ai/pipecat-cloud/guides/telephony/plivo-websocket

This Python script creates a web server that generates Plivo-compatible XML to initiate WebSocket streaming to Pipecat Cloud. Ensure both 'agent' and 'org' query parameters are provided.

```python
from fastapi import FastAPI, Query, HTTPException
from starlette.responses import Response
import uvicorn

app = FastAPI(title="Plivo XML Server")

@app.get("/plivo-xml")
async def plivo_xml(
    agent: str = Query(..., description="Agent name"),
    org: str = Query(..., description="Organization name"),
):
    """
    Returns XML for Plivo to start WebSocket streaming to Pipecat Cloud
    Example: /plivo-xml?agent=my-bot&org=my-org-123
    """
    if not agent or not org:
        raise HTTPException(status_code=400, detail="Both 'agent' and 'org' parameters are required")

    xml = f"<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Stream bidirectional="true" keepCallAlive="true" contentType="audio/x-mulaw;rate=8000">
    wss://api.pipecat.daily.co/ws/plivo?serviceHost={agent}.{org}
  </Stream>
</Response>"

    return Response(content=xml, media_type="application/xml")

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=7860)
```

--------------------------------

### Configure WebSocket Endpoint - Generic

Source: https://docs.pipecat.ai/pipecat-cloud/guides/telephony/overview

Configure your telephony provider's call flow to connect to this generic WebSocket endpoint. Your bot is responsible for parsing the provider's message format.

```bash
wss://{region}.api.pipecat.daily.co/ws/{provider}?serviceHost={agentName}.{organizationName}
```

--------------------------------

### Connect with wscat (No Authentication)

Source: https://docs.pipecat.ai/pipecat-cloud/guides/generic-websocket

Use this command to connect to the generic WebSocket endpoint when authentication is disabled (`websocket_auth = "none"`).

```bash
wscat -c "wss://us-west.api.pipecat.daily.co/ws/generic/my-agent.my-org"
```

--------------------------------

### List Available Organizations

Source: https://docs.pipecat.ai/pipecat-cloud/fundamentals/accounts-and-organizations

Retrieve a list of all organizations your account is a member of using the CLI.

```bash
pipecat cloud organizations list
```

--------------------------------

### Deployment Configuration TOML

Source: https://docs.pipecat.ai/pipecat-cloud/guides/container-registries/overview

Configure your `pcc-deploy.toml` file to specify the agent name, image, and the image credentials created in the previous step. Ensure the `image_credentials` field matches the name you provided when creating the secret.

```toml
agent_name = "my-agent"
image = "your-registry-url/my-agent:tag"
image_credentials = "my-registry-creds"
secret_set = "my-secrets"

[scaling]
    min_agents = 0
```

--------------------------------

### Agent Deployment Configuration File

Source: https://docs.pipecat.ai/pipecat-cloud/guides/regions

This TOML file defines the configuration for deploying an agent, including its name, target region, secret set, profile, and scaling parameters. Save this as 'pcc-deploy.toml'.

```toml
agent_name = "my-agent"
region = "us-east"
secret_set = "my-agent-secrets"
agent_profile = "agent-1x"

[scaling]
min_agents = 1
max_agents = 10
```
Tokens:
Raw