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.
The prompt
Section titled “The prompt”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 draft
Section titled “The draft”The first attempt looks like Argo YAML, but it won’t run.
apiVersion: argoproj.io/v1alpha1kind: Workflowmetadata: 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 check
Section titled “The check”The assistant sends the draft as a string in one tool call:
POST /api/v1/mcp HTTP/1.1Host: api.dagweave.comAuthorization: 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" } ]}Reading the answer
Section titled “Reading the answer”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 correction
Section titled “The correction”The assistant fixes the names and the key, and makes transform read rows and
region:
apiVersion: argoproj.io/v1alpha1kind: Workflowmetadata: 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..."}What the draft became
Section titled “What the draft became”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/v1alpha1kind: Workflowmetadata: 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: loadTwo 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.
On the canvas
Section titled “On the canvas”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.
What the check covers
Section titled “What the check covers”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.
Scopes
Section titled “Scopes”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.