163 lines
5.0 KiB
Markdown
163 lines
5.0 KiB
Markdown
# Pipecat Quickstart
|
|
|
|
Run your first Pipecat bot in under 5 minutes. This example creates a voice AI bot that you can talk to in your browser.
|
|
|
|
## Prerequisites
|
|
|
|
### Environment
|
|
|
|
- Python 3.10 or later
|
|
- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager installed
|
|
|
|
### AI Service API keys
|
|
|
|
Pipecat orchestrates different AI services in a pipeline, ensuring low latency communication. In this quickstart example, we'll use:
|
|
|
|
- [Deepgram](https://console.deepgram.com/signup) for Speech-to-Text transcriptions
|
|
- [OpenAI](https://auth.openai.com/create-account) for LLM inference
|
|
- [Cartesia](https://play.cartesia.ai/sign-up) for Text-to-Speech audio generation
|
|
|
|
Have your API keys ready. We'll add them to your `.env` shortly.
|
|
|
|
## Setup
|
|
|
|
### Set up your environment and dependencies
|
|
|
|
From `examples/quickstart`, run:
|
|
|
|
```bash
|
|
uv sync --extra webrtc \
|
|
--extra daily \
|
|
--extra silero \
|
|
--extra deepgram \
|
|
--extra openai \
|
|
--extra cartesia \
|
|
--extra runner
|
|
```
|
|
|
|
### Configure environment variables
|
|
|
|
Create a `.env` file:
|
|
|
|
```bash
|
|
cp env.example .env
|
|
```
|
|
|
|
Then, add your API keys:
|
|
|
|
```ini
|
|
DEEPGRAM_API_KEY=your_deepgram_api_key
|
|
OPENAI_API_KEY=your_openai_api_key
|
|
CARTESIA_API_KEY=your_cartesia_api_key
|
|
```
|
|
|
|
## Run your bot locally
|
|
|
|
```bash
|
|
uv run bot.py
|
|
```
|
|
|
|
**Open http://localhost:7860 in your browser** and click `Connect` to start talking to your bot.
|
|
|
|
> 💡 First run note: The initial startup may take ~20 seconds as Pipecat downloads required models and imports.
|
|
|
|
## Deploy to Pipecat Cloud (Optional)
|
|
|
|
Pipecat Cloud is a managed platform for hosting and scaling your Pipecat bots in production.
|
|
|
|
[Sign up](https://pipecat.daily.co/sign-up) for a Pipecat Cloud account and deploy your bot in minutes.
|
|
|
|
### Setup
|
|
|
|
#### Install `pipecatcloud`
|
|
|
|
The `pipecatcloud` CLI manages your Pipecat deployments, secrets, and organization. Install in your virtual enviroment:
|
|
|
|
```bash
|
|
uv add pipecatcloud
|
|
```
|
|
|
|
> 💡 Tip: You can run the `pipecatcloud` CLI using the `pcc` alias.
|
|
|
|
#### Docker
|
|
|
|
Pipecat Cloud expects a built Docker image that includes the agent code and all dependencies. You need to:
|
|
|
|
1. Install [Docker](https://www.docker.com/) on your system.
|
|
2. Create a container registry account. We'll use [Docker Hub](https://hub.docker.com/) in this example.
|
|
|
|
### Configure pcc-deploy.toml
|
|
|
|
The `pcc-deploy.toml` file is the spec for your Pipecat Cloud deployment.
|
|
|
|
```ini
|
|
agent_name = "quickstart"
|
|
image = "your_username/quickstart:0.1"
|
|
secret_set = "quickstart-secrets"
|
|
|
|
[scaling]
|
|
min_agents = 1
|
|
```
|
|
|
|
Details:
|
|
|
|
- `agent_name`: the name of your Pipecat Cloud agent
|
|
- `image`: your Docker Hub username and image tag (image_name:version) to run
|
|
- `secret_set`: environment variable secrets that you can use in your bot file
|
|
- `min_agents`: the number of reserve instances you'll run. We'll start with 1 to ensure you get an instant start
|
|
|
|
> 💡 Tip: [Set up `image_credentials`](https://docs.pipecat.ai/deployment/pipecat-cloud/fundamentals/secrets#image-pull-secrets) in your TOML file for authenticated image pulls
|
|
|
|
### Configure secrets
|
|
|
|
Store your secrets in Pipecat Cloud and use the environment variable keys in your bot file. To create secrets, run:
|
|
|
|
```bash
|
|
uv run pcc secrets set quickstart-secrets --file .env
|
|
```
|
|
|
|
This command creates a new secret set called `quickstart-secrets`. This value must match the `secret_set` in your TOML file. The `--file` arg points your `.env` file. This will add all environment variables from the file to the secret set.
|
|
|
|
## Build and push your Docker image
|
|
|
|
Pipecat Cloud expects a built Docker image that includes the agent code and all dependencies. You can build, tag, and push your Docker image using the included `build.sh` shell script:
|
|
|
|
1. Login to Docker Hub:
|
|
|
|
```bash
|
|
docker login
|
|
```
|
|
|
|
2. Update the `VERSION`, `DOCKER_USERNAME`, and `AGENT_NAME` to match your TOML file.
|
|
3. Run the script:
|
|
|
|
```bash
|
|
./build.sh
|
|
```
|
|
|
|
## Deploy your agent
|
|
|
|
You're ready to deploy your agent. Use the following command to deploy your agent according to the spec in your `pcc-deploy.toml` file:
|
|
|
|
```bash
|
|
uv run pcc deploy
|
|
```
|
|
|
|
## Connect to your agent
|
|
|
|
The Pipecat Cloud dashboard has a Sandbox which makes it easy to talk to your agent. In your [Pipecat Cloud dashboard](https://pipecat.daily.co/), select your `quickstart` agent > Sandbox.
|
|
|
|
- Accept the browser prompt for device access.
|
|
- Click `Connect` to start your agent.
|
|
|
|
## Troubleshooting
|
|
|
|
- **Browser permissions**: Make sure to allow microphone access when prompted by your browser.
|
|
- **Connection issues**: If the WebRTC connection fails, first try a different browser. If that fails, make sure you don't have a VPN or firewall rules blocking traffic. WebRTC uses UDP to communicate.
|
|
- **Audio issues**: Check that your microphone and speakers are working and not muted.
|
|
|
|
## Next Steps
|
|
|
|
- **Read the docs**: Check out [Pipecat's docs](https://docs.pipecat.ai/) for guides and reference information.
|
|
- **Join Discord**: Join [Pipecat's Discord server](https://discord.gg/pipecat) to get help and learn about what others are building.
|