Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Pipecat Cloud deployment docs #142

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+303 −6
Open

Add Pipecat Cloud deployment docs #142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 25 additions & 6 deletions guides/deployment/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,16 @@ You've created your Pipecat bot, had a good chat with it locally, and are eager
[here](https://github.com/pipecat-ai/pipecat/tree/main/examples/deployment).
</Note>

### Deployment options

You have several options for deploying your Pipecat bot:

1. **Pipecat Cloud** - A purpose-built managed service designed specifically for Pipecat deployments
2. **Self-managed cloud deployment** - Deploy to providers like Fly.io, AWS, Google Cloud Run, etc.
3. **Custom infrastructure** - Run on your own servers or specialized AI infrastructure

The best choice depends on your specific requirements, scale, and expertise.

### Things you'll need

- **Transport service** - Pipecat has existing services for various different [media transport](http://localhost:3000/docs/category/transports) modes, such as WebRTC or WebSockets. If you're not using a third-party service for handling media transport, you'll want to make sure that infrastructure is hosted and ready to receive connections.
Expand All @@ -23,9 +33,9 @@ You've created your Pipecat bot, had a good chat with it locally, and are eager

## Production-ready bots

In local development things often work great as you're testing on controlled, stable network conditions. In real-world use-cases, however, your users will likely interact with your bot across a variety of different devices and network conditions.
In local development, things often work great as you're testing on controlled, stable network conditions. In real-world use-cases, however, your users will likely interact with your bot across a variety of different devices and network conditions.

WebSockets are fine for server-to-server communication or for initial development. But for production use, you’ll likely want client-server audio that uses a protocol designed for real-time media transport. For an explanation of the difference between WebSockets and WebRTC, [see this post](https://www.daily.co/blog/how-to-talk-to-an-llm-with-your-voice/#webrtc).
WebSockets are fine for server-to-server communication or for initial development. But for production use, you'll likely want client-server audio that uses a protocol designed for real-time media transport. For an explanation of the difference between WebSockets and WebRTC, [see this post](https://www.daily.co/blog/how-to-talk-to-an-llm-with-your-voice/#webrtc).

If you're targeting scalable, client-server interactions, we recommend you use WebRTC for the best results.

Expand Down Expand Up @@ -65,7 +75,16 @@ torch.hub.load(

## Provider guides

Once you've familiarized yourself with the Pipecat [deployment pattern](/docs/deploying-your-bot/02-basic-pattern.md), here are some guides that walk you through the process for the two primary hardware use cases. Remember, your Pipecat bots are simply Python processes, so you can host them on whichever infrastructure or service best suits your project.

- [Deploying with Fly.io](/docs/deploying-your-bot/fly) for service-driven / CPU bots
- Deploying with Cerebrium.ai (coming soon)
Once you've familiarized yourself with the Pipecat [deployment pattern](/docs/deploying-your-bot/02-basic-pattern.md), here are some guides that walk you through the process for various deployment options. Remember, your Pipecat bots are simply Python processes, so you can host them on whichever infrastructure or service best suits your project.

<CardGroup cols={3}>
<Card title="Pipecat Cloud" icon="cloud" href="/deployment/pipecat-cloud">
Managed service purpose-built for Pipecat deployments
</Card>
<Card title="Fly.io" icon="paper-plane" href="/deployment/fly">
For service-driven / CPU bots
</Card>
<Card title="Cerebrium" icon="brain" href="/deployment/cerebrium">
For GPU-accelerated models & specialized AI infrastructure
</Card>
</CardGroup>
277 changes: 277 additions & 0 deletions guides/deployment/pipecat-cloud.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,277 @@
---
title: "Example: Pipecat Cloud"
description: "Deploy Pipecat agents with managed infrastructure"
---

[Pipecat Cloud](https://pipecat.daily.co) is a managed platform for hosting and scaling Pipecat agents in production.

## Prerequisites

Before you begin, you'll need:

- A [Pipecat Cloud account](https://pipecat.daily.co)
- [Docker](https://www.docker.com) installed
- Python 3.10+
- The Pipecat Cloud CLI: `pip install pipecatcloud`

<Card
title="Quickstart Guide"
icon="play"
href="https://docs.pipecat.daily.co/quickstart"
>
Follow a step-by-step guided experience to deploy your first agent
</Card>

## Choosing a starting point

Pipecat Cloud offers several ways to get started:

1. **Use a starter template** - Pre-built agent configurations for common use cases
2. **Build from the base image** - Create a custom agent using the official base image
3. **Clone the starter project** - A bare-bones project template to customize

### Starter templates

Pipecat Cloud provides several ready-made templates for common agent types:

| Template | Description |
| ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [voice](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-starters/voice) | Voice conversation agent with STT, LLM and TTS |
| [twilio](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-starters/twilio) | Telephony agent that works with Twilio |
| [natural_conversation](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-starters/natural_conversation) | Agent focused on natural dialogue flow, allowing a user time to think |
| [openai_realtime](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-starters/openai_realtime) | Agent using OpenAI's Realtime API |
| [gemini_multimodal_live](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-starters/gemini_multimodal_live) | Multimodal agent using Google's Gemini Multimodal Live API |
| [vision](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-starters/vision) | Computer vision agent that can analyze images |

These templates include a functioning implementation and Dockerfile. You can use them directly:

```bash
# Clone the repository
git clone https://github.com/daily-co/pipecat-cloud-images.git

# Navigate to a starter template
cd pipecat-cloud-images/pipecat-starters/voice

# Customize the agent for your needs
```

## Project structure

Whether using a starter template or building from scratch, a basic Pipecat Cloud project typically includes:

```
my-agent/
├── bot.py # Your Pipecat pipeline
├── Dockerfile # Container definition
├── requirements.txt # Python dependencies
└── pcc-deploy.toml # Deployment config (optional)
```

### Agent implementation with bot.py

Your agent's `bot.py` code must include a specific `bot()` function that serves as the entry point for Pipecat Cloud. This function has different signatures depending on the transport method:

#### For WebRTC/Daily transports

```python
async def bot(config, room_url: str, token: str, session_id=None, session_logger=None):
"""Main bot entry point for WebRTC/Daily agents.

Args:
config: Configuration passed from the client when starting the session
room_url: The Daily room URL provided by the platform
token: The Daily room token for authentication
session_id: Unique identifier for this session
session_logger: Logger instance for this session
"""
try:
# Your initialization code
await main(room_url, token, session_logger)
except Exception as e:
# Log and re-raise to let the platform know something went wrong
if session_logger:
session_logger.exception(f"Error in bot process: {str(e)}")
raise
```

#### For WebSocket transports (e.g., Twilio)

```python
async def bot(ws: WebSocket, session_logger=None):
"""Main bot entry point for WebSocket-based agents.

Args:
ws: WebSocket connection from the client
session_logger: Logger instance for this session
"""
try:
# Your WebSocket handling code
await handle_websocket(ws, session_logger)
except Exception as e:
if session_logger:
session_logger.exception(f"Error in bot process: {str(e)}")
raise
```

<CardGroup cols={2}>
<Card
title="Complete Example: Voice Bot"
icon="code"
href="https://github.com/daily-co/pipecat-cloud-images/blob/main/pipecat-starters/voice/bot.py"
>
View a complete WebRTC voice bot implementation
</Card>

<Card
title="Complete Example: Twilio Bot"
icon="phone"
href="https://github.com/daily-co/pipecat-cloud-images/blob/main/pipecat-starters/twilio/bot.py"
>
View a complete Twilio WebSocket bot implementation
</Card>
</CardGroup>

### Example Dockerfile

Pipecat Cloud provides base images that include common dependencies for Pipecat agents:

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

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

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

This Dockerfile:

1. Uses the official Pipecat base image
2. Installs Python dependencies from requirements.txt
3. Copies your bot.py file to the container

<Note>
The base image (dailyco/pipecat-base) includes the HTTP API server, session
management, and platform integration required to run on Pipecat Cloud. See the
[base image source
code](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-base)
for details.
</Note>

## Building and pushing your Docker image

With your project structure in place, build and push your Docker image:

```bash
# Build the image
docker build --platform=linux/arm64 -t my-first-agent:latest .

# Tag the image for your repository
docker tag my-first-agent:latest your-username/my-first-agent:0.1

# Push the tagged image to the repository
docker push your-username/my-first-agent:0.1
```

<Note>
Pipecat Cloud requires ARM64 images. Make sure to specify the
`--platform=linux/arm64` flag when building.
</Note>

## Managing secrets

Your agent likely requires API keys and other credentials. Create a secret set to store them securely:

```bash
# Create an .env file with your credentials
touch .env

# Create a secret set from the file
pcc secrets set my-first-agent-secrets --file .env
```

## Deploying your agent

Deploy your agent with the CLI:

```bash
pcc deploy my-first-agent your-username/my-first-agent:0.1 --secret-set my-first-agent-secrets
```

For a more maintainable approach, create a `pcc-deploy.toml` file:

```toml
agent_name = "my-first-agent"
image = "your-username/my-first-agent:0.1"
secret_set = "my-first-agent-secrets"
image_credentials = "my-first-agent-image-credentials" # For private repos

[scaling]
min_instances = 0
```

Then deploy using:

```bash
pcc deploy
```

## Starting a session

Once deployed, you can start a session with your agent:

```bash
# Create and set a public access key if needed
pcc organizations keys create
pcc organizations keys use

# Start a session using Daily for WebRTC
pcc agent start my-first-agent --use-daily
```

This will open a Daily room where you can interact with your agent.

## Checking deployment status

Monitor your agent deployment:

```bash
# Check deployment status
pcc agent status my-first-agent

# View deployment logs
pcc agent logs my-first-agent
```

## Next steps

<CardGroup cols={2}>
<Card
title="Agent Images"
icon="box"
href="https://docs.pipecat.daily.co/agents/agent-images"
>
Learn about containerizing your agent
</Card>
<Card
title="Secrets"
icon="key"
href="https://docs.pipecat.daily.co/agents/secrets"
>
Managing sensitive information
</Card>
<Card
title="Scaling"
icon="arrows-up-down-left-right"
href="https://docs.pipecat.daily.co/agents/scaling"
>
Configure scaling for production workloads
</Card>
<Card
title="Active Sessions"
icon="phone"
href="https://docs.pipecat.daily.co/agents/active-sessions"
>
Understand how sessions work
</Card>
</CardGroup>
1 change: 1 addition & 0 deletions mint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,7 @@
"pages": [
"guides/deployment/overview",
"guides/deployment/pattern",
"guides/deployment/pipecat-cloud",
"guides/deployment/fly",
"guides/deployment/cerebrium"
]
Expand Down