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

Đã đóng
  • Có gì không ổn?
#8,092 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Một pull request liên quan đã được merge.

  • #8093 của @ninglinLiu — đã merge
  • #8119 của @zichen0116 — đã đóng, không merge

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
35/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
python
Lĩnh vực
api, backend

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
Python
Star
14.6k
Fork
3.9k
Merge trung bình
2 ngày 23 giờ
Pull request đã merge (30 ngày)
258

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của livekit/agents

Tất cả issue của livekit/agents

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.