Pipecat Cloud continuously checks the health of each agent instance through two HTTP endpoints that the base image exposes for you: a readiness check and a liveness check. You don’t need to add these endpoints yourself — they’re built in — but you can customize the readiness check to control when an instance should receive new sessions.
The readyz() override described below is available in Pipecat Cloud base
image 0.1.14 and later.
The built-in endpoints
/readyz and /livez are reserved paths. Don’t define your own endpoints at
these paths in your agent. See Reserved
paths.How readiness affects routing
Readiness is the signal Pipecat Cloud uses to decide whether an instance should be sent new work:
- When an instance reports ready, it can be assigned new sessions from the pool.
- When an instance reports not ready, Pipecat Cloud stops routing new sessions to it. Any session already running on that instance is unaffected and continues to completion.
This makes the readiness check a clean way to take an instance out of rotation without disrupting active calls — for example, while it finishes a graceful shutdown.
Customizing the readiness check
Override the default readiness behavior by defining a readyz() function in your bot.py. It can be synchronous or asynchronous, and may return either a bool or a dict containing a ready key:
Return values map to HTTP status codes:
Use readyz() to gate on dependencies your agent needs in order to handle a
session — for example a database, a model download, or an upstream API. If a
dependency is unavailable, report not-ready so the instance isn’t handed new
sessions until it recovers.
