feat(server): add health check endpoint with tests by OhYee · Pull Request #64 · Serverless-Devs/agentrun-sdk-python

OhYee · 2026-03-09T04:22:15Z

Add /health endpoint to server for health checking and monitoring. Include comprehensive tests covering GET requests, method restrictions, and compatibility with custom protocols.

Added _register_health_check method to AgentRunServer that registers a /health route returning {"status": "ok"} for GET requests while ensuring other methods are properly restricted.

添加用于健康检查和监控的 /health 端点。
包括涵盖 GET 请求、方法限制和自定义协议兼容性的全面测试。

在 AgentRunServer 中添加 _register_health_check 方法，该方法注册一个 /health 路由，对 GET 请求返回 {"status": "ok"}，同时
确保其他方法被正确限制。

Change-Id: I7718d675242179379935b81f6e323a2942d71bd8

Thank you for creating a pull request to contribute to Serverless Devs agentrun-sdk-python code! Before you open the request please answer the following questions to help it be more easily integrated. Please check the boxes "[ ]" with "[x]" when done too.
Please select one of the PR types below to complete

Fix bugs

Bug detail

The specific manifestation of the bug or the associated issue.

Pull request tasks

Add test cases for the changes
Passed the CI test

Update docs

Reason for update

Why do you need to update your documentation?

Pull request tasks

Update Chinese documentation
Update English documentation

Add contributor

Contributed content

Code
Document

Content detail

if content_type == 'code' || content_type == 'document':
    please tell us `PR url`，like: https://github.com/Serverless-Devs/agentrun-sdk-python/pull/1
else:
    please describe your contribution in detail

Others

Reason for update

Why do you need to update your documentation?

Add /health endpoint to server for health checking and monitoring. Include comprehensive tests covering GET requests, method restrictions, and compatibility with custom protocols. Added _register_health_check method to AgentRunServer that registers a /health route returning {"status": "ok"} for GET requests while ensuring other methods are properly restricted. 添加用于健康检查和监控的 /health 端点。包括涵盖 GET 请求、方法限制和自定义协议兼容性的全面测试。在 AgentRunServer 中添加 _register_health_check 方法，该方法注册一个 /health 路由，对 GET 请求返回 {"status": "ok"}，同时确保其他方法被正确限制。 Change-Id: I7718d675242179379935b81f6e323a2942d71bd8 Signed-off-by: OhYee <oyohyee@oyohyee.com>

Copilot

Pull request overview

Adds a root-level health check endpoint to AgentRunServer intended for monitoring and validates it via unit tests.

Changes:

Register GET /health on the main FastAPI app to return {"status": "ok"}.
Add unit tests covering /health success, method restriction (POST → 405), and availability when custom protocols are provided.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
`agentrun/server/server.py`	Registers a server-level `GET /health` route during server initialization.
`tests/unittests/server/test_server.py`	Adds tests verifying the new `/health` endpoint behavior and custom-protocol compatibility.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-09T04:25:08Z

agentrun/server/server.py

+        """注册 /health 健康检查路由 / Register /health health check route"""
+


AgentRunServer now always registers a root GET /health route. Note that AGUIProtocolHandler already defines GET /health on its router; if the AG-UI prefix is configured to an empty string (or a custom protocol mounts at root with the same path), the protocol’s /health will be shadowed by the server-level route, leading to ambiguous/unreachable behavior depending on route order. Consider guarding registration (skip if an existing GET /health route already exists), or using a dedicated non-conflicting path (e.g. /_health) for the server-level endpoint.

Suggested change

"""注册 /health 健康检查路由 / Register /health health check route"""

"""注册 /health 健康检查路由 / Register /health health check route

如果应用中已经存在 GET /health 路由（例如协议自身定义了该路由），

则不会重复注册，以避免路由冲突或被覆盖。

"""

# Check if a GET /health route already exists to avoid conflicts

for route in getattr(self.app, "routes", []):

path = getattr(route, "path", None)

methods = getattr(route, "methods", None)

if path == "/health" and methods and "GET" in methods:

logger.warning(

"Skipping registration of server-level GET /health route "

"because an existing GET /health route was found."

)

return

Copilot · 2026-03-09T04:25:09Z

tests/unittests/server/test_server.py

+        """测试自定义协议列表时 /health 仍可用"""
+        from agentrun.server.openai_protocol import OpenAIProtocolHandler
+
+        server = AgentRunServer(
+            invoke_agent=self.get_invoke_agent_non_streaming(),
+            protocols=[OpenAIProtocolHandler()],
+        )


This test imports OpenAIProtocolHandler from the internal module path (agentrun.server.openai_protocol). Elsewhere in the test suite it’s imported from the public agentrun.server package exports; using the internal path makes the test more brittle to refactors. Prefer from agentrun.server import OpenAIProtocolHandler here for consistency and stability.

The health check endpoint was removed from the AGUI protocol handler as it's no longer needed. All related test cases have been updated to reflect the new health check location at the root path. BREAKING CHANGE: The /ag-ui/agent/health endpoint has been removed and health checks are now available at /health 移除 AGUI 协议的健康检查端点并更新测试 AGUI 协议处理器中的健康检查端点已被移除，因为它不再需要。所有相关测试用例都已更新以反映新健康检查位置在根路径。重大变更：/ag-ui/agent/health 端点已被移除，健康检查现在可在 /health 路径获取 Change-Id: I7afd3abc03a90ec0e9ab989529197b6ce158ba76 Signed-off-by: OhYee <oyohyee@oyohyee.com>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-09T06:17:16Z

agentrun/server/agui_protocol.py

                    media_type=self._encoder.get_content_type(),
                    headers=sse_headers,
                )

-        @router.get("/health")
-        async def health_check():
-            """健康检查端点"""
-            return {"status": "ok", "protocol": "ag-ui", "version": "1.0"}
-
        return router


This change removes the AG-UI protocol-specific health endpoint (previously available at the mounted prefix, e.g. "/ag-ui/agent/health"). If any users or internal tooling rely on that path, this is a breaking API change; consider keeping it as an alias (returning the same payload as /health, or a deprecation response) while also adding the new top-level /health endpoint.

OhYee requested a review from Copilot March 9, 2026 04:22

Copilot started reviewing on behalf of OhYee March 9, 2026 04:22 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

OhYee requested a review from Copilot March 9, 2026 06:13

Copilot started reviewing on behalf of OhYee March 9, 2026 06:14 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

OhYee merged commit 3b8ea78 into main Mar 9, 2026
6 checks passed

OhYee deleted the feat-default-health-api branch March 9, 2026 06:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(server): add health check endpoint with tests#64

feat(server): add health check endpoint with tests#64
OhYee merged 2 commits intomainfrom
feat-default-health-api

OhYee commented Mar 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		"""注册 /health 健康检查路由 / Register /health health check route"""

-        """注册 /health 健康检查路由 / Register /health health check route"""
+        """注册 /health 健康检查路由 / Register /health health check route
+        如果应用中已经存在 GET /health 路由（例如协议自身定义了该路由），
+        则不会重复注册，以避免路由冲突或被覆盖。
+        """
+        # Check if a GET /health route already exists to avoid conflicts
+        for route in getattr(self.app, "routes", []):
+            path = getattr(route, "path", None)
+            methods = getattr(route, "methods", None)
+            if path == "/health" and methods and "GET" in methods:
+                logger.warning(
+                    "Skipping registration of server-level GET /health route "
+                    "because an existing GET /health route was found."
+                )
+                return

Conversation

OhYee commented Mar 9, 2026

Fix bugs

Update docs

Add contributor

Others

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants