DeepSeek Harness Plugin: dsh-grafana-query (Read-Only Grafana Query Tool)

When developing DeepSeek Harness agents, letting an Agent read Grafana metrics and alerting status is a common requirement. Calling the Grafana API directly often involves cumbersome authentication logic, while some existing DSH plugins focus on dashboard editing (write operations). dsh-grafana-query provides a read-only solution that allows an Agent to run PromQL queries through Grafana’s datasource proxy and read unified alerting states without making any changes to the Grafana instance.

Plugin Introduction¶

Plugin name: dsh-grafana-query
Maintainer: maxmilian
License: MIT

This is an open-source DeepSeek Harness plugin focused on read-only Grafana operations. It leverages Grafana’s /api/datasources/proxy/uid/:uid/* endpoint, enabling agents to query metrics from monitoring systems such as Prometheus as if operating on a local datasource, while retrieving alerting states through the unified alerting interface.

Core Features¶

The plugin provides the following 6 tools, all read-only:

1. grafana_health
   Checks whether the Grafana instance is reachable and returns version information.
2. grafana_list_datasources
   Lists datasources, including UID, type, and access mode. This is a required step before querying.
3. grafana_query
   Runs an instant PromQL query through the datasource proxy to get the current value.
4. grafana_query_range
   Runs a range PromQL query. The plugin enforces step limits and a point budget to prevent returning too much data.
5. grafana_alert_state
   Reads the current state of unified alerting rules (such as firing, pending, and unknown).
6. grafana_list_alert_rules
   Lists configured alert rule definitions.

Installation and Enablement¶

Before installation, ensure the environment meets the following requirements:
* Node.js: 22.19 or a later version in the 22.x line, or version 24 and above.
* Grafana: 9.0 or later (only supports UID-based datasource proxy; the old numeric ID paths are not supported).

Install the plugin using Bun:

bun add dsh-grafana-query

The plugin is declared through dsh.bundle.patch in package.json, and the DeepSeek Harness registry automatically loads its default configuration.

Typical Usage¶

1. Get a Datasource UID¶

Before using query tools, you need to find the UID of the target datasource. Retrieve it by filtering datasources with the type prometheus:

{
  "type": "prometheus"
}

2. Run an Instant Query¶

Get the current value of a metric (such as up):

{
  "datasource_uid": "prom-1",
  "query": "up"
}

3. Run a Range Query (Trend)¶

Query the CPU usage trend. When the step parameter is omitted, the plugin automatically chooses a step to ensure that each series does not exceed the default maximum number of points.

{
  "datasource_uid": "prom-1",
  "query": "rate(node_cpu_seconds_total[5m])",
  "start": "2026-09-29T00:00:00Z",
  "end": "2026-09-30T00:00:00Z"
}

4. View Alerting State¶

Call it without arguments to view currently firing alert rules:

{}

Configuration and Permissions¶

Environment Variable Configuration¶

The plugin relies on environment variables for configuration, which has lower priority than explicit in-code configuration:

export GRAFANA_URL='https://grafana.example.com'
export GRAFANA_TOKEN='glsa_your_service_account_token'

Permission Requirements¶

This plugin requires specific Grafana permissions to work correctly. It is recommended to use a Grafana service account token (glsa_ prefix).

Required permissions:
* datasources:read: for listing datasources and querying metadata.
* datasources:query: for executing PromQL queries.
* alert.rules:read: for reading alerting states.
* alert.provisioning:read: for listing alert rule definitions.

Recommended permissions setup:
When creating a service account in Grafana, it is recommended to combine the following roles:
1. Basic role: Viewer (covers datasources:read and datasources:query).
2. Fixed role: Alerting → Full read-only access (covers alert.rules:read and alert.provisioning:read).

Note: Do not use Grafana Cloud Access Policy tokens (glc_). They only apply to cloud data endpoints and do not support this API.

Limitations and Behavior¶

The plugin enforces multiple client-side limits to prevent performance issues caused by returning too much data:

• Point limit: the default max_points is 200, with a maximum of 500. The point count formula for grafana_query_range is floor(n / s) + 1.
• Series limit: the default maxSeries is 100.
• Response size: the default maxResponseBytes is 5MB.
• Time range: the maximum duration for grafana_query_range is 31 days.
• Security policy: error messages never include tokens, request headers, or raw response bodies. Only when Prometheus returns HTTP 400 is a structured error field passed to the Agent, with a maximum length of 200 characters.
• Read-only principle: version 0.1 never creates, edits, deletes, silences, acknowledges, or pauses anything in Grafana.

Use Cases and Caveats¶

• Use cases: building monitoring dashboards, automated agent inspections, and metrics-driven automated operations decisions.
• Note: This plugin is functionally opposite to dsh-grafana (which is responsible for editing dashboard JSON). The plugin introduced in this document is only for querying and does not involve reading or writing dashboard definitions.

Conclusion¶

dsh-grafana-query provides standardized Grafana read-only access for DeepSeek Harness, reducing the integration cost between agents and monitoring systems. Through strict permission controls and limitation policies, it allows Agents to obtain the necessary monitoring data while ensuring security.

• Plugin directory: dsh-grafana-query
• Source code: GitHub