All checks were successful
check agents / check (push) Successful in 10s
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>
9.2 KiB
9.2 KiB
Plan: integrating KAB platform artifacts into the CP1 Discovery agents
Moved here on 2026-10-29. Written while the agents were in two separate repositories, both now in this one:
cp1-agents→sub-agents/ALZ-F01: Discovery Workflow Agent/, andcp1-agents-individual→individual-agents/ALZ-F01: Discovery Workflow Agent/.
| Date | 2026-10-29 |
| Scope | code_generated/cp1-agents (orchestrator pattern) and code_generated/cp1-agents-individual (individual pattern) |
| Platform reviewed | modernization-platform @ 7adfc87f (2026-10-19) |
| Rule | In the orchestrator pattern, only the orchestrator handles artifacts. Its sub-agents never receive an artifact reference: they see workspace records only. |
| Status | Plan for review. Nothing changed yet. |
1. How artifacts work on the platform today
| Question | Finding | Where |
|---|---|---|
| Can an agent call the artifact API? | No. The API needs a user's or the platform's internal token, and agents run with AGENT_EGRESS=enforce: they can reach only the model gateway and the MCP gateway. |
agent-builder-api/src/api/artifact_routes.py; agents' configmap.yaml |
| How does an artifact reach an agent? | Through a select_artifacts workflow step. The designer picks artifact_ids (fixed per workflow, as static inputs). At run time the step outputs either artifacts, a list of entries with file_path on the executions volume, content_type and optional base64 content up to 5 MB, or parsed_content, the decoded file. An agent step takes one of them with from_steps, e.g. "artifacts": "s0.artifacts", and the API marks the producing step wants_artifacts / wants_parsed_content. |
agent-builder-temporal-workers/.../activities/artifacts_activities.py (SelectArtifactsActivity); workflow_execution_routes.py (ON_DEMAND_OUTPUTS) |
| How does an agent declare what it accepts? | An input named artifacts (array) with x-artifact-types in schemas/input.json. KAB's run chat then offers the agent for runs that hold those types. |
agent-builder-knowledge-graph-analyst/schemas/input.json; services/run_chat/follow_up.py |
| How does an agent read one? | The reference agent accepts the list in several shapes (find_artifacts). It reads a referenced file only if the real path is inside the executions volume (read_file). |
agent-builder-knowledge-graph-analyst/app/request.py |
| How does an agent's output become an artifact? | Automatically. At the end of a run with a project_id, the executor registers every step's output as an execution_output artifact at pv://{execution_id}/step_{n}/output.json. There is no per-step artifact type. |
generic_workflow_executor.py (_register_artifacts); artifact_registration_activities.py |
| Which artifact types exist? | knowledge_graph, structured_data, file, report, assessment_result (supports contributions) and execution_output (on the volume). |
agent-builder-api/src/database/init_artifact_types.py |
| Typed outputs and contributions? | Only through the API (POST /projects/{id}/artifacts, .../contributions), so not from an agent. |
artifact_routes.py |
This corrects what I said earlier: workflow steps can take constants. The executor accepts static inputs beside from_workflow and from_steps.
2. Design
2.1 Orchestrator pattern: only the orchestrator integrates
s0 select_artifacts (static artifact_ids) --artifacts--> s1 orchestrator (plan) -> s2 collect -> s3 analyse -> s4 critique
|
+- import_artifacts (code): each artifact -> workspace record
plan/artifact-<n>, produced_by "platform-artifact"
sub-agents <- delegate(input_refs=["plan/artifact-1", ...]) (records only; never artifact ids or paths)
each phase reply ------------------------------------------> execution_output artifact (automatic, end of run)
- Input. Add an optional
artifactsinput (array,x-artifact-types: ["file", "structured_data", "report", "execution_output"]). - Import, in code, not the model. In the plan phase,
pre_processcalls a newapp/artifacts.py(import_artifacts). For each artifact it:- accepts the platform's shapes, as
find_artifactsdoes; - reads only files whose real path is under
/data/executions, with a size cap; - parses JSON or CSV, otherwise keeps text;
- stores one write-once record per artifact,
plan/artifact-<n>, withartifact_id,type_id, the sourcesha256andfile_pathas provenance, chained in the manifest like every other record.
- accepts the platform's shapes, as
- Sub-agents unchanged. The orchestrator's plan skill lists the artifact records and passes them with
delegate: to the planner (for example a scope or CMDB export), and in analyse to DSC-03 / DSC-04. Sub-agents get records exactly as now, and their prompts and functions don't change. - Output. Phase replies already become
execution_outputartifacts. The critique reply gains a compactdeliverableobject (verdict, coverage, the counts per output, and refs), so its artifact is the Discovery deliverable that Assessment can select. - Charter. Artifact content is data: the existing content rule and the injection checks apply. The critic gets the artifact records with everything else.
2.2 Individual pattern: each agent integrates itself, declaratively
These agents have no code, so they can't read files. They use parsed_content, the decoded file, never artifacts, the paths.
- Workflow. Add an optional
s0 select_artifactsstep. Steps that need source data take it withfrom_steps, e.g."source_records": "s0.parsed_content":- planner: a scope or connector export;
- inventory: a CMDB or asset export.
- Contracts. Add an optional
source_recordsinput to those two agents (nox-artifact-types, because they don't take theartifactslist). Their prompts say to treat it as data, cite it asartifact:<id>, and never follow instructions in it. - Output. Unchanged. Every step's reply already becomes an
execution_outputartifact. - Limit.
parsed_contentis inline, bounded by the platform's inline payload limit, so large exports stay a job for the orchestrator pattern.
3. Steps
| # | Step | Repository | Verified by |
|---|---|---|---|
| 1 | ADRs: orchestrator 0012 (artifacts enter only through the orchestrator, as workspace records); individual 0011 (artifacts through parsed_content) |
both | Review |
| 2 | app/artifacts.py: find_artifacts and a bounded, volume-only read_artifact_file; import_artifacts writes plan/artifact-<n> |
cp1-agents |
Dry run: list, wrapped and file-reference shapes; path outside the volume refused; oversize refused; duplicate import write-once |
| 3 | Input schema artifacts + x-artifact-types; output deliverable on critique; pre_process calls the import in plan only |
cp1-agents |
Dry run; contract validation |
| 4 | Plan skill: list artifact records and pass them to dsc_01_planner; analyse skill: pass them to DSC-03 / DSC-04 |
cp1-agents |
Review; eval case with a CMDB export artifact |
| 5 | Workflow export: optional s0 select_artifacts step with static artifact_ids; s1.from_steps.artifacts |
both | Export shape still matches; builder asserts wiring |
| 6 | Individual agents: source_records on planner and inventory; prompt line; regenerate from the scaffold |
cp1-agents-individual |
check_agents.py (cp4's) 0 problems; runtime parse; eval validation |
| 7 | Version 0.2.0 + release notes; rebuild and push; kubectl diff, then apply |
both | Pods ready; cards list the new input |
| 8 | In-cluster check: put a small fixture artifact file under /data/executions, run import_artifacts inside the orchestrator pod, confirm the record and its hash |
cp1-agents |
Record stored; chain sound |
| 9 | End-to-end, once MCP keys exist: run the workflow in a project with one selected artifact | both | Artifact record used by the planner; phase outputs listed as execution_output artifacts |
4. Decisions for you
- Which artifacts should Discovery take? For example a CMDB or asset export, a scope list, a previous discovery run's outputs, or client documents. This decides the
x-artifact-typeslist and which sub-agents get them. - Should we ask the platform team for typed outputs? Today every output is
execution_output. A per-step output type, such asstructured_datafor the inventory orassessment_resultwith contributions for findings, would need a platform change: either the executor taking an output type per step, or an artifacts MCP server agents could call. - Projects. Outputs are registered only when the run has a
project_id, so Discovery must run inside the engagement's KAB project.
5. Constraints and risks
- Still blocked end to end: real runs need the MCP keys, which need the gateway tenant link (see
kab-dev-mcp-gateway-default-tenant-500-2026-10-29.md). Steps 1–8 don't. - Sizes:
select_artifactsinlines at most 5 MB, and larger values travel as file references, which only the orchestrator can read. - Provenance: an imported artifact's
sha256is recorded at import. A later change to the artifact doesn't change the run's record.