pipecat/examples/quickstart

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 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 for Speech-to-Text transcriptions
• OpenAI for LLM inference
• Cartesia 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:

uv sync --extra webrtc \
    --extra daily \
    --extra silero \
    --extra deepgram \
    --extra openai \
    --extra cartesia \
    --extra runner

Configure environment variables

Create a .env file:

cp env.example .env

Then, add your API keys:

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

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

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 on your system.
2. Create a container registry account. We'll use Docker Hub in this example.

Configure pcc-deploy.toml

The pcc-deploy.toml file is the spec for your Pipecat Cloud deployment.

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

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:

   docker login
   

2. Update the VERSION, DOCKER_USERNAME, and AGENT_NAME to match your TOML file.

3. Run the script:

   ./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:

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, 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 for guides and reference information.
• Join Discord: Join Pipecat's Discord server to get help and learn about what others are building.