Skip to main content

​
Deploying an agent

Deploy your agent to Pipecat Cloud with a single command: 
pipecat cloud deploy
The CLI builds your image in the cloud from your project’s Dockerfile and deploys it - no container registry setup needed. For more details on how cloud builds work, see the Cloud Builds guide.

​
Deploying to a specific region

Agents deploy to your organization’s default region, which is us-west by default. You can deploy to a specific region to reduce latency or meet data residency requirements: 
pipecat cloud deploy --region us-east
Agent names are globally unique across all regions. For multi-region deployments, deploy uniquely named agents to each target region (e.g., my-agent-us-west, my-agent-us-east).
Once the deployment completes, you will be able to run your agent on-demand. For a complete list of deployment configuration options, see the CLI deploy reference.

​
Deploying with a custom image

If you prefer to build and push images to your own container registry, you can specify an image directly: 
pipecat cloud deploy my-agent my-image:0.1
Using a private container registry? See our Container Registry guides for setup instructions for GCP Artifact Registry, AWS ECR, and other private registries.
You will be asked to confirm your deployment configuration before proceeding.

​
Deployment status

Once complete, Pipecat Cloud will return the status of your deployment or any errors that occurred during the deployment process.

​
Using pcc-deploy.toml

To support shareable deployment configurations, you can create a pcc-deploy.toml file in the root of your project (adjacent to where you run your CLI commands.) The CLI will automatically detect this file and use it to populate the deployment configuration. Any CLI arguments you provide will override the values in the pcc-deploy.toml file. An example pcc-deploy.toml file might look like this: 
agent_name = "my-agent"
secret_set = "my-agent-secrets"
agent_profile = "agent-1x"
region = "us-west"

[scaling]
    min_agents = 1
If you’re deploying with a custom image, add the image field (and image_credentials for private registries): 
agent_name = "my-agent"
image = "your-docker-repository/my-agent:0.1"
image_credentials = "dockerhub-access"
secret_set = "my-agent-secrets"
For a complete reference of all configuration options, see the deploy command documentation.

​
Agent Profiles

Agent profiles determine the CPU and memory resources allocated to your deployed agents. Choose the profile that best matches your agent’s requirements:
  • agent-1x (default): 0.5 vCPU and 1 GB of memory. Best for voice agents.
  • agent-2x: 1 vCPU and 2 GB of memory. Well suited for voice and video agents or voice agents requiring extra processing.
  • agent-3x: 1.5 vCPU and 3 GB of memory. Best for voice and video agents requiring extra processing or multiple video inputs.
You can specify the agent profile in your deployment: Via CLI: 
pipecat cloud deploy --profile agent-2x
Via pcc-deploy.toml: 
agent_profile = "agent-2x"
Agent profiles affect resource allocation and impact your usage costs. Choose the smallest profile that meets your agent’s performance requirements.

​
Checking status of a deployment

You can check the status of a deployment using the CLI: 
pipecat cloud agent status my-first-agent
If a deployment was successful and ready to be started, you should see a ready status.

​
Modifying a deployment

Agents are referenced as a mutable manifest in Pipecat Cloud. Pushing a new image or configuration to the same agent name will update your agent manifest and be used for any new requests. 
pipecat cloud deploy --min-agents 2
This command will update the deployment to set the minimum number of instances to 2. To avoid interruption of any active sessions, any running agent instances will continue on the old image until the session concludes. Once those sessions end, the instances running the old image are discarded and will not be returned to the pool.
When there is no new deployment, instances are returned to the pool after a session ends and remain available to serve new sessions during a cooldown period. A new deployment changes this behavior: instances running the prior image are terminated once their sessions conclude, rather than being recycled.
Idle agent instances in your agent pool will be replaced with the new configuration according to the Pipecat Cloud auto-scaling strategy. New agent requests may, therefore, start with prior deployment configuration if updates are not fully propagated. This ensures on-demand availability remains consistent and avoids potential cold starts.

​
Failed deployments

If a deployment fails (i.e. fails to enter a ready state), requests will be routed to any prior deployments in a ready state. This ensures that your agent remains available to end-users even when a deployment fails.

​
Delete a deployment

This action is irreversible and will remove all data related to the agent from Pipecat Cloud.
If you no longer need a deployment, you can delete it using the delete command: 
pipecat cloud agent delete my-first-agent
Any running agent instances will continue to run until they conclude or are stopped.