Skip to content

A workflow an assistant wrote

An AI assistant can write an Argo Workflows manifest, but it can’t tell whether it’ll run. Give it Dagweave’s MCP server and it can call dagweave_validate_workflow, which compiles a draft and returns every fault with its location.

This is one real session, start to finish. The faults, compiled YAML and responses are the checker’s actual output.

If your assistant writes Dagweave IR JSON instead of Argo YAML, have it call dagweave_list_node_types first. It lists the step types and, for a type you name, the JSON Schema of its config, so the assistant uses real field names. It needs the same workflows:read scope as the checker.

Sketch me a nightly ETL as an Argo DAG: extract, then transform, then load. Stub the containers with alpine for now. The extract step should write a row count that transform picks up, and put a region parameter on the workflow, we will need it later.

The first attempt looks like Argo YAML, but it won’t run.

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: nightly-etl-
spec:
entrypoint: main
arguments:
parameters:
- name: region
value: eu-west-1
templates:
- name: main
dag:
tasks:
- name: extract
template: extract
- name: transform
template: tranform
dependencies: [extract]
arguments:
parameters:
- name: rows
value: "{{tasks.extrac.outputs.parameters.rows}}"
- name: load
template: load
dependencies: [transfrom]
- name: extract
outputs:
parameters:
- name: rows
valueFrom:
path: /tmp/rows
container:
image: alpine:3.19
command: [sh, -c, "echo 12 > /tmp/rows"]
- name: transform
inputs:
parameters:
- name: rows
contianer:
image: alpine:3.19
command: [sh, -c, "echo transforming"]
- name: load
container:
image: alpine:3.19
command: [sh, -c, "echo loading"]

Three names are misspelt, and one key doesn’t exist in Argo.

The assistant sends the draft as a string in one tool call:

POST /api/v1/mcp HTTP/1.1
Host: api.dagweave.com
Authorization: Bearer dwk_...
Content-Type: application/json
{"jsonrpc":"2.0","id":4,"method":"tools/call",
"params":{"name":"dagweave_validate_workflow",
"arguments":{"workflow":"apiVersion: argoproj.io/v1alpha1\nkind: Workflow\n..."}}}

The answer is one text block, the same as POST /api/v1/workflows/validate returns, so a script calling the API gets the same thing. Decoded:

{
"valid": false,
"format": "argo-yaml",
"faults": [
{
"severity": "warning",
"rule": "unknown-field",
"path": "spec.templates[2].contianer",
"message": "unknown field \"contianer\" at spec.templates[2]: Argo has no such field, so whatever it was meant to configure will not happen. Did you mean \"container\"?"
},
{
"severity": "error",
"rule": "template-not-found",
"path": "spec.templates[0].dag.tasks[1].template",
"message": "spec.templates[0].dag.tasks[1].template names template \"tranform\", which this workflow does not define. This workflow defines: main, extract, transform, load."
},
{
"severity": "error",
"rule": "task-not-found",
"path": "spec.templates[0].dag.tasks[2].dependencies[0]",
"message": "task \"load\" depends on \"transfrom\", which template \"main\" does not contain. Tasks here: extract, transform, load."
},
{
"severity": "error",
"rule": "task-not-found",
"path": "spec.templates[0].dag.tasks[1].arguments.parameters[0].value",
"message": "this reads the output of \"extrac\", which template \"main\" does not contain. Tasks here: extract, transform, load."
},
{
"severity": "warning",
"rule": "unused-parameter",
"path": "spec.arguments.parameters[0]",
"message": "parameter \"region\" is declared and never read. Reference it as {{workflow.parameters.region}} or drop it."
},
{
"severity": "warning",
"rule": "unused-parameter",
"path": "spec.templates[2].inputs.parameters[0]",
"message": "template \"transform\" declares parameter \"rows\" and never reads it. Reference it as {{inputs.parameters.rows}} or drop it."
},
{
"severity": "error",
"rule": "compile",
"message": "dagweave could not compile this manifest: edge \"e1\" references unknown node"
}
]
}

Each fault’s path points at the spot in the draft, and the messages list the names that do exist, so the assistant knows what to fix.

An error means the workflow can’t run. Here the three errors are references to a template or task that doesn’t exist. They leave the graph with edges pointing at nothing, which causes the compile error and is why no manifest came back.

A warning means it would run, but part of it does nothing. With contianer, the transform step has no container. region and rows are declared and never read.

valid is false if any fault is an error. rule is a machine-readable name; the API reference lists them all.

The check stores and starts nothing, and the same document always gets the same faults in the same order. An assistant can run it after every edit.

The assistant fixes the names and the key, and makes transform read rows and region:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: nightly-etl-
spec:
entrypoint: main
arguments:
parameters:
- name: region
value: eu-west-1
templates:
- name: main
dag:
tasks:
- name: extract
template: extract
- name: transform
template: transform
dependencies: [extract]
arguments:
parameters:
- name: rows
value: "{{tasks.extract.outputs.parameters.rows}}"
- name: load
template: load
dependencies: [transform]
- name: extract
outputs:
parameters:
- name: rows
valueFrom:
path: /tmp/rows
container:
image: alpine:3.19
command: [sh, -c, "echo 12 > /tmp/rows"]
- name: transform
inputs:
parameters:
- name: rows
container:
image: alpine:3.19
command: [sh, -c, "echo transforming {{inputs.parameters.rows}} rows in {{workflow.parameters.region}}"]
- name: load
container:
image: alpine:3.19
command: [sh, -c, "echo loading"]

Checked again:

{
"valid": true,
"format": "argo-yaml",
"faults": [],
"manifest": "apiVersion: argoproj.io/v1alpha1\nkind: Workflow\n..."
}

manifest is what Dagweave compiles the draft to, and it comes back whenever the draft compiles, warnings or not. It’s Dagweave’s output, not your YAML reformatted, so read it before you use it:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
annotations:
dagweave/step-types: '{"load":"container"}'
generateName: nightly-etl-
spec:
arguments:
parameters:
- name: region
value: eu-west-1
entrypoint: main
templates:
- dag:
tasks:
- name: extract
template: extract
- arguments:
parameters:
- name: rows
value: '{{tasks.extract.outputs.parameters.rows}}'
depends: extract
name: transform
template: transform
- depends: transform
name: load
template: load
name: main
- container:
command:
- sh
- -c
- echo 12 > /tmp/rows
image: alpine:3.19
name: extract
outputs:
parameters:
- name: rows
valueFrom:
path: /tmp/rows
- container:
command:
- sh
- -c
- echo transforming {{inputs.parameters.rows}} rows in {{workflow.parameters.region}}
image: alpine:3.19
inputs:
parameters:
- name: rows
name: transform
- container:
command:
- sh
- -c
- echo loading
image: alpine:3.19
name: load

Two things changed. dependencies became depends. And Dagweave rebuilt load as a plain container step, recording that in a dagweave/step-types annotation so the next import reads it the same way. Every template kept its name.

Import the corrected manifest like any Argo manifest (see Import and round-trip). You get three steps and two arrows, and can see at a glance whether that’s the shape you asked for.

From there it’s an ordinary workflow. Edit it, push it to Git, add a trigger or run it on a connected cluster. An assistant with a workflows:write token can save it directly with dagweave_create_workflow, which runs the same checks first.

The checker uses the same importer and compiler as the canvas, so a draft that passes will open there. It checks:

  • field names against the Argo Workflows types
  • that every template, task, dependency and output reference resolves within the document
  • the compiled result against the rules Argo applies when a cluster accepts a workflow, such as an input nothing supplies or a parameter read nothing declares

It can’t see outside the document. It doesn’t know whether alpine:3.19 will pull, whether /tmp/rows exists at read time, or what the service account may do. A clean result means the structure and references are right.

Checking needs workflows:read, the same scope as listing workflows, so an assistant with that token can read and check but can’t change or run anything. Saving needs workflows:write and running needs runs:write, and you can keep those on separate tokens. MCP server explains how to connect a client.