[tofarr]

Overview

This PR adds server health monitoring and operational endpoints to the OpenHands Agent Server, along with improved API documentation and examples.

Changes Made

🏥 Server Health & Monitoring

• New Router: Added server_details_router.py with health monitoring endpoints:
  • GET /alive - Simple alive check returning {"status": "ok"}
  • GET /health - Health check endpoint returning "OK"
  • GET /server_info - Detailed server information including uptime and idle time
• Activity Tracking: Integrated activity tracking that updates last execution time when events occur
• Server Metrics: Tracks server uptime and idle time since last agent activity

📚 API Documentation Improvements

• Enhanced FastAPI Metadata: Updated API title to "OpenHands Agent Server" with comprehensive description
• Endpoint Documentation: Added detailed docstrings to all conversation endpoints
• Request Examples: Added comprehensive examples for StartConversationRequest including:
  • LLM configuration with model and API key
  • Tool specifications (BashTool, FileEditor, TaskTracker)
  • Sample initial message

🔧 API Enhancements

• Improved Descriptions: Updated endpoint descriptions to be more user-friendly:
  • Removed "local" references for broader applicability
  • Added clear descriptions for pause/resume/delete operations
• Better Request Handling: Enhanced request body handling with examples in OpenAPI documentation

Technical Details

Files Modified

• openhands/agent_server/api.py - Added server details router and enhanced API metadata
• openhands/agent_server/conversation_router.py - Added documentation, examples, and improved descriptions
• openhands/agent_server/conversation_service.py - Integrated activity tracking
• openhands/agent_server/server_details_router.py - New file with health monitoring endpoints

New Endpoints

GET /alive        - Basic alive check
GET /health       - Health status
GET /server_info  - Server uptime and idle time metrics

Benefits

1. Operational Monitoring: Enables monitoring of server health and activity
2. Better Documentation: Improved API documentation with examples makes integration easier
3. Production Readiness: Health endpoints support deployment monitoring and load balancer health checks
4. Developer Experience: Clear examples and documentation improve SDK usability

Testing

The changes maintain backward compatibility and add new functionality without breaking existing endpoints. The health endpoints provide simple, reliable monitoring capabilities for production deployments.

[github-actions]

Agent Server image for this PR

Pull (multi-arch manifest):

docker pull ghcr.io/all-hands-ai/agent-server:ee1ad69

Run:

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-ee1ad69 \
  ghcr.io/all-hands-ai/agent-server:ee1ad69

This tag is a multi-arch manifest (amd64/arm64). Your client pulls the right arch automatically.

[xingyaoww]

We still have a lot to change from tool serialization side (#350)

I think this PR should wait until we finalize those

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Pre-commit checks
  • Agent Server

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #362 at branch `server-details`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}