BotStatusService: Monitor FrostAgent Health in Real Time

BotStatusService is a ConnectRPC service that exposes real-time health and operational data for a running FrostAgent instance. It is accessible under the base path /frostagent.v1.BotStatusService/ and provides two RPCs: GetOverview for a snapshot of the bot’s current state, and GetSessions for a paginated list of active conversation sessions.

Connection

ConnectRPC services use HTTP POST with either Content-Type: application/json (for JSON encoding) or Content-Type: application/proto (for binary protobuf). The default base URL is http://<host>:8080, configured via the LISTEN_ADDR environment variable.

# Example: call GetOverview with JSON encoding
curl -X POST http://localhost:8080/frostagent.v1.BotStatusService/GetOverview \
  -H "Content-Type: application/json" \
  -d '{}'

GetOverview

Returns a point-in-time snapshot of the bot’s status, including uptime, model in use, registered tools, and session count. The status field reflects whether the engine has finished initialising. Request: GetOverviewRequest This message has no fields — send an empty JSON object {}. Response: GetOverviewResponse

bot_name

string

The name of the agent. Always "FrostAgent" in the current release.

version

string

The running binary version string, e.g. "0.1.0".

uptime_seconds

int64

Seconds elapsed since the engine’s StartedAt timestamp was recorded.

total_messages_processed

int64

Cumulative count of messages the engine has processed since startup.

active_sessions

int32

Number of sessions currently held in the session manager.

current_model

string

The model name taken from the MODEL_NAME environment variable, e.g. "qwen-turbo".

status

string

Either "running" (session manager is initialised) or "initializing" (engine is still starting up).

tools

repeated ToolInfo

List of tools registered with the engine at startup.

Show ToolInfo fields

name

string

The tool’s unique identifier, e.g. "send_message" or "get_weather".

description

string

A human-readable description of what the tool does.

Example response

{
  "bot_name": "FrostAgent",
  "version": "0.1.0",
  "uptime_seconds": "3842",
  "total_messages_processed": "127",
  "active_sessions": 3,
  "current_model": "qwen-turbo",
  "status": "running",
  "tools": [
    {
      "name": "send_message",
      "description": "Sends a message to a specified target."
    },
    {
      "name": "get_weather",
      "description": "Retrieves current weather data for a given city."
    },
    {
      "name": "sub_agent",
      "description": "Delegates a sub-task to a separate agent instance."
    },
    {
      "name": "get_game_version",
      "description": "Fetches the latest game version information."
    }
  ]
}

GetSessions

Returns a paginated list of currently active conversation sessions. Sessions are created by the OneBot adapter and identified by a prefixed ID such as group_123456 or private_789. Request: GetSessionsRequest

pagination

Pagination

Controls the page of results to return.

Show Pagination fields

Response: GetSessionsResponse

sessions

repeated SessionInfo

The sessions in the requested page.

Show SessionInfo fields

session_id

string

The unique session identifier, e.g. "group_123456" or "private_789".

platform

string

Derived from the session ID prefix. One of "group", "private", or the prefix before the first underscore. Falls back to "unknown" if the ID has no underscore.

message_count

int32

Number of messages in this session’s history at the time of the call.

created_at

string

RFC 3339 timestamp of when the session was first created, e.g. "2025-06-01T09:00:00Z".

last_active

string

RFC 3339 timestamp of the most recent activity in this session.

pagination

Pagination

Pagination metadata for the response. page_token is set to the next page cursor if more results exist, or an empty string on the last page. total holds the total session count.

Example request

curl -X POST http://localhost:8080/frostagent.v1.BotStatusService/GetSessions \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": {
      "page_size": 10,
      "page_token": ""
    }
  }'

Example response

{
  "sessions": [
    {
      "session_id": "group_100001",
      "platform": "group",
      "message_count": 42,
      "created_at": "2025-06-01T08:15:30Z",
      "last_active": "2025-06-01T11:47:02Z"
    },
    {
      "session_id": "private_200042",
      "platform": "private",
      "message_count": 7,
      "created_at": "2025-06-01T10:00:00Z",
      "last_active": "2025-06-01T10:22:11Z"
    }
  ],
  "pagination": {
    "page_size": 10,
    "page_token": "",
    "total": 2
  }
}

ConnectRPC Services

HTTP Endpoints

BotStatusService: Monitor FrostAgent Health in Real Time

Connection

GetOverview

GetSessions

Build docs developers (and LLMs) love

ConnectRPC Services

HTTP Endpoints

Documentation Index

​Connection

​GetOverview

​GetSessions

Build docs developers (and LLMs) love

Connection

GetOverview

GetSessions