Files
Jonathan Boniface 416c66ced4
All checks were successful
check agents / check (push) Successful in 10s
Add CP1 Discovery agents in both patterns
ALZ-F01 Discovery as a sub-agent orchestrator (sub-agents/) and as eight
individual declarative agents (individual-agents/), with their KAB workflow
exports. Shared check, render and import scripts, the alz-discovery-sample
MCP server, the crucible-kab-dev deploy profile, deployment docs, platform
issue reports and the source material. Agent steps time out at 20 minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 18:25:57 +00:00
..

CP1 - ALZ Discovery Orchestrator Agent

Runs one phase of Agentic Landing Zone discovery (plan, collect, analyse or critique) for an engagement. It keeps the run's working data in a hash-chained workspace, and returns the phase's artifacts and, for critique, a coverage verdict enforced in code.

The four steps of the workflow "CP1 - Agentic Landing Zone - Discovery" (ALZ-F01) all call this agent. Version 0.2.0, built 2026-10-29 on the KAB agent runtime 0.35.7 (agent-runtime-adk). The runtime builds the agent from agent.yaml: its instructions are prompt.md, it accepts and returns only what schemas/ declares, and its own code is in app/.

Unlike the CP4 agents, this one is not purely declarative. It has sub-agents, functions and hooks, so it carries an app/ folder (see Why app/).

Inputs

Field Type Required Description
engagement_id string yes The engagement being discovered. One engagement is one platform project.
run_id string yes The discovery run. Every phase of one run passes the same id; that is how a later phase reads what an earlier one stored.
phase string | null no plan, collect, analyse or critique. Left out, the first phase the run has not yet stored.
batch integer | null no collect only: the scan batch to run; null runs every batch.
source_documents string | null no plan only: text of files uploaded at run time (a Parse Assessment Files step's parsed_content). Imported as plan/source-documents.
artifacts array | null no plan only: project artifacts an Artifacts step selected (x-artifact-types: file, structured_data, report, execution_output, assessment_result). Each imported as plan/artifact-NN; id, type, path and hash kept in plan/artifact-NN-provenance.

Outputs

Field Type Required Description
engagement_id, run_id, phase string yes As run; the phase is the one actually run.
status string yes completed, completed_with_gaps, halted or failed, set by the phase's checks in code, not by the model.
artifacts array yes What the phase stored, from the workspace manifest: name, ref, sha256, produced_by.
summary string yes Three sentences at most.
issues array yes Refused calls, failed sub-agents, failed checks, declared gaps.
next_phase string | null yes The phase to run next; null after critique or on failure.
verdict object | null yes critique only: verdict, coverage_complete, coverage_gaps, declared_gaps, reasons, recomputed in post_process.
manifest_head string yes The head hash of the run's workspace manifest.

Knowledge packs

One skill per phase, under skills/: discovery-plan, discovery-collect, discovery-analyse, discovery-critique. The orchestrator loads the one for the phase it runs.

Sub-agents

One sub-agent per ADO story of Feature ALZ-F01. All are as_tool: false, so the model never calls them directly: it calls delegate, whose code asks them through the runtime and stores their replies.

Sub-agent Story Prompt
dsc_01_planner ALZ-DSC-01 Discovery Planner prompts/dsc_01_planner.md
dsc_02_scan_executor ALZ-DSC-02 Estate Scan Executor prompts/dsc_02_scan_executor.md
dsc_03_inventory ALZ-DSC-03 Asset Inventory Normalisation prompts/dsc_03_inventory.md
dsc_04_cmdb_reconciliation ALZ-DSC-04 CMDB & ITSM Reconciliation prompts/dsc_04_cmdb_reconciliation.md
dsc_05_data_classification ALZ-DSC-05 Data Classification prompts/dsc_05_data_classification.md
dsc_06_dependency_mapping ALZ-DSC-06 Dependency Mapping prompts/dsc_06_dependency_mapping.md
dsc_07_network ALZ-DSC-07 Network Discovery & Assessment prompts/dsc_07_network.md
dsc_08_critic ALZ-DSC-08 Discovery Critic (own model: DSC_08_CRITIC_LLM_MODEL) prompts/dsc_08_critic.md

MCP tools

Sub-agents cannot hold MCP tools, so the orchestrator makes every call itself. All the tools are read-only, declared under mcp: in agent.yaml across nine logical servers (alz-scope, alz-estate, alz-cloud, alz-cmdb, alz-inventory, alz-schema, alz-dependency, alz-network, alz-evidence). ../../../mcp-servers/alz-discovery-sample serves all 20 of them over the Meridian Retail Group sample estate. Register it under each of the nine names on the MCP gateway. The agent does not finish starting until its MCP tools can be listed.

Why app/

File What it does
app/artifacts.py Imports uploads and project artifacts into the workspace (plan phase only): files read only from the executions volume, size-capped, provenance kept in a separate record sub-agents never get.
app/workspace.py Write-once records under $EXECUTION_STORAGE_ROOT/alz-discovery/<engagement>/<run>/, chained in manifest.jsonl. These are the data, context and memory the phases and sub-agents share.
app/tools.py workspace_put / workspace_get / workspace_list, and delegate, which hands work to a sub-agent and stores its reply with a hash.
app/rules.py The story files' rules as code: plan checks, match score, record confidence, ghost action, roll-up, edge score, node metrics, overlaps, bottlenecks, coverage.
app/business_logic.py pre_process binds the run, infers the phase and refuses a phase whose predecessor hasn't run. post_process rebuilds the reply from the workspace and enforces the verdict.

Run it locally

docker build -t cp1-alz-discovery-orchestrator-agent:local .
docker run --rm -p 8080:8080 \
  -e LITELLM_MODEL=gpt-5.6-sol \
  -e LITELLM_TEMPERATURE=1 \
  -e LITELLM_MAX_TOKENS=32000 \
  -e LITELLM_PROXY_BASE=<your LiteLLM gateway> \
  -e LITELLM_MASTER_KEY=<your LiteLLM key> \
  -e MCP_GATEWAY_URL=<your MCP gateway> \
  -e MCP_AGENT_API_KEY=<the agent's MCP key> \
  cp1-alz-discovery-orchestrator-agent:local
curl http://localhost:8080/.well-known/agent-card.json

Then python -m kyndryl_agent_runtime.eval --url http://localhost:8080 --cases eval/cases.yaml runs the eval cases (it needs kyndryl-agent-runtime[eval]). python3 ../scripts/dry_run.py . checks the agent's code with no model and no MCP server.