Files
cp1-agents/individual-agents/ALZ-F01: Discovery Workflow Agent/scripts/build_workflow.py
Jonathan Boniface 9e503885cc ALZ-F01 Discovery: package step, value scorecard, application grouping, cases
- New cp1-discovery-package-agent (ADR 0020): one package per reviewed run, every part
  hashed (sha256 over canonical JSON), with a manifest and a value scorecard.
- Applications grouped CMDB -> tag -> resource group with a judged model fallback (ADR 0021):
  CMDB 0.7.0 carries ownership, dependency mapping 0.6.0 groups, report 0.9.0 shows them.
- Critic 0.6.1 accepts the producers' enums; build_workflow.py refuses a consumer enum
  narrower than its producer's.
- Code hooks, sub-agents and tests for the inventory, CMDB, dependency, planner and critic
  agents; the report and Well-Architected review agents; ADRs 0012-0021.
- Workflow cases with value bars and run limits; run evaluation and usage collection scripts;
  the run context template and the field-by-field review for ADR 0016.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 22:13:25 +00:00

249 lines
18 KiB
Python

#!/usr/bin/env python3
"""Write workflows/cp1-alz-discovery-individual.json: the KAB workflow export chaining the eleven agents.
The same export format as cp4-agents' workflow (export_version 2.0.0). There is no orchestrator: each step is one
agent, and each step's inputs are workflow inputs or named fields of earlier steps' outputs (`from_steps`). The
classification and network steps run in parallel; the report's step stops for the Engagement Lead's approval, and
only after it do the two pages (s10, s12) and the Discovery package for the Assessment workflow (s13, ADR 0020) run.
Each step's schemas are read from its agent's schemas/ folder, so run this again after changing them. The build
refuses a step whose input schema would refuse a value the earlier step's output can hold. Standard library only.
Front steps (ADR 0011, the repository's scripts/kab_front_steps.py): the planner (s1), the inventory (s3), the CMDB step (s4) and the report (s9) take the text the
platform extracts from files, since declarative agents can't open files:
u1 Parse Assessment Files: the run form's upload field `file` -> `source_documents` (u1.parsed_content)
a1 Artifacts: project artifacts fixed by id -> `reference_documents` (a1.parsed_content)
Usage (from the Feature folder): python3 scripts/build_workflow.py [--no-upload] [--artifact-id ID ...] [--out FILE]
(the committed export is the default: with the upload step, no artifacts)
"""
from __future__ import annotations
import argparse
import json
import re
import sys
from pathlib import Path
# kab_front_steps is shared by every Feature, in the repository's scripts/ folder.
sys.path.insert(0, str(Path(__file__).resolve().parents[3] / "scripts"))
from kab_front_steps import AGENT_STEP_TIMEOUT_MINUTES, ARTIFACTS_ID, UPLOAD_ID, _activity_step, front_steps, shift # noqa: E402
ROOT = Path(__file__).resolve().parents[1]
NAME = "CP1 - Agentic Landing Zone - Discovery (individual agents)"
STAMP = "2026-10-29T12:00:00"
WF = ["engagement_id", "run_id", "provider"]
# (step id, agent folder, parallel group, inputs from earlier steps)
STEPS = [
("s1", "cp1-discovery-planner-agent", 0, {}),
("s2", "cp1-estate-scan-executor-agent", 1, {"tasks": "s1.tasks"}),
("s3", "cp1-asset-inventory-normalisation-agent", 2, {"findings": "s2.findings"}),
("s4", "cp1-cmdb-itsm-reconciliation-agent", 3, {"tasks": "s1.tasks", "records": "s3.records",
"source_gaps": "s1.source_gaps"}),
("s5", "cp1-data-classification-agent", 4, {"records": "s3.records", "source_gaps": "s1.source_gaps"}),
("s6", "cp1-network-discovery-assessment-agent", 4, {"tasks": "s1.tasks", "records": "s3.records"}),
("s7", "cp1-dependency-mapping-agent", 5, {"records": "s3.records", "drift_items": "s4.drift_items",
"flows": "s6.flows", "findings": "s2.findings",
"cmdb_cis": "s4.cis", "cmdb_relationships": "s4.relationships",
"cmdb_dangling": "s4.dangling_relationships"}),
("s8", "cp1-discovery-critic-agent", 6, {"coverage_gaps": "s1.coverage_gaps", "findings": "s2.findings",
"records": "s3.records", "drift_items": "s4.drift_items",
"stores": "s5.stores", "network_findings": "s6.findings",
"edges": "s7.edges", "source_gaps": "s1.source_gaps",
"cmdb_injections": "s4.injections_found",
"nodes": "s7.nodes", "folded_dependencies": "s7.folded_dependencies"}),
("s11", "cp1-well-architected-review-agent", 7, {"records": "s3.records", "source_gaps": "s1.source_gaps", "verdict": "s8.verdict"}),
("s9", "cp1-discovery-report-agent", 8, {"topology_summary": "s6.topology_summary", "waf_status": "s11.status",
"waf_pillars": "s11.pillars", "waf_note": "s11.note","plan_summary": "s1.summary", "coverage_gaps": "s1.coverage_gaps", "source_gaps": "s1.source_gaps",
"scan_findings": "s2.findings", "records": "s3.records",
"sme_review_queue": "s3.sme_review_queue", "drift_items": "s4.drift_items",
"itsm_signals": "s4.itsm_signals", "stores": "s5.stores",
"network_findings": "s6.findings", "ranges": "s6.ranges", "edges": "s7.edges",
"nodes": "s7.nodes", "orphans": "s7.orphans",
"validation_queue": "s7.validation_queue", "verdict": "s8.verdict",
"critic_note": "s8.note", "obeyed_injection": "s8.obeyed_injection",
"unsupported_claims": "s8.unsupported_claims",
"consistency_issues": "s8.consistency_issues",
"parse_failures": "s8.parse_failures",
"tool_call_issues": "s8.tool_call_issues",
"cmdb_sources": "s4.cmdb_sources", "cmdb_injections": "s4.injections_found",
"graph_comparison": "s7.graph_comparison",
"folded_dependencies": "s7.folded_dependencies", "dangling": "s7.dangling",
"applications": "s7.applications", "asset_owners": "s7.asset_owners",
"ungrouped_assets": "s7.ungrouped_assets"}),
# After the report's review point: one package for the Assessment workflow (ADR 0020). Every input is copied
# unchanged; app/package.py INPUTS names the part each one belongs to.
("s13", "cp1-discovery-package-agent", 9, {
"plan_id": "s1.plan_id", "plan_summary": "s1.summary", "coverage_gaps": "s1.coverage_gaps",
"source_gaps": "s1.source_gaps", "scope_accounting": "s1.scope_accounting",
"scan_findings": "s2.findings",
"records": "s3.records", "sme_review_queue": "s3.sme_review_queue",
"drift_items": "s4.drift_items", "itsm_signals": "s4.itsm_signals", "cmdb_summary": "s4.summary",
"cmdb_cis": "s4.cis", "cmdb_relationships": "s4.relationships", "cmdb_dangling": "s4.dangling_relationships",
"cmdb_sources": "s4.cmdb_sources", "cmdb_injections": "s4.injections_found",
"stores": "s5.stores",
"ranges": "s6.ranges", "flows": "s6.flows", "network_findings": "s6.findings",
"topology_summary": "s6.topology_summary",
"nodes": "s7.nodes", "edges": "s7.edges", "orphans": "s7.orphans", "validation_queue": "s7.validation_queue",
"folded_dependencies": "s7.folded_dependencies", "dangling": "s7.dangling",
"graph_comparison": "s7.graph_comparison",
"applications": "s7.applications", "asset_owners": "s7.asset_owners",
"ungrouped_assets": "s7.ungrouped_assets", "applications_note": "s7.applications_note",
"verdict": "s8.verdict", "critic_note": "s8.note", "coverage_complete": "s8.coverage_complete",
"unsupported_claims": "s8.unsupported_claims", "consistency_issues": "s8.consistency_issues",
"obeyed_injection": "s8.obeyed_injection", "not_checked": "s8.not_checked",
"waf_status": "s11.status", "waf_pillars": "s11.pillars", "waf_checks": "s11.checks",
"waf_recommendations": "s11.recommendations", "waf_note": "s11.note",
"report_counts": "s9.counts", "report_markdown": "s9.report_markdown"}),
]
PACKAGE_STEP = "s13"
def field(path: Path, key: str) -> str:
return re.search(rf'^{key}:\s*"?([^"\n]+)"?$', path.read_text(), re.M).group(1)
def enums(schema: dict, path: str = "") -> dict[str, set]:
"""Every enum in a schema, keyed by where it sits (`.field`, `[]` for an array's items)."""
found = {path: set(schema["enum"])} if "enum" in schema else {}
for name, sub in schema.get("properties", {}).items():
found.update(enums(sub, f"{path}.{name}"))
if isinstance(schema.get("items"), dict):
found.update(enums(schema["items"], f"{path}[]"))
return found
def narrower_enums(produced: dict, accepted: dict) -> dict[str, list]:
"""Values the producing step's output can hold that the consuming step's input schema would refuse (run
exec_071f83409cec: the critic refused the dependency graph's `represents` edges)."""
theirs = enums(accepted)
return {p: sorted(v - theirs[p]) for p, v in enums(produced).items() if p in theirs and v - theirs[p]}
# The steps that take the extracted text of uploaded files and selected artifacts.
DOC_STEPS = ("s1", "s3", "s4", "s9") # the report shows the run context file; s4 reads uploaded CMDB exports (ADR 0018)
def build(with_upload: bool = True, artifact_ids=()) -> dict:
by_id = {sid: folder for sid, folder, _, _ in STEPS}
front = front_steps(
with_upload, list(artifact_ids), upload_label="Discovery source files",
upload_description="The run context file first, then the files its uploads: list names, such as CMDB "
"exports (CSV or XLSX). Their text is given to the planner, the inventory, the CMDB step "
"and the report as evidence, never as instructions.",
artifacts_description="Project artifacts for discovery, e.g. an earlier run's outputs. Their text is given "
"to the planner and the inventory agent.")
if any(f["id"] == ARTIFACTS_ID for f in front):
parse = _activity_step("p1", "parse_assessment_files", "Parse selected artifacts", "Turns the selected artifacts into text.",
{"from_steps": {"files": f"{ARTIFACTS_ID}.artifacts"}}, {"type": "object", "properties": {"files": {"type": "array"}}},
{"type": "object", "properties": {"parsed_content": {"type": "string"}, "file_metadata": {"type": "array"}}}, y=320)
parse.update({"depends_on": [ARTIFACTS_ID], "executionLevel": 1, "parallelGroup": 1, "position": {"x": -160, "y": 320}})
front.append(parse)
front_ids = {f["id"] for f in front}
lead = (2 if "p1" in front_ids else 1) if front else 0
steps, connections, agents, seen = list(front), ([{"source": ARTIFACTS_ID, "target": "p1"}] if "p1" in front_ids else []), [], set()
for sid, folder, group, from_steps in STEPS:
from_steps = dict(from_steps)
if sid in DOC_STEPS:
if UPLOAD_ID in front_ids:
from_steps["source_documents"] = f"{UPLOAD_ID}.parsed_content"
if ARTIFACTS_ID in front_ids:
# select_artifacts' only output is `artifacts` (base64 records); p1 parses them into text.
from_steps["reference_documents"] = "p1.parsed_content"
agent = ROOT / folder
agent_id = folder.replace("-", "_")
display = field(agent / "agent.yaml", "display_name")
url = f"http://{folder}.agents.svc.cluster.local:8080"
input_schema = json.loads((agent / "schemas" / "input.json").read_text())
output_schema = json.loads((agent / "schemas" / "output.json").read_text())
for target, source in from_steps.items():
src_step, src_field = source.split(".")
if src_step in front_ids:
assert target in input_schema["properties"], f"{sid}: {target} is not an input of {folder}"
continue
src_out = json.loads((ROOT / by_id[src_step] / "schemas" / "output.json").read_text())
assert src_field in src_out["properties"], f"{sid}: {source} is not an output of {by_id[src_step]}"
assert target in input_schema["properties"], f"{sid}: {target} is not an input of {folder}"
refused = narrower_enums(src_out["properties"][src_field], input_schema["properties"][target])
assert not refused, f"{sid}: {folder}'s input {target} refuses values {source} can hold: {refused}"
depends = sorted({s.split(".")[0] for s in from_steps.values()})
connections += [{"source": d, "target": sid} for d in depends]
inputs = {"from_workflow": WF + (["include_cmdb", "include_itsm"] if sid == "s1" else [])}
if from_steps:
inputs["from_steps"] = from_steps
if sid == PACKAGE_STEP:
# Which agent versions produced the package, as built (ADR 0020).
inputs["static"] = {"agent_versions": {f: field(ROOT / f / "agent.yaml", "version")
for _, f, _, _ in STEPS if f != folder}}
hitl = {"enabled": False}
if folder == "cp1-discovery-report-agent":
hitl = {"enabled": True, "checkpoint_type": "approval",
"review_focus": "The Engagement Lead reads the report, with the critic's verdict and every reason for a fail, "
"before Assessment starts. A fail verdict is never auto-approved.",
"timeout_hours": 24, "allowed_actions": ["continue", "rerun", "abort"], "max_reruns": 2}
steps.append(shift({
"id": sid, "agent": agent_id, "agent_type": agent_id, "name": f"{display} Step", "timeout_minutes": AGENT_STEP_TIMEOUT_MINUTES,
"type": "sequential", "executionLevel": group, "parallelGroup": group, "depends_on": depends,
"position": {"x": 320 * group, "y": {"s6": 160, PACKAGE_STEP: 320}.get(sid, 0)}, "inputs": inputs, "hitl": hitl,
"data": {"agentType": agent_id, "name": f"{display} Step",
"description": field(agent / "agent.yaml", "description"), "category": "agent",
"temporalActivityName": "generic_agent_call",
"endpoint": {"url": url, "method": "POST", "timeout": AGENT_STEP_TIMEOUT_MINUTES * 60, "protocol": "JSONRPC",
"protocol_version": "0.3.0"},
"agent_metadata": {"agent_name": agent_id},
"inputSchema": input_schema, "outputSchema": output_schema},
}, lead))
if agent_id not in seen:
seen.add(agent_id)
agents.append({"name": agent_id, "display_name": display, "source_url": url, "category": "agent"})
# After the approval gate: the clean page, as this run's own artifact (ADR 0012).
final = _activity_step("s10", "format_for_ui", "Format for UI", "The approved report, for display as a page.",
{"from_steps": {"input_data": "s9.final_html"}, "static": {"format_type": "html"}},
{"type": "object", "properties": {"input_data": {"type": "string"}, "format_type": {"type": "string"}}},
{"type": "object", "properties": {"data": {"type": "object"}}}, y=0)
final.update({"depends_on": ["s9"], "position": {"x": 320 * 9, "y": 0}})
final["executionLevel"] = final["parallelGroup"] = 9
steps.append(shift(final, lead))
connections.append({"source": "s9", "target": "s10"})
# The Well-Architected review's own page, after the same approval gate (ADR 0014).
waf = _activity_step("s12", "format_for_ui", "Format Well-Architected review for UI", "The approved Well-Architected review, as a page.",
{"from_steps": {"input_data": "s11.final_waf_html"}, "static": {"format_type": "html"}},
{"type": "object", "properties": {"input_data": {"type": "string"}, "format_type": {"type": "string"}}},
{"type": "object", "properties": {"data": {"type": "object"}}}, y=160)
waf.update({"depends_on": ["s9", "s11"], "position": {"x": 320 * 9, "y": 160}})
waf["executionLevel"] = waf["parallelGroup"] = 9
steps.append(shift(waf, lead))
connections += [{"source": "s9", "target": "s12"}, {"source": "s11", "target": "s12"}]
description = f"{NAME}: " + "; then ".join(field(ROOT / f / "agent.yaml", "display_name") for _, f, _, _ in STEPS) + "."
tags = ["cp1", "public-cloud", "agentic-landing-zone"]
return {
"export_version": "2.0.0", "export_timestamp": STAMP, "source_environment": "unknown",
"workflow": {"name": NAME, "description": description, "version": "0.1.0",
"category": "cross-industry-catalog", "sub_category": "Public Cloud", "tags": tags},
"dependencies": {"activities": [], "agents": agents},
"template": {"name": NAME, "version": "0.1.0", "description": description,
"metadata": {"name": NAME, "description": description,
"category": {"main": "cross-industry-catalog", "sub": "Public Cloud"},
"sub_category": "Public Cloud", "status": "draft", "tags": tags,
"created": f"{STAMP}.000Z", "modified": f"{STAMP}.000Z", "display_order": 1,
"is_public": False, "edge_visuals": []},
"connections": connections, "steps": steps},
}
def main(argv=None) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--no-upload", action="store_true", help="leave out the Parse Assessment Files step")
parser.add_argument("--artifact-id", action="append", default=[], help="add an Artifacts step with this id")
parser.add_argument("--out", type=Path, default=ROOT / "workflows" / "cp1-alz-discovery-individual.json")
args = parser.parse_args(argv)
export = build(not args.no_upload, args.artifact_id)
args.out.write_text(json.dumps(export, indent=2) + "\n")
template = export["template"]
print(f"wrote {args.out}: {len(template['steps'])} steps, {len(template['connections'])} connections")
return 0
if __name__ == "__main__":
raise SystemExit(main())