语音AI机器人开发平台

Pipecat Quickstart

Build and deploy your first voice AI bot in under 10 minutes. Develop locally, then scale to production on Pipecat Cloud.

Two steps: 🏠 Local Development → ☁️ Production Deployment

Step 1: Local Development (5 min)

Prerequisites

Environment

• Python 3.10 or later
• uv package manager installed

AI Service API keys

You'll need API keys from these services:

• Deepgram for Speech-to-Text
• Anthropic for LLM inference (Claude 3.7 Sonnet)
• Cartesia for Text-to-Speech
• OpenAI (optional) — included in .env for experimentation but not used by the default bot.

💡 Tip: Sign up for all three now. You'll need them for both local and cloud deployment.

Desktop Commander (MCP tools)

Desktop Commander powers the MCP tools the bot expects. Make sure you have Node.js installed, then start the server in another terminal before launching the bot:

npx -y @wonderwhy-er/desktop-commander@latest --no-onboarding

Leave that process running; you should see JSON-RPC logs showing that the tools are available.

Setup

Navigate to the quickstart directory and set up your environment.

1. Clone this repository

   复制

   git clone https://github.com/pipecat-ai/pipecat-quickstart.git
   cd pipecat-quickstart
   

2. Configure your API keys:

   Create a .env file:

   复制

   cp env.example .env
   

   Then, add your API keys:

   复制

   DEEPGRAM_API_KEY=your_deepgram_api_key
   CARTESIA_API_KEY=your_cartesia_api_key
   ANTHROPIC_API_KEY=your_claude_api_key
   OPENAI_API_KEY=optional_openai_api_key
   

3. Set up a virtual environment and install dependencies

   复制

   uv sync
   

Run your bot locally

uv run bot.py --transport webrtc

You can omit --transport webrtc to fall back to the Daily transport, but the WebRTC option matches the default browser demo at http://localhost:7860.

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.

Customize the system prompt

The bot now reads its persona from prompts/prompt.txt. Update that file to tweak tone, tool usage guidelines, or instructions without touching bot.py. If the file is missing, the bot falls back to a lightweight friendly-assistant prompt so development can continue.

🎉 Success! Your bot is running locally. Now let's deploy it to production so others can use it.

Step 2: Deploy to Production (5 min)

Transform your local bot into a production-ready service. Pipecat Cloud handles scaling, monitoring, and global deployment.

Prerequisites

1. Sign up for Pipecat Cloud.

2. Set up Docker for building your bot image:

   • Install Docker on your system

   • Create a Docker Hub account

   • Login to Docker Hub:

     复制

     docker login
     

3. Install the Pipecat CLI

   复制

   uv tool install pipecat-ai-cli
   

   Tip: You can run the pipecat CLI using the pc alias.

Configure your deployment

The pcc-deploy.toml file tells Pipecat Cloud how to run your bot. Update the image field with your Docker Hub username by editing pcc-deploy.toml.

agent_name = "quickstart"
image = "YOUR_DOCKERHUB_USERNAME/quickstart:0.1"  # 👈 Update this line
secret_set = "quickstart-secrets"

[scaling]
	min_agents = 1

Understanding the TOML file settings:

• agent_name: Your bot's name in Pipecat Cloud
• image: The Docker image to deploy (format: username/image:version)
• secret_set: Where your API keys are stored securely
• min_agents: Number of bot instances to keep ready (1 = instant start)

💡 Tip: Set up image_credentials in your TOML file for authenticated image pulls

Log in to Pipecat Cloud

To start using the CLI, authenticate to Pipecat Cloud:

pipecat cloud auth login

You'll be presented with a link that you can click to authenticate your client.

Configure secrets

Upload your API keys to Pipecat Cloud's secure storage:

pipecat cloud secrets set quickstart-secrets --file .env

This creates a secret set called quickstart-secrets (matching your TOML file) and uploads all your API keys from .env.

Build and deploy

Build your Docker image and push to Docker Hub:

pipecat cloud docker build-push

Deploy to Pipecat Cloud:

pipecat cloud deploy

Connect to your agent

1. Open your Pipecat Cloud dashboard
2. Select your quickstart agent → Sandbox
3. Allow microphone access and click Connect

What's Next?

🔧 Customize your bot: Modify bot.py to change personality, add functions, or integrate with your data
📚 Learn more: Check out Pipecat's docs for advanced features
💬 Get help: Join Pipecat's Discord to connect with the community

Troubleshooting

• Browser permissions: Allow microphone access when prompted
• Connection issues: Try a different browser or check VPN/firewall settings
• Audio issues: Verify microphone and speakers are working and not muted