Skip to main content
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.

​
What readiness does not do

Reporting not-ready takes an instance out of rotation. It does not replace it. Pipecat Cloud does not start a fresh instance to stand in for one that reports not-ready, and the instance does not restart itself. Its process keeps running with whatever state it already had. So readyz() is not a way to recycle an instance. If your agent needs a fresh process, for example to clear memory it could not release, reporting not-ready will not give you one. There is no per-instance recycle setting today. Instances are replaced when you deploy again, which discards instances created before that deployment. See Instance reuse and memory for what carries over when an instance serves another session.

​
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.