---
title: "Build workflows with an AI agent | Grafana Cloud documentation"
description: "Describe a workflow in plain language and let an AI coding agent build, validate, and test it for you with the gcx CLI."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Build workflows with an AI agent

> Note
> 
> Grafana Workflows is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

You describe what a workflow should do, and an agent writes the definition. An *AI coding agent* is an assistant that runs in your terminal and can run commands for you, such as Claude Code, Cursor, or GitHub Copilot. With the gcx command-line tool, an agent can build a workflow from your description, check it, test it, and fix it.

By the end of this scenario, you have a working workflow that you described in plain language and reviewed before you turned it on.

## Before you begin

Before you start, make sure you have:

- A Grafana Cloud stack with the Workflows app installed.
- The Editor basic role, `workflows:write`, and edit access to the folder you want to use. For details, refer to [Manage access](/docs/grafana-cloud/platform/workflows/manage-access).
- gcx installed and signed in to your stack. For details, refer to [Install gcx](/docs/grafana/latest/as-code/observability-as-code/grafana-cli/gcx/installation/) and [Configure gcx](/docs/grafana/latest/as-code/observability-as-code/grafana-cli/gcx/configuration/). To sign in with `gcx login`, you need the gcx User role. Grafana grants it to the Viewer, Editor, and Admin basic roles by default.
- An AI coding agent that can run terminal commands.

You don’t need to know the workflow definition format. The agent reads it from your stack.

## Give the agent context

An agent works better when it knows where to find Workflows information and what it’s allowed to do. Most agents read instructions from a file in your project folder, such as `AGENTS.md` or `CLAUDE.md`.

Add the following section to that file. It tells the agent where to find the building blocks and sets rules that keep your workflows safe:

Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```markdown
## Grafana Workflows

Manage Grafana Workflows with gcx. Workflows are `definitions` resources in
the `workflows.ext.grafana.app/v1alpha1` API group.

- Step types available on this stack, with inputs and outputs:
  `gcx api /api/plugins/grafana-workflows-app/resources/api/v1/types/steps`
- Trigger (event) types:
  `gcx api /api/plugins/grafana-workflows-app/resources/api/v1/types/triggers`
- Existing workflows, useful as examples: `gcx resources get definitions -o yaml`
- Folders: `gcx api /api/folders`. Every definition needs the
  `grafana.app/folder` annotation set to a folder UID.
- Expressions use CEL inside `${...}`. Event fields are under `inputs.data`,
  step outputs are under `steps['<STEP_ID>'].outputs`.
- Runs started through the API don't load the incident automatically. Declare
  it with `spec.resources.incidents.event: "incident://id/${inputs.data.incidentID}"`.

Rules:

- Write new workflows to `./workflows/` with `enabled: false`.
- Validate with `gcx resources push -p ./workflows --dry-run --assume-server-dry-run definitions.workflows.ext.grafana.app`.
- Test with the `trigger` endpoint before enabling, and show me each step's output.
- Ask me before you enable a workflow, delete one, or run a step that sends
  messages, pages people, or changes incidents.
```

gcx also includes Agent Skills, which are instruction files that teach an agent how to use gcx. How you install them depends on your agent.

For Claude Code, the skills come in the gcx plugin. To add the plugin, run the following commands in Claude Code:

text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```text
/plugin marketplace add grafana/gcx
/plugin install gcx@gcx-marketplace
```

If your agent reads skills from an `.agents` directory, for example, OpenAI Codex, install the skill that helps an agent set up gcx. Run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx agent skills install setup-gcx
```

## Describe the workflow

Tell the agent what you want in plain language. Include what should start the workflow, what it should do, which folder it belongs in, and how to test it.

The following example asks for an incident workflow:

text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```text
Create a Grafana workflow that runs when a new incident is created in IRM.
It should post a message to the Slack channel C0123456789 with the incident
title, severity, and a link to the incident. Put it in the "Incident
automation" folder. Test it against incident 56 before you enable it.
```

## Follow the agent’s work

The agent works through five stages. At each stage, it tells you what it found or changed. Your job is to check the result and answer its questions.

### Discover the building blocks

The agent reads the step types and triggers available on your stack, and finds the folder you named. For this example, it looks up the inputs of the Slack message step:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx api /api/plugins/grafana-workflows-app/resources/api/v1/types/steps \
  --jq '.items[] | select(.spec.type == "slack.message.post") | .spec'
```

**What to check:** The agent names the steps and trigger it plans to use. If a step you expect is missing, your stack might not offer it.

### Draft the definition

The agent writes a workflow file with `enabled: false`, so the workflow can’t start on its own. For this example, it writes `workflows/new-incident-slack.yaml`:

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
apiVersion: workflows.ext.grafana.app/v1alpha1
kind: Definition
metadata:
  name: new-incident-slack
  annotations:
    grafana.app/folder: <FOLDER_UID>
spec:
  name: Announce new incidents in Slack
  enabled: false
  startWhen:
    matchingRules:
      - eventNameRegex: grafana_irm_app\.incident\.updated
        filter: "inputs.data.eventKind == 'incident_created'"
    schedules: []
  resources:
    incidents:
      event: "incident://id/${inputs.data.incidentID}"
  steps:
    - id: announce
      name: Post to Slack
      type: slack.message.post
      inputs:
        channelID: C0123456789
        messageText: |
          :rotating_light: *${resources.incident.event.title}*
          Severity: ${resources.incident.event.severity}
          ${resources.incident.event.overviewURL}
```

**What to check:** Read the file. The trigger, the Slack channel, and the message should match what you asked for.

### Validate the draft

The agent asks Workflows to check the file without saving it. If Workflows reports a problem, the agent fixes the file and checks again:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx resources push -p ./workflows --dry-run \
  --assume-server-dry-run definitions.workflows.ext.grafana.app
```

When the check passes, the agent saves the draft to your stack with `gcx resources push -p ./workflows`.

**What to check:** The agent reports that validation passed.

### Test the draft

The agent runs the draft once against the incident you named, then reads the output of each step. A test run doesn’t turn on the workflow’s trigger.

**What to check:** The agent shows you each step’s result. For this example, look for the test message in the Slack channel.

### Turn on the workflow

When the test results match what you expect, tell the agent to turn on the workflow. It sets `enabled: true` and saves the workflow again.

## Verify the outcome

You’re done when the following are true:

- The workflow appears in the Workflows app. To find it, open the app and go to **Manage workflows**.
- The test run’s steps all completed, and the result matched what you asked for.
- You turned on the workflow, so its definition shows `enabled: true`.

## Try other requests

You can also ask an agent to fix or review workflows you already have.

### Debug a failing workflow

The following prompt asks the agent to find and fix a failure:

text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```text
My "new-incident-slack" workflow failed a few times today. Find out why,
propose a fix, and show me the diff before you push anything.
```

The agent lists the workflow’s failed runs, reads the error from the step that failed, and edits the file. For example, the error `CEL evaluation error: no such key: incident` means the workflow tried to read an incident it didn’t load. The agent validates the fix and shows you the change before it saves anything.

### Review many workflows

The following prompt asks the agent to report on every workflow without changing anything:

text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```text
List every enabled workflow that posts to Slack, and tell me which channel
each one uses. Don't change anything.
```

To change many workflows at once, ask the agent to save them to files, edit the files, and show you the changes before it saves them back.

## Keep agent sessions safe

Workflows take real actions, such as posting to Slack, paging people, and changing incidents. Follow these guidelines when an agent works on your workflows:

- Have the agent create workflows turned off, and turn them on yourself or after you approve.
- Test with a single test run before you turn a workflow on.
- Send test messages to a test Slack channel, not a production channel.
- Keep workflow files in version control, such as Git, so you can review every change and roll it back.
- Sign gcx in with an account that can edit only the folders the agent should change.

## Next steps

- [Use gcx](/docs/grafana-cloud/platform/workflows/as-code/use-gcx)
- [Use CEL expressions](/docs/grafana-cloud/platform/workflows/use-expressions)
- [Step and trigger types reference](/docs/grafana-cloud/platform/workflows/reference)