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

83 lines
6.3 KiB
Markdown

# 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/](#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`](../../../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
```sh
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.