Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Python AgentServer health check (GET /) returns 200 before the worker has registered with LiveKit

Cerrado
  • ¿Algo no está bien?
#8,092 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Ya se ha fusionado un pull request relacionado.

  • #8093 de @ninglinLiu — fusionado
  • #8119 de @zichen0116 — cerrado sin fusionar

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
35/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
python
Área
api, backend

Línea de trabajo

Start in worker.py at the health handler and connection state described in the issue; compare the Python behavior with the Node SDK's connection check. Run the supplied reproduction to confirm the response before registration, then verify the chosen health or readiness behavior during registration and reconnection. Done means the endpoint behavior matches its documented purpose, including the existing unregistered=True mode; an open linked pull request already addresses this issue.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Bug Description

The built-in health endpoint returns 200 OK after its HTTP server starts, even before the worker receives RegisterWorkerResponse and registers with LiveKit. I reproduced this with livekit-agents==1.8.8 and with main at 7e824e3637b06198176c4cd619489134ce51d2bb.

The Server options documentation says the endpoint returns 200 when connected and 503 when the server is not connected, and notes that LiveKit Cloud uses it for rolling deployments. In worker.py, the health handler checks only whether the inference process is alive and whether _connection_failed is true. _connection_failed starts as False and becomes True only after the retry limit is exhausted. The HTTP server starts before the connection task. _connecting is tracked but is not checked by the health handler.

Expected Behavior

Before receiving RegisterWorkerResponse, GET / should indicate that the worker is not yet connected, consistent with the documentation. If / is intended to be a liveness check that remains healthy during reconnection, could a separate readiness endpoint be provided and documented? The Node SDK returns 503 while connecting or while its WebSocket is not open.

Reproduction Steps
  1. Run the script below in an environment with the package versions listed under Package Versions.
  2. The fake LiveKit endpoint accepts the worker's WebSocket and reads its registration message, but deliberately never sends RegisterWorkerResponse.
  3. Observe that worker_registered is still false while GET / returns 200.
import asyncio
import aiohttp
from aiohttp import web
from livekit.agents import AgentServer, JobContext, __version__

FAKE_PORT, HEALTH_PORT = 18880, 18881


async def main() -> None:
    register_requests = 0

    async def agent_ws(request: web.Request) -> web.WebSocketResponse:
        nonlocal register_requests
        ws = web.WebSocketResponse()
        await ws.prepare(request)
        async for _ in ws:  # read RegisterWorkerRequest, never send RegisterWorkerResponse
            register_requests += 1
        return ws

    app = web.Application()
    app.router.add_get("/agent", agent_ws)
    runner = web.AppRunner(app)
    await runner.setup()
    await web.TCPSite(runner, "127.0.0.1", FAKE_PORT).start()

    server = AgentServer(
        ws_url=f"ws://127.0.0.1:{FAKE_PORT}", api_key="devkey", api_secret="secret" * 6,
        host="127.0.0.1", port=HEALTH_PORT, num_idle_processes=0,
    )

    @server.rtc_session()
    async def entrypoint(ctx: JobContext) -> None: ...

    registered = asyncio.Event()
    server.on("worker_registered", lambda *_: registered.set())
    run_task = asyncio.create_task(server.run(devmode=False))
    await asyncio.sleep(5)

    async with aiohttp.ClientSession() as http:
        async with http.get(f"http://127.0.0.1:{HEALTH_PORT}/") as resp:
            print(f"livekit-agents {__version__}: register_requests={register_requests} "
                  f"worker_registered={registered.is_set()} GET / -> {resp.status} {await resp.text()!r}")

    await server.aclose()
    run_task.cancel()
    await runner.cleanup()

asyncio.run(main())

Output on both tested versions:

livekit-agents 1.8.8: register_requests=1 worker_registered=False GET / -> 200 'OK'
Operating System

macOS 27.0.1, arm64.

Models Used

Not applicable; this reproduction tests worker registration only and does not use STT, LLM, or TTS models.

Package Versions
Python 3.12.13

Release test:
livekit-agents==1.8.8
livekit==1.1.20
livekit-api==1.2.2
aiohttp==3.14.5

main @ 7e824e3637b06198176c4cd619489134ce51d2bb:
livekit-agents==1.8.8
livekit==1.1.21
livekit-api==1.2.2
aiohttp==3.14.5
Session/Room/Call IDs

Not applicable; this uses a local fake LiveKit endpoint and does not create a LiveKit Cloud session or room.

Proposed Solution

Return 503 while the worker is not registered, for example while _connecting is true or using a registered state that is cleared on disconnect. Preserve the existing behavior for unregistered=True mode. If / is intended to be a liveness check so short LiveKit outages do not restart workers with active jobs, could you add a separate readiness endpoint and update the docs? I can open a PR for either option.

Additional Context
  • The same health-check code is present in 1.8.2, 1.8.8, and the tested main revision.
  • The Node SDK checks connection state and returns 503 while connecting or while the socket is not open (agents-js change).
  • Related: #4419 reports failure after retries are exhausted, but does not cover the initial registration gap. #6918 proposes moving the existing checks into agent_health(), which appears to retain the same gap.
Lenguaje dominante
Python
Estrellas
14.6k
Forks
3.9k
Merge medio
2 d 7 h
PR fusionados (30 d)
228

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de livekit/agents

Todos los issues de livekit/agents

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.