k6 for coding agents

If a coding agent has shell access to your codebase, it can use k6 to send scripted requests to an API and check the responses. k6 is a load-testing tool: it sends requests that imitate a chosen pattern of traffic, then reports metrics such as request duration and failures. The one-request example below checks basic behavior, but it does not show how the service handles heavy traffic.

An agent can write and run a k6 script on your machine, then inspect the results with the same command-line interface (CLI) a developer uses. Grafana also documents an optional agent setup and a k6 Model Context Protocol (MCP) server, which is in preview. Compatible assistants can use the server to access k6 guidance and run tests through a defined interface. You do not need this integration for the shell-based example.

Install k6

On macOS with Homebrew, install k6 and check that the command is available:

brew install k6
k6 version

For other operating systems, follow the official k6 installation instructions. A local k6 run does not require a Grafana account. The example below makes a network request to a public test site, but it does not authenticate to Grafana or change the site.

Grafana documents k6 x agent for bootstrapping editor integrations and portable agent skills. It also documents k6 x mcp for starting the k6 MCP server. Grafana’s documentation says the server is currently in preview. It also warns that the server's HTTP transport has no built-in authentication, so do not expose it on a public network. By default the server uses the stdio transport instead. The AI assistant setup documentation describes these options.

Run a one-request check

Ask an agent to create a file named api-check.js with this script:

import http from 'k6/http';
import { check } from 'k6';

export const options = {
  vus: 1,
  iterations: 1,
};

export default function () {
  const response = http.get('https://quickpizza.grafana.com');

  check(response, {
    'status is 200': (res) => res.status === 200,
  });
}

The script sends one HTTP GET request, which asks the server for a resource, then checks whether the server answered with status 200. A virtual user, or VU, is a simulated user that runs the script. Here, one VU runs one iteration, so the test makes one request. The URL points to QuickPizza, the public demo site that the k6 getting started guide uses. When checking your own API, replace it with an endpoint you are authorized to test.

Run the script and save a JSON summary:

k6 run --vus 1 --iterations 1 --summary-export=summary.json api-check.js

The command sends a request over the network and writes summary.json on your machine. k6 also prints a summary in the terminal, including metrics for requests and checks. The summary file contains metrics from the end of the test, not a separate record for every measurement. Check results show whether the assertion passed, but they do not show that the service can handle production traffic. The k6 options reference says --summary-export still works but is discouraged. For a custom summary file, it points to the handleSummary() function.

To save each metric sample in a JSON stream as k6 produces it, add --out json=results.ndjson to the command. The JSON output documentation describes this format, which has one JSON object per line. This output is useful when another local tool needs to process the measurements. It differs from --summary-export, which saves the final summary.

Give the agent a narrow task

A useful prompt names the endpoint, the request the agent may send, and the result you want it to check:

Create api-check.js with a one-iteration k6 GET check for https://quickpizza.grafana.com. Run it with one VU, save the summary to summary.json, and report whether the response check passed. Do not increase the request count or add other endpoints.

The agent writes the script and runs k6 locally; k6 contacts the named endpoint. Review the URL and request before running the script against a real service. If an API requires credentials, provide them through your usual local secret or environment configuration, not in the agent prompt or script.

For larger tests, ask the agent to describe the workload and thresholds before it runs requests. A test that sends sustained or concurrent traffic can affect the target service. You should review the assumptions and interpret the results before using them to make performance or release decisions.