From 416c66ced48f0d66796053768308e2b4ed8b1585 Mon Sep 17 00:00:00 2001 From: Jonathan Boniface Date: Thu, 29 Oct 2026 18:25:57 +0000 Subject: [PATCH] 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 --- .agents/CONTEXT.md | 57 + .gitea/workflows/check.yml | 24 + .gitignore | 4 + CLAUDE.md | 33 + README.md | 68 + deploy/crucible-kab-dev.yaml | 84 + docs/README.md | 26 + docs/artifact-integration-plan-2026-10-29.md | 86 + docs/deployment.md | 121 + .../report-2026-10-29.md | 84 + .../mcp-gateway-default-tenant/README.md | 12 + ...-agent-builder-mcp-gateway.deployment.yaml | 153 + .../mcp-gateway-link-default-tenant.job.yaml | 66 + .../report-2026-10-29.md | 231 ++ .../mcp-gateway-default-tenant/secrets.yaml | 15 + .../agent-shapes/agent-pattern/.dockerignore | 29 + .../agent-shapes/agent-pattern/.env.example | 124 + .../agent-shapes/agent-pattern/.gitignore | 21 + .../agent-shapes/agent-pattern/Dockerfile | 63 + .../agent-shapes/agent-pattern/README.md | 495 +++ .../agent-pattern/RELEASE_NOTES.md | 18 + .../agent-shapes/agent-pattern/agent.yaml | 88 + .../agent-pattern/app/__init__.py | 1 + .../agent-pattern/app/business_logic.py | 193 + .../agent-pattern/app/policy.yaml | 48 + .../agent-shapes/agent-pattern/app/tools.py | 146 + .../agent-pattern/eval/cases.yaml | 263 ++ .../eval/schemas/cases-1.1.schema.json | 289 ++ .../agent-pattern/kubernetes/configmap.yaml | 108 + .../agent-pattern/kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../agent-pattern/kubernetes/namespace.yaml | 7 + .../agent-pattern/kubernetes/secretnames.yaml | 34 + .../agent-pattern/kubernetes/service.yaml | 33 + .../agent-shapes/agent-pattern/prompt.md | 14 + .../agent-pattern/requirements.txt | 8 + .../agent-shapes/agent-pattern/run-local.sh | 224 ++ .../agent-pattern/schemas/input.json | 52 + .../agent-pattern/schemas/output.json | 45 + .../agent-pattern/skills/README.md | 66 + .../skills/review-purchases/SKILL.md | 35 + .../skills/review-travel-and-meals/SKILL.md | 35 + .../review-travel-and-meals/references/faq.md | 11 + .../agent-pattern/tests/a2a_client.py | 359 ++ .../agent-pattern/tests/requirements.txt | 13 + .../agent-pattern/tests/test_chatbot.py | 253 ++ .../subagent-pattern/.dockerignore | 29 + .../subagent-pattern/.env.example | 124 + .../agent-shapes/subagent-pattern/.gitignore | 21 + .../agent-shapes/subagent-pattern/Dockerfile | 67 + .../agent-shapes/subagent-pattern/README.md | 495 +++ .../subagent-pattern/RELEASE_NOTES.md | 18 + .../agent-shapes/subagent-pattern/agent.yaml | 98 + .../subagent-pattern/app/__init__.py | 1 + .../subagent-pattern/app/business_logic.py | 193 + .../subagent-pattern/app/policy.yaml | 48 + .../subagent-pattern/app/tools.py | 146 + .../subagent-pattern/eval/cases.yaml | 263 ++ .../eval/schemas/cases-1.1.schema.json | 289 ++ .../kubernetes/configmap.yaml | 112 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../subagent-pattern/kubernetes/service.yaml | 33 + .../agent-shapes/subagent-pattern/prompt.md | 14 + .../subagent-pattern/prompts/subagents.md | 1 + .../subagent-pattern/requirements.txt | 8 + .../subagent-pattern/run-local.sh | 224 ++ .../subagent-pattern/schemas/input.json | 52 + .../subagent-pattern/schemas/output.json | 45 + .../subagent-pattern/skills/README.md | 66 + .../skills/review-purchases/SKILL.md | 35 + .../skills/review-travel-and-meals/SKILL.md | 35 + .../review-travel-and-meals/references/faq.md | 11 + .../subagent-pattern/tests/a2a_client.py | 359 ++ .../subagent-pattern/tests/requirements.txt | 13 + .../subagent-pattern/tests/test_chatbot.py | 253 ++ .../Workflow-01-Discovery 1.pdf | Bin 0 -> 2234314 bytes .../PCA-03-Business-Requirements.md | 144 + .../PCA-03-Comprehensive-Prompt.md | 370 ++ .../workflow-files/FILE_2194.json | 511 +++ .../workflow-files/FILE_4357.json | 448 +++ .../workflow-files/FILE_6034.json | 634 +++ .../workflow-files/FILE_6422.json | 799 ++++ .../workflow-files/FILE_6423.json | 402 ++ .../workflow-files/FILE_6763.json | 474 +++ .../workflow-files/FILE_9563.json | 421 ++ .../.agents/CONTEXT.md | 25 + .../.agents/PLAN.md | 27 + .../CLAUDE.md | 23 + .../README.md | 62 + .../.agents/CONTEXT.md | 24 + .../CLAUDE.md | 23 + .../Dockerfile | 5 + .../README.md | 53 + .../RELEASE_NOTES.md | 11 + .../agent.yaml | 29 + .../docs/adr/README.md | 13 + .../docs/user-guide.md | 33 + .../eval/cases.yaml | 43 + .../kubernetes/configmap.yaml | 111 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../prompt.md | 148 + .../schemas/input.json | 88 + .../schemas/output.json | 182 + .../.agents/CONTEXT.md | 24 + .../CLAUDE.md | 23 + .../Dockerfile | 5 + .../README.md | 55 + .../RELEASE_NOTES.md | 5 + .../agent.yaml | 31 + .../docs/adr/README.md | 11 + .../docs/user-guide.md | 33 + .../eval/cases.yaml | 142 + .../kubernetes/configmap.yaml | 111 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../prompt.md | 144 + .../schemas/input.json | 234 ++ .../schemas/output.json | 172 + .../.agents/CONTEXT.md | 24 + .../cp1-data-classification-agent/CLAUDE.md | 23 + .../cp1-data-classification-agent/Dockerfile | 5 + .../cp1-data-classification-agent/README.md | 50 + .../RELEASE_NOTES.md | 5 + .../cp1-data-classification-agent/agent.yaml | 28 + .../docs/adr/README.md | 11 + .../docs/user-guide.md | 33 + .../eval/cases.yaml | 65 + .../kubernetes/configmap.yaml | 111 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../cp1-data-classification-agent/prompt.md | 128 + .../schemas/input.json | 184 + .../schemas/output.json | 119 + .../.agents/CONTEXT.md | 24 + .../cp1-dependency-mapping-agent/CLAUDE.md | 23 + .../cp1-dependency-mapping-agent/Dockerfile | 5 + .../cp1-dependency-mapping-agent/README.md | 57 + .../RELEASE_NOTES.md | 5 + .../cp1-dependency-mapping-agent/agent.yaml | 30 + .../docs/adr/README.md | 11 + .../docs/user-guide.md | 33 + .../eval/cases.yaml | 67 + .../kubernetes/configmap.yaml | 111 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../cp1-dependency-mapping-agent/prompt.md | 154 + .../schemas/input.json | 288 ++ .../schemas/output.json | 147 + .../.agents/CONTEXT.md | 24 + .../cp1-discovery-critic-agent/CLAUDE.md | 23 + .../cp1-discovery-critic-agent/Dockerfile | 5 + .../cp1-discovery-critic-agent/README.md | 66 + .../RELEASE_NOTES.md | 5 + .../cp1-discovery-critic-agent/agent.yaml | 31 + .../docs/adr/README.md | 11 + .../docs/user-guide.md | 33 + .../eval/cases.yaml | 49 + .../kubernetes/configmap.yaml | 111 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../cp1-discovery-critic-agent/prompt.md | 153 + .../schemas/input.json | 589 +++ .../schemas/output.json | 133 + .../.agents/CONTEXT.md | 24 + .../cp1-discovery-planner-agent/CLAUDE.md | 23 + .../cp1-discovery-planner-agent/Dockerfile | 5 + .../cp1-discovery-planner-agent/README.md | 56 + .../RELEASE_NOTES.md | 11 + .../cp1-discovery-planner-agent/agent.yaml | 30 + .../docs/adr/README.md | 11 + .../docs/user-guide.md | 33 + .../eval/cases.yaml | 18 + .../kubernetes/configmap.yaml | 111 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../cp1-discovery-planner-agent/prompt.md | 170 + .../schemas/input.json | 33 + .../schemas/output.json | 125 + .../.agents/CONTEXT.md | 24 + .../cp1-estate-scan-executor-agent/CLAUDE.md | 23 + .../cp1-estate-scan-executor-agent/Dockerfile | 5 + .../cp1-estate-scan-executor-agent/README.md | 50 + .../RELEASE_NOTES.md | 5 + .../cp1-estate-scan-executor-agent/agent.yaml | 30 + .../docs/adr/README.md | 11 + .../docs/user-guide.md | 33 + .../eval/cases.yaml | 95 + .../kubernetes/configmap.yaml | 111 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../cp1-estate-scan-executor-agent/prompt.md | 138 + .../schemas/input.json | 67 + .../schemas/output.json | 63 + .../.agents/CONTEXT.md | 24 + .../CLAUDE.md | 23 + .../Dockerfile | 5 + .../README.md | 53 + .../RELEASE_NOTES.md | 5 + .../agent.yaml | 30 + .../docs/adr/README.md | 10 + .../docs/user-guide.md | 33 + .../eval/cases.yaml | 142 + .../kubernetes/configmap.yaml | 111 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../prompt.md | 136 + .../schemas/input.json | 233 ++ .../schemas/output.json | 136 + .../docs/README.md | 9 + .../docs/adr/0001.md | 19 + .../docs/adr/0002.md | 20 + .../docs/adr/0003.md | 20 + .../docs/adr/0004.md | 16 + .../docs/adr/0005.md | 21 + .../docs/adr/0006.md | 23 + .../docs/adr/0007.md | 23 + .../docs/adr/0008.md | 17 + .../docs/adr/0009.md | 14 + .../docs/adr/0010.md | 17 + .../docs/adr/0011.md | 24 + .../docs/adr/README.md | 29 + .../docs/adr/template.md | 14 + .../scripts/build_workflow.py | 150 + .../scripts/scaffold_from_stories.py | 706 ++++ .../cp1-alz-discovery-individual.json | 3428 +++++++++++++++++ mcp-servers/alz-discovery-sample.server.yaml | 585 +++ mcp-servers/alz-discovery-sample/.env.example | 55 + mcp-servers/alz-discovery-sample/.gitignore | 15 + mcp-servers/alz-discovery-sample/Dockerfile | 43 + mcp-servers/alz-discovery-sample/README.md | 196 + .../alz-discovery-sample/constraints.txt | 28 + .../kubernetes/configmap.yaml | 22 + .../kubernetes/deployment.yaml | 71 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 18 + .../kubernetes/service.yaml | 33 + .../alz-discovery-sample/mcp_connection.py | 220 ++ .../alz-discovery-sample/requirements.txt | 36 + mcp-servers/alz-discovery-sample/server.py | 1224 ++++++ .../tests/test_conformance.py | 334 ++ scripts/check_agents.py | 212 + scripts/kab_front_steps.py | 80 + scripts/kab_import_workflow.py | 122 + scripts/render_k8s.py | 145 + scripts/render_mcp_server.py | 106 + scripts/smoke_mcp_server.py | 88 + .../CLAUDE.md | 18 + .../README.md | 53 + .../.agents/CONTEXT.md | 63 + .../.agents/PLAN.md | 43 + .../CLAUDE.md | 23 + .../Dockerfile | 10 + .../README.md | 82 + .../RELEASE_NOTES.md | 15 + .../agent.yaml | 149 + .../app/__init__.py | 1 + .../app/artifacts.py | 153 + .../app/business_logic.py | 391 ++ .../app/rules.py | 322 ++ .../app/tools.py | 247 ++ .../app/workspace.py | 176 + .../docs/README.md | 10 + .../adr/0001-orchestrator-with-sub-agents.md | 22 + .../adr/0002-workspace-replaces-alz-run.md | 22 + .../adr/0003-orchestrator-makes-mcp-calls.md | 22 + .../adr/0004-four-phases-one-request-each.md | 22 + ...b-agents-from-code-and-enforced-verdict.md | 23 + .../docs/adr/0006-findings-per-scan-batch.md | 20 + .../docs/adr/0007-names.md | 14 + .../docs/adr/0008-app-folder-in-cp1-agents.md | 20 + .../docs/adr/0009-models.md | 20 + .../adr/0010-evidence-in-execution-storage.md | 20 + ...tomize-deploy-secrets-outside-manifests.md | 20 + ...0012-artifacts-through-the-orchestrator.md | 33 + .../docs/adr/README.md | 30 + .../docs/adr/template.md | 20 + .../docs/user-guide.md | 82 + .../eval/cases.yaml | 148 + .../kubernetes/configmap.yaml | 134 + .../kubernetes/deployment.yaml | 81 + .../kubernetes/kustomization.yaml | 20 + .../kubernetes/namespace.yaml | 7 + .../kubernetes/secretnames.yaml | 34 + .../kubernetes/service.yaml | 33 + .../prompt.md | 43 + .../prompts/dsc_01_planner.md | 84 + .../prompts/dsc_02_scan_executor.md | 73 + .../prompts/dsc_03_inventory.md | 72 + .../prompts/dsc_04_cmdb_reconciliation.md | 69 + .../prompts/dsc_05_data_classification.md | 66 + .../prompts/dsc_06_dependency_mapping.md | 69 + .../prompts/dsc_07_network.md | 59 + .../prompts/dsc_08_critic.md | 76 + .../schemas/input.json | 77 + .../schemas/output.json | 147 + .../skills/discovery-analyse/SKILL.md | 42 + .../skills/discovery-collect/SKILL.md | 32 + .../skills/discovery-critique/SKILL.md | 22 + .../skills/discovery-plan/SKILL.md | 31 + .../scripts/build_workflow.py | 152 + .../scripts/dry_run.py | 263 ++ .../workflows/cp1-alz-discovery.json | 1223 ++++++ 331 files changed, 33561 insertions(+) create mode 100644 .agents/CONTEXT.md create mode 100644 .gitea/workflows/check.yml create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 deploy/crucible-kab-dev.yaml create mode 100644 docs/README.md create mode 100644 docs/artifact-integration-plan-2026-10-29.md create mode 100644 docs/deployment.md create mode 100644 docs/platform-issues/artifacts-step-within-a-run/report-2026-10-29.md create mode 100644 docs/platform-issues/mcp-gateway-default-tenant/README.md create mode 100644 docs/platform-issues/mcp-gateway-default-tenant/kyn-agent-builder-mcp-gateway.deployment.yaml create mode 100644 docs/platform-issues/mcp-gateway-default-tenant/mcp-gateway-link-default-tenant.job.yaml create mode 100644 docs/platform-issues/mcp-gateway-default-tenant/report-2026-10-29.md create mode 100644 docs/platform-issues/mcp-gateway-default-tenant/secrets.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/.dockerignore create mode 100644 docs/source-material/agent-shapes/agent-pattern/.env.example create mode 100644 docs/source-material/agent-shapes/agent-pattern/.gitignore create mode 100644 docs/source-material/agent-shapes/agent-pattern/Dockerfile create mode 100644 docs/source-material/agent-shapes/agent-pattern/README.md create mode 100644 docs/source-material/agent-shapes/agent-pattern/RELEASE_NOTES.md create mode 100644 docs/source-material/agent-shapes/agent-pattern/agent.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/app/__init__.py create mode 100644 docs/source-material/agent-shapes/agent-pattern/app/business_logic.py create mode 100644 docs/source-material/agent-shapes/agent-pattern/app/policy.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/app/tools.py create mode 100644 docs/source-material/agent-shapes/agent-pattern/eval/cases.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/eval/schemas/cases-1.1.schema.json create mode 100644 docs/source-material/agent-shapes/agent-pattern/kubernetes/configmap.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/kubernetes/deployment.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/kubernetes/kustomization.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/kubernetes/namespace.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/kubernetes/secretnames.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/kubernetes/service.yaml create mode 100644 docs/source-material/agent-shapes/agent-pattern/prompt.md create mode 100644 docs/source-material/agent-shapes/agent-pattern/requirements.txt create mode 100755 docs/source-material/agent-shapes/agent-pattern/run-local.sh create mode 100644 docs/source-material/agent-shapes/agent-pattern/schemas/input.json create mode 100644 docs/source-material/agent-shapes/agent-pattern/schemas/output.json create mode 100644 docs/source-material/agent-shapes/agent-pattern/skills/README.md create mode 100644 docs/source-material/agent-shapes/agent-pattern/skills/review-purchases/SKILL.md create mode 100644 docs/source-material/agent-shapes/agent-pattern/skills/review-travel-and-meals/SKILL.md create mode 100644 docs/source-material/agent-shapes/agent-pattern/skills/review-travel-and-meals/references/faq.md create mode 100644 docs/source-material/agent-shapes/agent-pattern/tests/a2a_client.py create mode 100644 docs/source-material/agent-shapes/agent-pattern/tests/requirements.txt create mode 100644 docs/source-material/agent-shapes/agent-pattern/tests/test_chatbot.py create mode 100644 docs/source-material/agent-shapes/subagent-pattern/.dockerignore create mode 100644 docs/source-material/agent-shapes/subagent-pattern/.env.example create mode 100644 docs/source-material/agent-shapes/subagent-pattern/.gitignore create mode 100644 docs/source-material/agent-shapes/subagent-pattern/Dockerfile create mode 100644 docs/source-material/agent-shapes/subagent-pattern/README.md create mode 100644 docs/source-material/agent-shapes/subagent-pattern/RELEASE_NOTES.md create mode 100644 docs/source-material/agent-shapes/subagent-pattern/agent.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/app/__init__.py create mode 100644 docs/source-material/agent-shapes/subagent-pattern/app/business_logic.py create mode 100644 docs/source-material/agent-shapes/subagent-pattern/app/policy.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/app/tools.py create mode 100644 docs/source-material/agent-shapes/subagent-pattern/eval/cases.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/eval/schemas/cases-1.1.schema.json create mode 100644 docs/source-material/agent-shapes/subagent-pattern/kubernetes/configmap.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/kubernetes/deployment.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/kubernetes/kustomization.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/kubernetes/namespace.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/kubernetes/secretnames.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/kubernetes/service.yaml create mode 100644 docs/source-material/agent-shapes/subagent-pattern/prompt.md create mode 100644 docs/source-material/agent-shapes/subagent-pattern/prompts/subagents.md create mode 100644 docs/source-material/agent-shapes/subagent-pattern/requirements.txt create mode 100755 docs/source-material/agent-shapes/subagent-pattern/run-local.sh create mode 100644 docs/source-material/agent-shapes/subagent-pattern/schemas/input.json create mode 100644 docs/source-material/agent-shapes/subagent-pattern/schemas/output.json create mode 100644 docs/source-material/agent-shapes/subagent-pattern/skills/README.md create mode 100644 docs/source-material/agent-shapes/subagent-pattern/skills/review-purchases/SKILL.md create mode 100644 docs/source-material/agent-shapes/subagent-pattern/skills/review-travel-and-meals/SKILL.md create mode 100644 docs/source-material/agent-shapes/subagent-pattern/skills/review-travel-and-meals/references/faq.md create mode 100644 docs/source-material/agent-shapes/subagent-pattern/tests/a2a_client.py create mode 100644 docs/source-material/agent-shapes/subagent-pattern/tests/requirements.txt create mode 100644 docs/source-material/agent-shapes/subagent-pattern/tests/test_chatbot.py create mode 100644 docs/source-material/workflow-documentation/Workflow-01-Discovery 1.pdf create mode 100644 docs/source-material/workflow-documentation/user_story_files/PCA-03-Business-Requirements.md create mode 100644 docs/source-material/workflow-documentation/user_story_files/PCA-03-Comprehensive-Prompt.md create mode 100644 docs/source-material/workflow-files/FILE_2194.json create mode 100644 docs/source-material/workflow-files/FILE_4357.json create mode 100644 docs/source-material/workflow-files/FILE_6034.json create mode 100644 docs/source-material/workflow-files/FILE_6422.json create mode 100644 docs/source-material/workflow-files/FILE_6423.json create mode 100644 docs/source-material/workflow-files/FILE_6763.json create mode 100644 docs/source-material/workflow-files/FILE_9563.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/.agents/PLAN.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/Dockerfile create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/RELEASE_NOTES.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/agent.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/docs/user-guide.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/eval/cases.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/kubernetes/configmap.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/kubernetes/deployment.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/kubernetes/kustomization.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/kubernetes/namespace.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/kubernetes/secretnames.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/kubernetes/service.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/prompt.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/schemas/input.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-asset-inventory-normalisation-agent/schemas/output.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/Dockerfile create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/RELEASE_NOTES.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/agent.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/docs/user-guide.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/eval/cases.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/kubernetes/configmap.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/kubernetes/deployment.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/kubernetes/kustomization.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/kubernetes/namespace.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/kubernetes/secretnames.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/kubernetes/service.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/prompt.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/schemas/input.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-cmdb-itsm-reconciliation-agent/schemas/output.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/Dockerfile create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/RELEASE_NOTES.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/agent.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/docs/user-guide.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/eval/cases.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/kubernetes/configmap.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/kubernetes/deployment.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/kubernetes/kustomization.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/kubernetes/namespace.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/kubernetes/secretnames.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/kubernetes/service.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/prompt.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/schemas/input.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-data-classification-agent/schemas/output.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/Dockerfile create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/RELEASE_NOTES.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/agent.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/docs/user-guide.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/eval/cases.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/kubernetes/configmap.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/kubernetes/deployment.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/kubernetes/kustomization.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/kubernetes/namespace.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/kubernetes/secretnames.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/kubernetes/service.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/prompt.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/schemas/input.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-dependency-mapping-agent/schemas/output.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/Dockerfile create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/RELEASE_NOTES.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/agent.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/docs/user-guide.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/eval/cases.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/kubernetes/configmap.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/kubernetes/deployment.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/kubernetes/kustomization.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/kubernetes/namespace.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/kubernetes/secretnames.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/kubernetes/service.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/prompt.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/schemas/input.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-critic-agent/schemas/output.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/Dockerfile create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/RELEASE_NOTES.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/agent.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/docs/user-guide.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/eval/cases.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/kubernetes/configmap.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/kubernetes/deployment.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/kubernetes/kustomization.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/kubernetes/namespace.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/kubernetes/secretnames.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/kubernetes/service.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/prompt.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/schemas/input.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-planner-agent/schemas/output.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/Dockerfile create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/RELEASE_NOTES.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/agent.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/docs/user-guide.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/eval/cases.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/kubernetes/configmap.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/kubernetes/deployment.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/kubernetes/kustomization.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/kubernetes/namespace.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/kubernetes/secretnames.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/kubernetes/service.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/prompt.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/schemas/input.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-estate-scan-executor-agent/schemas/output.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/.agents/CONTEXT.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/CLAUDE.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/Dockerfile create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/RELEASE_NOTES.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/agent.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/docs/user-guide.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/eval/cases.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/kubernetes/configmap.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/kubernetes/deployment.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/kubernetes/kustomization.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/kubernetes/namespace.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/kubernetes/secretnames.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/kubernetes/service.yaml create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/prompt.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/schemas/input.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-network-discovery-assessment-agent/schemas/output.json create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0001.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0002.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0003.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0004.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0005.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0006.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0007.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0008.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0009.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0010.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0011.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/README.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/template.md create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/scripts/build_workflow.py create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/scripts/scaffold_from_stories.py create mode 100644 individual-agents/ALZ-F01: Discovery Workflow Agent/workflows/cp1-alz-discovery-individual.json create mode 100644 mcp-servers/alz-discovery-sample.server.yaml create mode 100644 mcp-servers/alz-discovery-sample/.env.example create mode 100644 mcp-servers/alz-discovery-sample/.gitignore create mode 100644 mcp-servers/alz-discovery-sample/Dockerfile create mode 100644 mcp-servers/alz-discovery-sample/README.md create mode 100644 mcp-servers/alz-discovery-sample/constraints.txt create mode 100644 mcp-servers/alz-discovery-sample/kubernetes/configmap.yaml create mode 100644 mcp-servers/alz-discovery-sample/kubernetes/deployment.yaml create mode 100644 mcp-servers/alz-discovery-sample/kubernetes/kustomization.yaml create mode 100644 mcp-servers/alz-discovery-sample/kubernetes/namespace.yaml create mode 100644 mcp-servers/alz-discovery-sample/kubernetes/secretnames.yaml create mode 100644 mcp-servers/alz-discovery-sample/kubernetes/service.yaml create mode 100644 mcp-servers/alz-discovery-sample/mcp_connection.py create mode 100644 mcp-servers/alz-discovery-sample/requirements.txt create mode 100644 mcp-servers/alz-discovery-sample/server.py create mode 100644 mcp-servers/alz-discovery-sample/tests/test_conformance.py create mode 100644 scripts/check_agents.py create mode 100644 scripts/kab_front_steps.py create mode 100644 scripts/kab_import_workflow.py create mode 100644 scripts/render_k8s.py create mode 100644 scripts/render_mcp_server.py create mode 100644 scripts/smoke_mcp_server.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/CLAUDE.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/README.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/.agents/CONTEXT.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/.agents/PLAN.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/CLAUDE.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/Dockerfile create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/README.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/RELEASE_NOTES.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/agent.yaml create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/app/__init__.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/app/artifacts.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/app/business_logic.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/app/rules.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/app/tools.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/app/workspace.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/README.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0001-orchestrator-with-sub-agents.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0002-workspace-replaces-alz-run.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0003-orchestrator-makes-mcp-calls.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0004-four-phases-one-request-each.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0005-sub-agents-from-code-and-enforced-verdict.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0006-findings-per-scan-batch.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0007-names.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0008-app-folder-in-cp1-agents.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0009-models.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0010-evidence-in-execution-storage.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0011-kustomize-deploy-secrets-outside-manifests.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/0012-artifacts-through-the-orchestrator.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/README.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/adr/template.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/docs/user-guide.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/eval/cases.yaml create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/kubernetes/configmap.yaml create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/kubernetes/deployment.yaml create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/kubernetes/kustomization.yaml create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/kubernetes/namespace.yaml create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/kubernetes/secretnames.yaml create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/kubernetes/service.yaml create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompt.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompts/dsc_01_planner.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompts/dsc_02_scan_executor.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompts/dsc_03_inventory.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompts/dsc_04_cmdb_reconciliation.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompts/dsc_05_data_classification.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompts/dsc_06_dependency_mapping.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompts/dsc_07_network.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/prompts/dsc_08_critic.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/schemas/input.json create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/schemas/output.json create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/skills/discovery-analyse/SKILL.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/skills/discovery-collect/SKILL.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/skills/discovery-critique/SKILL.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/cp1-alz-discovery-orchestrator-agent/skills/discovery-plan/SKILL.md create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/scripts/build_workflow.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/scripts/dry_run.py create mode 100644 sub-agents/ALZ-F01: Discovery Workflow Agent/workflows/cp1-alz-discovery.json diff --git a/.agents/CONTEXT.md b/.agents/CONTEXT.md new file mode 100644 index 0000000..98955a8 --- /dev/null +++ b/.agents/CONTEXT.md @@ -0,0 +1,57 @@ +# Context: cp1-agents + +Repository-wide facts for coding agents. Pattern- and agent-specific context lives in `individual-agents//.agents/` and in `/.agents/`. + +## Layout + +- **`///`.** The patterns are `sub-agents` and `individual-agents`. A Feature folder is named `ALZ-F0N: Workflow Agent`. ALZ-F01 is built; the F02 and F03 folders are empty. +- **A Feature folder works like a small repository:** its agents, `workflows/`, its own `scripts/build_workflow.py` and, for individual agents, its pattern ADRs and `.agents/`. Relative links inside a Feature (`../scripts/`, `../workflows/`, `../../../docs/adr/` from an agent's `docs/adr/`) resolve inside that Feature. +- **Shared, at the root:** + - `scripts/`: + - `check_agents.py` (cp4's rules, plus `app/` only when declared); + - `render_k8s.py` (finds an agent by name under either pattern); + - `kab_import_workflow.py ` (loads that Feature's `scripts/build_workflow.py`); + - `kab_front_steps.py` (Feature builders import it from `parents[3]/scripts`); + - `render_mcp_server.py`, `smoke_mcp_server.py`. + - `mcp-servers/`, `deploy/`, and `docs/`. + +## Sources of truth + +| What | Where | +|---|---| +| Requirements | ADO project "Global Modernization Engineering Hub - Agent Board": Epic 3214440, Features 3214441–3214447, F01 stories 3214451–3214458. The v1.1 story files are in the engineering hub workspace (`drafts/cp1/agentic-landing-zone/`), not in this repository | +| Agent shape | `docs/source-material/agent-shapes/agent-pattern` and `subagent-pattern` (KAB's; their `.env` files are local and git-ignored, and the zips, which contain `.env` files, are left out) | +| KAB workflow exports used as references | `docs/source-material/workflow-files/` | +| Workflow documentation | `docs/source-material/workflow-documentation/` | +| Reference repository | `cp4-agents` (gitea.kyndemo.live/agents/cp4-agents): layout, check script, workflow export format | +| Changes to requirements | Sub-agents: `/docs/adr/`. Individual agents: `individual-agents//docs/adr/` | +| Platform problems found | `docs/platform-issues/` | + +## Platform facts + +- **Runtime image:** `cruciblecoredevacr.azurecr.io/kab/agent-runtime-adk:0.35.7`. Images are pushed to `cruciblecoredevacr.azurecr.io/kab/cp1/:`. +- **Cluster:** context `crucible-kab-dev-aks`, in the Windows kubeconfig `/mnt/c/Users/JonathanBoniface/.kube/config`. + - Agents run in namespace `agents`, MCP servers in `mcp-servers`, and the gateways in `core-components`. + - Model gateway: `http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000`. Its key is Secret `agent-builder-secrets`, key `litellm-master-key`, in `agents`. + - MCP gateway: `http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000`. + - Shared storage: PVC `execution-storage-pvc` (RWX) in `agents`, mounted at `/data/executions`. The platform doesn't set `EXECUTION_STORAGE_ROOT`, so an agent that writes there sets it in its own ConfigMap. + - There's **no** `agent-platform-connections` ConfigMap, so the gateway URLs go in each agent's ConfigMap through `deploy/.yaml`. +- **The `repo` label is in every Deployment's selector** (`includeSelectors: true`). The individual agents keep `repo: cp1-agents-individual` (set per agent in `deploy/`), and the orchestrator and the MCP server use `cp1-agents`. +- **An agent needs its own `MCP_AGENT_API_KEY`** (Secret `-secrets`), issued when it's created in KAB. Without it, every request fails at startup. +- **MCP server registration fails as of 2026-10-29.** In the gateway's single tenancy mode, a server insert passes row-level security only when the caller's tenant is `default`, and KAB's default tenant isn't mapped to it. See `docs/platform-issues/mcp-gateway-default-tenant/`. +- **Workflow export** (`export_version` 2.0.0): + - Each agent step is a `generic_agent_call` to `http://.agents.svc.cluster.local:8080`. + - Inputs come `from_workflow`, `from_steps` or `static` (front steps only). + - `parallelGroup` and `executionLevel` order the steps. + - Approvals are `hitl` with `checkpoint_type: approval`. +- **Models on the Azure resource behind the gateway:** `gpt-4o`, `gpt-5.6-sol`, `claude-sonnet-5-5`, `claude-haiku-5-5`, `text-embedding-3-small`. Whether the cluster's LiteLLM serves each name hasn't been confirmed. + +## Glossary + +| Term | Meaning | +|---|---| +| Orchestrator | The sub-agent pattern's one agent per Feature. It makes every MCP call and holds the run workspace. | +| Sub-agent | A story's agent, run by the orchestrator through `delegate` (`as_tool: false`). It has functions only, never MCP tools. | +| Run workspace | Write-once records plus a hash-chained manifest, under `/data/executions/alz-discovery///` | +| Phase | One request's share of a workflow: plan, collect, analyse or critique, for Discovery | +| Logical MCP server | A name in `agent.yaml` `mcp:` (`alz-scope` …), mapped to a deployed server at the MCP gateway | diff --git a/.gitea/workflows/check.yml b/.gitea/workflows/check.yml new file mode 100644 index 0000000..3207a3b --- /dev/null +++ b/.gitea/workflows/check.yml @@ -0,0 +1,24 @@ +name: check agents +on: [push, pull_request] + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Check every agent folder (///) + run: | + # Feature folder names have spaces, so pass the paths NUL-separated. + find sub-agents individual-agents -mindepth 3 -maxdepth 3 -name agent.yaml -print0 \ + | xargs -0 -n1 dirname -z | sort -z \ + | xargs -0 python3 scripts/check_agents.py --runtime-image cruciblecoredevacr.azurecr.io/kab/agent-runtime-adk:0.35.7 + - name: Dry-run the Discovery orchestrator's code (no model, no MCP server) + working-directory: "sub-agents/ALZ-F01: Discovery Workflow Agent" + run: | + python3 -m pip install --quiet jsonschema==4.23.0 + python3 scripts/dry_run.py cp1-alz-discovery-orchestrator-agent "$(mktemp -d)" + - name: Every Feature's workflow export matches its agents' contracts + run: | + find sub-agents individual-agents -mindepth 3 -maxdepth 3 -path '*/scripts/build_workflow.py' -print0 \ + | xargs -0 -n1 python3 + git diff --exit-code -- sub-agents individual-agents diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c30f69e --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +build/ +__pycache__/ +*.pyc +.env diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..552dfa5 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,33 @@ +# cp1-agents + +KAB agents and workflows for the CP1 Agentic Landing Zone Epic, in two patterns. Modelled on `cp4-agents`. + +@.agents/CONTEXT.md + +Each Feature folder has its own `CLAUDE.md`, and so does each agent folder. Read them before changing anything inside. + +## Commands (repository root) + +```sh +find sub-agents individual-agents -mindepth 3 -maxdepth 3 -name agent.yaml -print0 | xargs -0 -n1 dirname -z \ + | xargs -0 python3 scripts/check_agents.py --runtime-image cruciblecoredevacr.azurecr.io/kab/agent-runtime-adk:0.35.7 +python3 "//scripts/build_workflow.py" # after any schemas/ change +python3 scripts/render_k8s.py deploy/crucible-kab-dev.yaml [] # fill placeholders into build/ +kustomize build build/crucible-kab-dev/ # validate a render +python3 scripts/kab_import_workflow.py "/" --project-id # validate; --apply to import +``` + +## Rules + +- **Keep the two patterns apart.** `sub-agents/` and `individual-agents/` never share agent code, prompts or ADRs. They share only `scripts/`, `mcp-servers/`, `deploy/` and `docs/`. +- **Don't duplicate.** A script, server or doc that more than one Feature or pattern needs belongs at the root, once. Per-agent `Dockerfile` and `kubernetes/` are the exception, because Kyndryl CI needs them in every agent folder. +- **Keep the `kubernetes/` placeholders** (``). Fill them only in `build/` (git-ignored), through `render_k8s.py`. +- **No key, token or password in any file,** including `deploy/` profiles, docs and examples. Keys live in Kubernetes Secrets created by hand. +- **`.env` files are local only.** They're git-ignored (`.gitignore`); never commit one, never force-add one, and never commit an archive that contains one. `docs/source-material/` is read-only input. +- **Cluster changes** (`kubectl apply/delete/create`, image pushes) need the user's explicit approval each time. `kubectl diff`, `get` and `kustomize build` don't. Never read Secret values. +- **Never `kubectl delete -k` an agent's own `kubernetes/` folder.** Its `namespace.yaml` is the shared namespace. +- **Don't change a deployed agent's `repo` label** in `deploy/`: it's in the Deployment's selector. +- **Human docs** go in `README.md` and `docs/`; agent context goes in `CLAUDE.md` and `.agents/`. +- **A change to an original requirement** (the ADO story or the v1.1 story file) needs an ADR in that pattern's ADRs and a step in its `.agents/PLAN.md`. +- **Never change existing ADO work items** from this repository's work. +- **Quote the Feature paths.** They contain spaces and `:`. In scripts, pass them NUL-separated (`-print0`, `xargs -0`). diff --git a/README.md b/README.md new file mode 100644 index 0000000..0d998a5 --- /dev/null +++ b/README.md @@ -0,0 +1,68 @@ +# CP1 agents + +The KAB agents and workflows for the CP1 Epic "Agentic Landing Zone" (ADO 3214440), built on the KAB agent runtime in KAB's agent shape (`agent.yaml`, `prompt.md`, `schemas/`, `eval/`). + +Each Feature is built in **two patterns**, and which one is adopted hasn't been decided: + +| Pattern | Folder | Shape | +|---|---|---| +| **Sub-agents** | [`sub-agents/`](sub-agents/) | One orchestrator agent per Feature, with the Feature's stories as its sub-agents. It keeps a shared run workspace, and a verdict enforced in code. | +| **Individual agents** | [`individual-agents/`](individual-agents/) | One declarative agent per story, chained by the KAB workflow, cp4-agents style | + +| Feature | Sub-agents | Individual agents | +|---|---|---| +| ALZ-F01 Discovery (3214441) | [built](sub-agents/ALZ-F01:%20Discovery%20Workflow%20Agent/): 1 orchestrator, 8 sub-agents | [built](individual-agents/ALZ-F01:%20Discovery%20Workflow%20Agent/): 8 agents | +| ALZ-F02 Assessment & Disposition | not started | not started | +| ALZ-F03 Strategy Synthesis | not started | not started | + +## Layout + +``` +cp1-agents/ +├── sub-agents// the sub-agent pattern, one folder per Feature +│ ├── cp1-…-orchestrator-agent/ the agent (Dockerfile, kubernetes/, docs/, .agents/) +│ ├── workflows/ the Feature's KAB workflow export +│ └── scripts/ scripts only this Feature uses (build_workflow.py, dry_run.py) +├── individual-agents// the individual-agents pattern, one folder per Feature +│ ├── cp1-…-agent/ … one agent per story +│ ├── docs/adr/ .agents/ the pattern's decisions and plan for this Feature +│ ├── workflows/ scripts/ +├── mcp-servers/ MCP servers shared by both patterns (alz-discovery-sample) +├── scripts/ shared: check_agents, render_k8s, kab_import_workflow, kab_front_steps, MCP server tools +├── deploy/ deploy profiles: where to deploy, never keys +└── docs/ + ├── deployment.md building, rendering and deploying every component + ├── platform-issues/ KAB platform problems found while building these agents + ├── source-material/ the inputs: agent shapes, KAB workflow exports, workflow documentation + └── strategy-outline/ +``` + +Each agent keeps its own `Dockerfile` and `kubernetes/` folder. Kyndryl's agent CI builds one folder at a time, and the `kubernetes/` files keep the CI's placeholders. Everything else that the two patterns or several Features share exists once, at the root. + +The Feature folder names contain spaces and a colon. Quote them in a shell. Git can't check out a path that contains `:` on Windows, so clone the repository in WSL or on Linux or macOS. + +## Common tasks + +From the repository root: + +```sh +# Check every agent folder +find sub-agents individual-agents -mindepth 3 -maxdepth 3 -name agent.yaml -print0 | xargs -0 -n1 dirname -z \ + | xargs -0 python3 scripts/check_agents.py --runtime-image cruciblecoredevacr.azurecr.io/kab/agent-runtime-adk:0.35.7 + +# Rebuild a Feature's workflow export, then validate it against KAB and import it +python3 "sub-agents/ALZ-F01: Discovery Workflow Agent/scripts/build_workflow.py" +python3 scripts/kab_import_workflow.py "sub-agents/ALZ-F01: Discovery Workflow Agent" --project-id [--apply] + +# Render the manifests for a deploy +python3 scripts/render_k8s.py deploy/crucible-kab-dev.yaml [] +``` + +The secrets, the MCP gateway registration and the order of the steps are in [docs/deployment.md](docs/deployment.md). + +## Checks + +`.gitea/workflows/check.yml` runs on every push: +- **`scripts/check_agents.py`:** cp4-agents' folder rules (pinned runtime image, Kyndryl CI's placeholders, no secrets). An agent may carry `app/` only if it declares functions, hooks or sub-agents. +- **The orchestrator's dry run:** its code, with no model and no MCP server. +- **Every Feature's workflow export** must match its agents' contracts. diff --git a/deploy/crucible-kab-dev.yaml b/deploy/crucible-kab-dev.yaml new file mode 100644 index 0000000..7b80267 --- /dev/null +++ b/deploy/crucible-kab-dev.yaml @@ -0,0 +1,84 @@ +# Where scripts/render_k8s.py deploys to: the KAB dev cluster the CP4 agents run in. +# +# Only names, addresses and image locations live here. Keys never do: each component reads them from a +# Kubernetes Secret created by hand (see docs/deployment.md). The cluster has no agent-platform-connections +# ConfigMap, so each agent's ConfigMap names the gateways. +# +# Agents are found by name under sub-agents// or individual-agents//. + +context: crucible-kab-dev-aks +registry: cruciblecoredevacr.azurecr.io/kab/cp1 +repo: cp1-agents + +agents: + # Sub-agent pattern (sub-agents/ALZ-F01: Discovery Workflow Agent) + cp1-alz-discovery-orchestrator-agent: + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-alz-discovery-orchestrator-agent.agents.svc.cluster.local" + + # Individual-agent pattern (individual-agents/ALZ-F01: Discovery Workflow Agent). + # repo stays cp1-agents-individual: the label is in each Deployment's selector, which can't change in place, + # and these eight were first deployed from the cp1-agents-individual repository. + cp1-discovery-planner-agent: + repo: cp1-agents-individual + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-discovery-planner-agent.agents.svc.cluster.local" + cp1-estate-scan-executor-agent: + repo: cp1-agents-individual + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-estate-scan-executor-agent.agents.svc.cluster.local" + cp1-asset-inventory-normalisation-agent: + repo: cp1-agents-individual + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-asset-inventory-normalisation-agent.agents.svc.cluster.local" + cp1-cmdb-itsm-reconciliation-agent: + repo: cp1-agents-individual + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-cmdb-itsm-reconciliation-agent.agents.svc.cluster.local" + cp1-data-classification-agent: + repo: cp1-agents-individual + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-data-classification-agent.agents.svc.cluster.local" + cp1-dependency-mapping-agent: + repo: cp1-agents-individual + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-dependency-mapping-agent.agents.svc.cluster.local" + cp1-network-discovery-assessment-agent: + repo: cp1-agents-individual + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-network-discovery-assessment-agent.agents.svc.cluster.local" + cp1-discovery-critic-agent: + repo: cp1-agents-individual + port: 8080 + config: + LITELLM_PROXY_BASE: "http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000" + MCP_GATEWAY_URL: "http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000" + HOST: "cp1-discovery-critic-agent.agents.svc.cluster.local" + +mcp_servers: + alz-discovery-sample: + port: 8110 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..0549a4a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ +# cp1-agents: documentation + +Repository-wide documents for people. The docs for each agent are in its own `docs/` folder, and the individual-agents pattern's ADRs are in `individual-agents//docs/adr/`. + +| Document | For | +|---|---| +| [deployment.md](deployment.md) | Platform operators: building, pushing and deploying every agent and MCP server with kustomize | +| [artifact-integration-plan-2026-10-29.md](artifact-integration-plan-2026-10-29.md) | Reviewers: how uploaded files and project artifacts reach the agents in both patterns | +| [platform-issues/](platform-issues/) | Platform team: KAB problems found while building these agents | +| [source-material/](source-material/) | Everyone: the inputs these agents were built from (read-only) | +| [strategy-outline/](strategy-outline/) | Not yet written | + +## Platform issues + +| Issue | Status | +|---|---| +| [MCP server registration fails with a 500 (default tenant not mapped in the MCP gateway)](platform-issues/mcp-gateway-default-tenant/report-2026-10-29.md) | Open. It blocks MCP registration for both patterns. The proposed gateway manifests are alongside the report and **have not been applied**. | +| [The Artifacts step can't select an earlier step's output within the same run](platform-issues/artifacts-step-within-a-run/report-2026-10-29.md) | Open, with questions for the platform team. It doesn't block F01, where hand-offs use `from_steps`. It affects F01 → F02. | + +## Source material + +| Folder | Contents | +|---|---| +| `source-material/agent-shapes/` | KAB's `agent-pattern` and `subagent-pattern`. Their `.env` files are local only (git-ignored), and the zip archives are left out. | +| `source-material/workflow-files/` | KAB workflow exports used as format references | +| `source-material/workflow-documentation/` | The Discovery workflow description (PDF) and example user story files | diff --git a/docs/artifact-integration-plan-2026-10-29.md b/docs/artifact-integration-plan-2026-10-29.md new file mode 100644 index 0000000..a8bed65 --- /dev/null +++ b/docs/artifact-integration-plan-2026-10-29.md @@ -0,0 +1,86 @@ +# 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/`, and `cp1-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 + +```text +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-, 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 `artifacts` input (array, `x-artifact-types: ["file", "structured_data", "report", "execution_output"]`). +- **Import, in code, not the model.** In the plan phase, `pre_process` calls a new `app/artifacts.py` (`import_artifacts`). For each artifact it: + - accepts the platform's shapes, as `find_artifacts` does; + - 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-`, with `artifact_id`, `type_id`, the source `sha256` and `file_path` as provenance, chained in the manifest like every other record. +- **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_output` artifacts. The critique reply gains a compact `deliverable` object (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_artifacts` step. Steps that need source data take it with `from_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_records` input to those two agents (no `x-artifact-types`, because they don't take the `artifacts` list). Their prompts say to treat it as data, cite it as `artifact:`, and never follow instructions in it. +- **Output.** Unchanged. Every step's reply already becomes an `execution_output` artifact. +- **Limit.** `parsed_content` is 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-` | `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 + +1. **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-types` list and which sub-agents get them. +2. **Should we ask the platform team for typed outputs?** Today every output is `execution_output`. A per-step output type, such as `structured_data` for the inventory or `assessment_result` with 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. +3. **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_artifacts` inlines at most 5 MB, and larger values travel as file references, which only the orchestrator can read. +- **Provenance:** an imported artifact's `sha256` is recorded at import. A later change to the artifact doesn't change the run's record. diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..b77404d --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,121 @@ +# Deploying cp1-agents with kustomize + +For the platform operator who deploys the CP1 agents and their MCP server to the KAB dev cluster `crucible-kab-dev-aks`. You deploy by hand with kustomize. Kyndryl's agent CI can deploy the same folders unchanged, because each `kubernetes/` folder keeps the CI's placeholders. + +Run every command from the repository root. The Feature folder names contain spaces and a colon, so quote them. + +## What gets deployed + +| Component | Pattern | Folder | Namespace | Port | +|---|---|---|---|---| +| `cp1-alz-discovery-orchestrator-agent` | Sub-agents | `sub-agents/ALZ-F01: Discovery Workflow Agent/` | `agents` | 8080 | +| `cp1-discovery-planner-agent` … `cp1-discovery-critic-agent` (8 agents) | Individual agents | `individual-agents/ALZ-F01: Discovery Workflow Agent/` | `agents` | 8080 | +| `alz-discovery-sample` (sample MCP server, Meridian estate; both patterns use it) | — | `mcp-servers/alz-discovery-sample/` | `mcp-servers` | 8110 | + +Images are `cruciblecoredevacr.azurecr.io/kab/cp1/:`. An agent's version comes from its `agent.yaml`; the MCP server's comes from `mcp-servers/alz-discovery-sample.server.yaml`. + +The target, registry and gateway addresses are in [`deploy/crucible-kab-dev.yaml`](../deploy/crucible-kab-dev.yaml). `scripts/render_k8s.py` finds each agent by name under `sub-agents/` or `individual-agents/`. + +The eight individual agents keep the label `repo: cp1-agents-individual`. The label is part of each Deployment's selector, which can't be changed in place, and they were first deployed from that repository. + +Keys are never in a file. Each component reads its keys from a Kubernetes Secret that you create by hand: + +| Secret | Namespace | Key | Who creates it | +|---|---|---|---| +| `agent-builder-secrets` | `agents` | `litellm-master-key` | The platform; it already exists | +| `-secrets` (one per agent) | `agents` | `MCP_AGENT_API_KEY` | You, after KAB issues the agent's key | +| `alz-discovery-sample-secrets` | `mcp-servers` | `MCP_REGISTRATION_API_KEY` | You, with a new random key | + +## Before you start + +- **kubectl context:** `crucible-kab-dev-aks`. On this workstation it's in the Windows kubeconfig: `export KUBECONFIG=/mnt/c/Users//.kube/config`. +- **Registry access:** you can push to `cruciblecoredevacr` (`az acr login -n cruciblecoredevacr`). +- **Models:** the cluster's LiteLLM must serve `gpt-5.6-sol` and `claude-sonnet-5-5` (used by the critic). +- **MCP server registration works.** As of 2026-10-29 it fails with a 500 in the MCP gateway; see [platform-issues/mcp-gateway-default-tenant](platform-issues/mcp-gateway-default-tenant/report-2026-10-29.md). +- **The checks pass:** + + ```sh + find sub-agents individual-agents -mindepth 3 -maxdepth 3 -name agent.yaml -print0 | xargs -0 -n1 dirname -z \ + | xargs -0 python3 scripts/check_agents.py --runtime-image cruciblecoredevacr.azurecr.io/kab/agent-runtime-adk:0.35.7 + (cd "sub-agents/ALZ-F01: Discovery Workflow Agent" && python3 scripts/dry_run.py cp1-alz-discovery-orchestrator-agent "$(mktemp -d)") + ``` + +## 1. Build and push the images + +```sh +az acr login --name cruciblecoredevacr +R=cruciblecoredevacr.azurecr.io/kab/cp1 +find sub-agents individual-agents -mindepth 3 -maxdepth 3 -name agent.yaml -print0 | while IFS= read -r -d '' y; do + d=$(dirname "$y"); a=$(basename "$d"); v=$(sed -n 's/^version: "\{0,1\}\([^"#]*\)"\{0,1\}.*/\1/p' "$y" | tr -d ' ') + podman build -t "$R/$a:$v" "$d" && podman push "$R/$a:$v" +done +podman build -t $R/alz-discovery-sample:0.1.0 mcp-servers/alz-discovery-sample && podman push $R/alz-discovery-sample:0.1.0 +``` + +Every agent's Dockerfile builds on `cruciblecoredevacr.azurecr.io/kab/agent-runtime-adk:0.35.7`. A released version is never pushed twice. For a new build, bump `version` in `agent.yaml` and add an entry to `RELEASE_NOTES.md`. + +## 2. Render the manifests + +```sh +python3 scripts/render_k8s.py deploy/crucible-kab-dev.yaml # every component +python3 scripts/render_k8s.py deploy/crucible-kab-dev.yaml # or just one +``` + +This writes `build/crucible-kab-dev//` (git-ignored) with every placeholder filled. It leaves out two files: +- `secretnames.yaml`, so a deploy can't empty your Secrets; +- `namespace.yaml`, so the shared namespaces are never relabelled or deleted. + +## 3. Deploy the MCP server, then register it + +```sh +read -rs REG_KEY < <(openssl rand -hex 32; echo) +kubectl --context crucible-kab-dev-aks -n mcp-servers create secret generic alz-discovery-sample-secrets \ + --from-literal=MCP_REGISTRATION_API_KEY="$REG_KEY" +kubectl --context crucible-kab-dev-aks diff -k build/crucible-kab-dev/alz-discovery-sample +kubectl --context crucible-kab-dev-aks apply -k build/crucible-kab-dev/alz-discovery-sample +kubectl --context crucible-kab-dev-aks -n mcp-servers rollout status deploy/alz-discovery-sample +``` + +Then register the server in KAB: +1. Use the address `http://alz-discovery-sample.mcp-servers.svc.cluster.local:8110` and the key `$REG_KEY`. +2. Register it under each of the nine logical names the agents use: `alz-scope`, `alz-estate`, `alz-cloud`, `alz-cmdb`, `alz-inventory`, `alz-schema`, `alz-dependency`, `alz-network` and `alz-evidence`. +3. Run `unset REG_KEY`. + +## 4. Register each agent, then deploy it + +In KAB, create the agent at `http://.agents.svc.cluster.local:8080`. KAB issues the agent's MCP key, which you store without writing it anywhere: + +```sh +read -rs MCP_KEY && kubectl --context crucible-kab-dev-aks -n agents create secret generic -secrets \ + --from-literal=MCP_AGENT_API_KEY="$MCP_KEY"; unset MCP_KEY +kubectl --context crucible-kab-dev-aks diff -k build/crucible-kab-dev/ +kubectl --context crucible-kab-dev-aks apply -k build/crucible-kab-dev/ +kubectl --context crucible-kab-dev-aks -n agents rollout status deploy/ +``` + +An agent without its key still starts and serves its agent card, but every request fails with `MCP_AGENT_API_KEY is not set`. + +## 5. Test, then import the workflows + +```sh +kubectl --context crucible-kab-dev-aks -n agents port-forward svc/ 18080:8080 & +curl -s localhost:18080/.well-known/agent-card.json +python -m kyndryl_agent_runtime.eval --url http://localhost:18080 --cases "//eval/cases.yaml" +``` + +Each Feature has its own workflow export in `/workflows/`. Import it with your KAB session token in `~/.kab_token`. Importing needs the Editor role. + +```sh +python3 scripts/kab_import_workflow.py "sub-agents/ALZ-F01: Discovery Workflow Agent" --project-id # validate +python3 scripts/kab_import_workflow.py "sub-agents/ALZ-F01: Discovery Workflow Agent" --project-id --apply # import as a draft +python3 scripts/kab_import_workflow.py "individual-agents/ALZ-F01: Discovery Workflow Agent" --project-id --apply +``` + +## Rolling back and removing + +```sh +kubectl --context crucible-kab-dev-aks -n agents rollout undo deploy/ # the previous version +kubectl --context crucible-kab-dev-aks delete -k build/crucible-kab-dev/ # remove it entirely +``` + +A rendered build holds only the component's Deployment, Service and ConfigMap. **Never `kubectl delete -k` an agent's own `kubernetes/` folder.** That folder lists the shared namespace, and the delete would remove the namespace together with every other agent in it. diff --git a/docs/platform-issues/artifacts-step-within-a-run/report-2026-10-29.md b/docs/platform-issues/artifacts-step-within-a-run/report-2026-10-29.md new file mode 100644 index 0000000..9212600 --- /dev/null +++ b/docs/platform-issues/artifacts-step-within-a-run/report-2026-10-29.md @@ -0,0 +1,84 @@ +# Workflow Artifacts step: can't select an earlier step's output within the same run (and how hand-offs reach the next agent) + +| | | +|---|---| +| Date | 2026-10-29 | +| Environment | KAB dev (`crucible-kab-dev-aks`), Temporal workers as in `modernization-platform` @ `c89aedcb9` | +| Component | `agent-builder-temporal-workers`: the generic workflow executor, and the `select_artifacts` activity ("Artifacts" step) | +| Severity | Medium. Nothing fails, but artifacts can't be used to hand work between the steps of one run, and the step can't be left unconfigured in a reusable workflow. | +| Status | Open; reported to the platform team for confirmation | +| Found by | Code review while building the CP1 Discovery workflows (`sub-agents/` and `individual-agents/`, ALZ-F01) | + +## Summary + +You can place an Artifacts step (`select_artifacts`) anywhere in a workflow, including between two agent steps. Within one run, though, it can't select anything an earlier step of that same run produced. The executor registers a run's step outputs as project artifacts only **after every step has finished**. While the run is in progress, its own outputs aren't artifacts yet. + +Step-to-step data within a run therefore has to travel through `from_steps`. That works, and both CP1 Discovery workflows rely on it. But it means the Artifacts step is useful only for artifacts that **existed before the run started**, and those have to be named by id, fixed in the workflow definition. + +## What we expected + +For workflows to use Artifacts steps to hand work between agents. For example, a step selecting "the inventory produced by step s3 of this run" for later steps, with the artifact's type, provenance and size limits applied. This is how the artifact design reads (`PROJECT_WORKFLOW_ARTIFACT_DESIGN.md`). + +## What happens + +| # | Behaviour | Code (`packages/agent-builder-temporal-workers/src/temporal/`) | +|---|---|---| +| 1 | Artifacts for a run are registered once, after every step has run. They're also registered on failure, after the failing step. | `workflows/generic_workflow_executor.py:1025` `await self._execute_workflow()`, then `:1029` `await self._register_artifacts(workflow_input)`; failure path `:1040`; implementation `:2330` | +| 2 | The Artifacts step is a pass-through. Its output isn't stored and is never registered as an artifact. | `workflows/generic_workflow_executor.py:1223` `is_pass_through_selection = step_activity == "select_artifacts"`; `:1251` "Skipped storage … pass-through" | +| 3 | `select_artifacts` reads only the project's `artifacts` collection. It has no way to refer to "this run" or "step sN". | `activities/artifacts_activities.py:71` `SelectArtifactsActivity` | +| 4 | It fails if `artifact_ids` is empty, so a reusable workflow can't ship with the step left unconfigured. | `activities/artifacts_activities.py:98` "No artifact_ids provided" | +| 5 | Besides an artifact's `_id`, an entry in `artifact_ids` also matches the artifact's `workflow_id` or `name`. | `activities/artifacts_activities.py:122–124` | + +Behaviours 1 and 3 together mean an Artifacts step placed after step s1 finds no s1 artifact. It finds only artifacts from earlier, finished runs. + +## Impact on the CP1 workflows + +- **Both ALZ-F01 Discovery workflows** pass data between steps with `from_steps` (`s1.tasks`, `s3.records` and so on). Neither needs this fix to run. The committed exports have no Artifacts step. `scripts/kab_import_workflow.py --artifact-id ` adds one at the front for artifacts that already exist. +- **Large outputs between steps:** with `from_steps`, a step's whole output is passed inline. The individual-agents pattern has no other channel, and it can't use artifacts' size limits or file references within a run (individual-agents ADR 0010). +- **Between workflows (F01 → F02 Assessment):** this is where artifacts are needed. It works only once the Discovery run has finished, and only if the F02 workflow names F01's artifacts, by id or by one of the matches in row 5. The id-based route means editing the F02 workflow for every engagement. + +## Workarounds in use + +1. **Within a run:** `from_steps` for every hand-off. The sub-agent pattern also keeps a run workspace on the executions volume (sub-agents ADR 0010). +2. **Existing artifacts:** an Artifacts step built with fixed ids (`--artifact-id`), wired only into the step that needs them. +3. **Between workflows (not yet tested):** select by an earlier workflow's id, using the `workflow_id` match in row 5, so that a single entry brings in that workflow's outputs. Still to confirm on the dev platform: + - Is the stored `workflow_id` the workflow definition's id or the run's? + - Does the match return the outputs of every run, or of one run only? + +## How one agent's output reaches the next agent's context + +Traced through the workers (`modernization-platform` @ `c89aedcb9`) and the agent runtime (the repository's `agent-builder-agent-runtime` is 0.37.0; the agents pin 0.35.7). The `temporal-workers` limits below are the live values on `crucible-kab-dev-aks`. + +| Hop | What happens | Code | +|---|---|---| +| 1. The agent replies | The reply's text is parsed as JSON. If it doesn't parse, the reply is kept as a plain string. | `activities/base_activity.py` `_process_agent_result` (~1200) | +| 2. The executor stores it | A step output over **100 KB** is written to the PV, and only a reference is kept in workflow state. This is only to get it through Temporal. | `workflows/generic_workflow_executor.py:1189–1215` | +| 3. `from_steps` picks fields | `"records": "s3.records"` copies that field of s3's output. A reference to an externalised output carries `_extract_field`, so the field is cut out after the file has been loaded. If every `from_steps` reference is unresolved, the step fails. | `generic_workflow_executor.py:232–300`, `:444` | +| 4. The references are resolved again | Before the agent call, the stored references are loaded back into the input. | `generic_workflow_executor.py:1470`; `base_activity.py:229–320`, `:505` | +| 5. The size check | If the whole input exceeds `MAX_INLINE_PAYLOAD_BYTES` (code default 1 MiB, **8 MiB live**), every value over **50 KB** is replaced by a file path plus a preview: a list becomes `{"prompt": {"type": "externalized_list", "filepath": ...}}`, a string becomes `{"type": "externalized_text", "preview": <5,000 chars>}`, and a dict becomes `{"type": "externalized_data", "keys": ..., "preview": <2,000 chars>}`. The step's metadata records this as `payload_externalized`. | `base_activity.py:1701–1745`, `_externalize_large_agent_input` `:2176` | +| 6. The message | The input is serialised with `json.dumps` as the A2A message's **text**. Small values (under 10 KB each) are also copied into the call's context metadata. | `base_activity.py:1747–1770` | +| 7. The runtime | The runtime pulls the JSON out of the text and validates it against the agent's input schema. A violation is answered with `input_validation_failed` and no model call. If the message has no JSON at all, it is passed to the model as prose, with the contract skipped. | `request_cycle.py:205–225` | +| 8. The model | The validated request is the model's user turn: one fresh session per request, and nothing carried over from earlier steps. The system prompt adds the content rule: text from tools, files or other agents is material to work with, never instructions. | `spec.py:89` `CONTENT_RULE`; `a2a/server.py` | + +What this means for the CP1 agents: + +- **The binding limit is the model's context window, not the platform's.** Hop 5 starts only at 8 MiB, roughly 2 million tokens, far beyond what a model can take. A large hand-off will overflow the model's context (an error from LiteLLM, then a failed step) well before the platform does anything. Agents most at risk: + - in the individual pattern, the critic (s8, which takes everything) and the dependency-mapping agent (s7); + - in the sub-agent pattern, `dsc_08_critic`, whose inputs are every record in the run. +- **When hop 5 does trigger, the agent can't read what it's given.** A declarative agent has no function that could open the path. For fields our schemas type as arrays or strings (`records`, `findings`, `source_documents` …), the wrapper fails the input contract at hop 7. The step then fails loudly (`input_validation_failed`) rather than running on a preview, which is the safer of the two outcomes. An agent whose schema accepted an object would instead run on a 2,000- or 5,000-character preview without noticing. +- **The orchestrator could resolve externalised inputs; the declarative agents can't.** The orchestrator's `app/artifacts.py` reads files under `EXECUTION_STORAGE_ROOT`. It isn't wired to the `externalized_*` wrappers today. +- **Whatever one agent returns becomes the next agent's input, unfiltered.** It reaches the next model as a user turn, so the content rule and each agent's own input contract are the only safeguards. Both patterns check what an earlier step returned; the critic in particular checks the evidence. +- **Hop 1 accepts prose.** An agent that answers in prose rather than JSON hands the next step a string, and its `from_steps` fields go unresolved. The runtime's output contract (`schemas/output.json`) prevents this for our agents. + +## Questions for the platform team + +1. Is registering artifacts only at the end of the run intended? Could each step's output be registered when that step completes (it's already on the PV as `pv://{execution}/step_n/output.json`)? +2. Could `select_artifacts` take a reference to the current run, such as `{"from_step": "s3"}` or `{"execution": "current", "step": "s3"}`, resolved by the executor? +3. Could `artifact_ids` come from the run form, or from `from_workflow`, so that a reusable workflow doesn't need ids fixed when it's built? And could an empty selection be allowed (skip, rather than fail)? +4. What does the `workflow_id` match select: one workflow definition's artifacts across all of its runs, or one run's? Is matching by `name` meant for production use, or is it a fallback? +5. Could `_externalize_large_agent_input` hand an agent its externalised value as an A2A file part, or as a declared `x-storage-ref` field, instead of a wrapper object the agent's schema can't accept? And could its 50 KB per-value threshold be configured? +6. Is there a planned way to limit a hand-off to what fits the receiving agent's model: a per-step token budget, or summarising before the hand-off? + +## Evidence + +Code reading, of `modernization-platform` @ `c89aedcb9`, plus read-only `kubectl get` of the workers' plain environment values. Nothing was run against the platform, and nothing was changed. diff --git a/docs/platform-issues/mcp-gateway-default-tenant/README.md b/docs/platform-issues/mcp-gateway-default-tenant/README.md new file mode 100644 index 0000000..f9f5b24 --- /dev/null +++ b/docs/platform-issues/mcp-gateway-default-tenant/README.md @@ -0,0 +1,12 @@ +# MCP gateway: registering a server fails with a 500 + +Open since 2026-10-29, on `crucible-kab-dev-aks`. The full analysis is in [report-2026-10-29.md](report-2026-10-29.md). + +| File | What it is | Applied? | +|---|---|---| +| [report-2026-10-29.md](report-2026-10-29.md) | Root cause, code path, evidence and options | — | +| `kyn-agent-builder-mcp-gateway.deployment.yaml` | The gateway Deployment, cleaned up (`DEFAULT_TENANT_ID=default`, no `TENANT_ID`); no different from the live one | No change needed | +| `secrets.yaml` | Secret `kab-tenant-id`. It holds KAB's default tenant id, which is an identifier and not a credential. | **No** | +| `mcp-gateway-link-default-tenant.job.yaml` | A one-off Job that maps KAB's default tenant to the gateway tenant `default` | **No.** It changes `core-components`, so it needs approval. | + +The Job fixes registration only while the default tenant is selected. In the gateway's single tenancy mode, tenants that KAB provisions later still fail. See option C in the report. diff --git a/docs/platform-issues/mcp-gateway-default-tenant/kyn-agent-builder-mcp-gateway.deployment.yaml b/docs/platform-issues/mcp-gateway-default-tenant/kyn-agent-builder-mcp-gateway.deployment.yaml new file mode 100644 index 0000000..4364957 --- /dev/null +++ b/docs/platform-issues/mcp-gateway-default-tenant/kyn-agent-builder-mcp-gateway.deployment.yaml @@ -0,0 +1,153 @@ +# MCP Gateway Deployment for kab-dev (namespace core-components), from the live object of Helm release `kyn`. +# +# Server-generated fields (status, uid, resourceVersion, creationTimestamp, generation, the revision annotation) +# are removed so this file can be applied. Helm owns this object: a manual apply is overwritten by the next +# `helm upgrade`, so make lasting changes in the release's values file too. +# +# Tenancy (see documents/kab-dev-mcp-gateway-default-tenant-500-2026-10-29.md): +# - DEFAULT_TENANT_ID is read by the gateway (settings.default_tenant_id) and must stay "default": the database +# default and the row-level security policies hard-code 'default' as the effective tenant in single mode. +# - KAB's default tenant id is NOT configured here. The gateway maps it through the tenant row's external_id, +# which mcp-gateway-link-default-tenant.job.yaml sets. A TENANT_ID variable is not read by the gateway, and the +# earlier draft's reference to a Secret named "default" would have stopped the pod starting +# (CreateContainerConfigError). +apiVersion: apps/v1 +kind: Deployment +metadata: + annotations: + meta.helm.sh/release-name: kyn + meta.helm.sh/release-namespace: core-components + labels: + app.kubernetes.io/instance: kyn + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: agent-builder-mcp-gateway + app.kubernetes.io/version: latest + helm.sh/chart: agent-builder-mcp-gateway-0.1.0 + name: kyn-agent-builder-mcp-gateway + namespace: core-components +spec: + progressDeadlineSeconds: 600 + replicas: 1 + revisionHistoryLimit: 10 + selector: + matchLabels: + app.kubernetes.io/instance: kyn + app.kubernetes.io/name: agent-builder-mcp-gateway + strategy: + rollingUpdate: + maxSurge: 25% + maxUnavailable: 25% + type: RollingUpdate + template: + metadata: + labels: + app.kubernetes.io/instance: kyn + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: agent-builder-mcp-gateway + app.kubernetes.io/version: latest + helm.sh/chart: agent-builder-mcp-gateway-0.1.0 + spec: + containers: + - env: + - name: ENVIRONMENT + value: production + - name: DEBUG + value: "false" + - name: HOST + value: 0.0.0.0 + - name: PORT + value: "8000" + - name: DATABASE_URL + valueFrom: + secretKeyRef: + key: mcp-gateway-database-url + name: agent-builder-secrets + - name: INTERNAL_SERVICE_TOKEN + valueFrom: + secretKeyRef: + key: token + name: internal-service-secret + - name: DATABASE_POOL_SIZE + value: "20" + - name: REDIS_URL + value: redis://redis.kab-data.svc.cluster.local:6379/0 + - name: REDIS_PASSWORD + valueFrom: + secretKeyRef: + key: redis-password + name: agent-builder-secrets + - name: JWT_SECRET + valueFrom: + secretKeyRef: + key: mcp-gateway-jwt-secret + name: agent-builder-secrets + - name: MCP_ENCRYPTION_KEY + valueFrom: + secretKeyRef: + key: mcp-encryption-key + name: agent-builder-secrets + - name: AUTH_ENABLED + value: "true" + - name: CORS_ORIGINS + value: '["https://app.kab-dev.kyndemo.live"]' + - name: OIDC_ENABLED + value: "true" + - name: OIDC_AUTHORITY + value: https://id.kab-dev.kyndemo.live/realms/kab + - name: OIDC_AUDIENCE + value: account + - name: OIDC_DEFAULT_ROLES + value: '["viewer"]' + - name: ADMIN_PASSWORD + valueFrom: + secretKeyRef: + key: mcp-gateway-admin-password + name: agent-builder-secrets + - name: MCP_GATEWAY_TENANCY_MODE + value: single + # The gateway's own default tenant id. Keep "default": the RLS policies and the column default use it. + - name: DEFAULT_TENANT_ID + value: default + image: cruciblecoredevacr.azurecr.io/kab/agent-builder-mcp-gateway:v3.1.1 + imagePullPolicy: Always + livenessProbe: + failureThreshold: 5 + httpGet: + path: /health/live + port: 8000 + scheme: HTTP + initialDelaySeconds: 20 + periodSeconds: 15 + successThreshold: 1 + timeoutSeconds: 5 + name: agent-builder-mcp-gateway + ports: + - containerPort: 8000 + name: http + protocol: TCP + readinessProbe: + failureThreshold: 3 + httpGet: + path: /health/ready + port: 8000 + scheme: HTTP + initialDelaySeconds: 15 + periodSeconds: 10 + successThreshold: 1 + timeoutSeconds: 5 + resources: + limits: + cpu: "1" + memory: 1Gi + requests: + cpu: 200m + memory: 512Mi + terminationMessagePath: /dev/termination-log + terminationMessagePolicy: File + dnsPolicy: ClusterFirst + restartPolicy: Always + schedulerName: default-scheduler + securityContext: {} + serviceAccount: default + serviceAccountName: default + terminationGracePeriodSeconds: 30 diff --git a/docs/platform-issues/mcp-gateway-default-tenant/mcp-gateway-link-default-tenant.job.yaml b/docs/platform-issues/mcp-gateway-default-tenant/mcp-gateway-link-default-tenant.job.yaml new file mode 100644 index 0000000..030f627 --- /dev/null +++ b/docs/platform-issues/mcp-gateway-default-tenant/mcp-gateway-link-default-tenant.job.yaml @@ -0,0 +1,66 @@ +# Link KAB's default tenant to the MCP Gateway's "default" tenant (kab-dev, namespace core-components). +# +# KAB creates its default tenant at startup without the provisioning workflow, so the workflow's +# provision_mcp_gateway_tenant step never ran for it. Without that link, every MCP server registration from the +# default tenant fails row-level security (HTTP 500). This Job makes the same idempotent call the step makes, +# with the same credential: +# +# POST /api/v1/admin/tenants X-Internal-Service-Token: +# {"id": "default", "name": "Default Organization", "external_id": , "status": "active"} +# +# The gateway tenant id stays "default" (its RLS policies use it); KAB's id becomes its external_id, which is what +# the gateway resolves proxied requests by. It is the AKS equivalent of the dev kit's link-mcp-tenants.sh. +# +# Apply secrets.yaml first. Safe to run again: the endpoint is an upsert. The Job deletes itself an hour after it +# finishes. Neither key is printed: the token is sent as a header, and only the response body is logged. +apiVersion: batch/v1 +kind: Job +metadata: + name: mcp-gateway-link-default-tenant + namespace: core-components + labels: + app.kubernetes.io/part-of: kab + app.kubernetes.io/component: mcp-gateway-tenant-link +spec: + backoffLimit: 3 + ttlSecondsAfterFinished: 3600 + template: + metadata: + labels: + app.kubernetes.io/component: mcp-gateway-tenant-link + spec: + restartPolicy: Never + containers: + - name: link + image: docker.io/curlimages/curl:8.11.1 + env: + - name: INTERNAL_SERVICE_TOKEN + valueFrom: + secretKeyRef: + name: internal-service-secret + key: token + - name: KAB_TENANT_ID + valueFrom: + secretKeyRef: + name: kab-tenant-id + key: tenant-id + - name: GATEWAY_URL + value: http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000 + command: + - sh + - -c + - | + set -eu + body=$(printf '{"id":"default","name":"Default Organization","external_id":"%s","status":"active"}' "$KAB_TENANT_ID") + code=$(curl -sS -o /tmp/response -w '%{http_code}' -X POST "$GATEWAY_URL/api/v1/admin/tenants" \ + -H "X-Internal-Service-Token: $INTERNAL_SERVICE_TOKEN" -H "Content-Type: application/json" -d "$body") + echo "upsert: HTTP $code"; cat /tmp/response; echo + [ "$code" -lt 300 ] || exit 1 + curl -sS "$GATEWAY_URL/api/v1/admin/tenants" -H "X-Internal-Service-Token: $INTERNAL_SERVICE_TOKEN"; echo + resources: + requests: + cpu: 10m + memory: 32Mi + limits: + cpu: 100m + memory: 64Mi diff --git a/docs/platform-issues/mcp-gateway-default-tenant/report-2026-10-29.md b/docs/platform-issues/mcp-gateway-default-tenant/report-2026-10-29.md new file mode 100644 index 0000000..47569d6 --- /dev/null +++ b/docs/platform-issues/mcp-gateway-default-tenant/report-2026-10-29.md @@ -0,0 +1,231 @@ +# KAB dev: MCP server registration fails with HTTP 500 for the default tenant + +> **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/`, and `cp1-agents-individual` → `individual-agents/ALZ-F01: Discovery Workflow Agent/`. + +| | | +|---|---| +| Environment | kab-dev (AKS `crucible-kab-dev-aks`), platform from `modernization-platform` @ `7adfc87f` (2026-10-19) | +| Component | MCP Gateway (`kyn-agent-builder-mcp-gateway`, namespace `core-components`, Helm release `kyn`, chart `agent-builder-mcp-gateway-0.1.0`) | +| Reported | 2026-10-29 | +| Severity | High: no MCP server can be registered in the default tenant, so no agent that uses MCP tools can be created or run there | +| Status | Root cause confirmed; one-call remediation identified; permanent fix needed in the platform bootstrap | + +## Summary + +Registering an MCP server in the KAB UI fails with `500 Internal Server Error` on +`POST https://api.kab-dev.kyndemo.live/api/v1/mcp-gateway/api/v1/admin/servers`. The MCP server itself is healthy, and +its key is accepted. + +The failure is a gap in platform provisioning. The MCP Gateway keeps its own tenant registry, and the gateway tenant +for KAB's **default tenant** (`6ada663eb5b88053a9e43723`) has never been linked to it. KAB creates its default tenant +at startup without running the provisioning workflow. That workflow is the only automated path that creates the +matching gateway tenant. Each request from the default tenant therefore resolves to no gateway tenant, and Postgres +row-level security refuses the insert. + +Locally, the dev kit closes this gap with `scripts/link-mcp-tenants.sh`. The AKS installation has no equivalent step. + +**Immediate fix:** one idempotent call, made as a KAB platform admin, that sets the gateway's `default` tenant's +`external_id` to the KAB default tenant id (see [Remediation](#remediation)). **Permanent fix:** register the +bootstrap tenant with the gateway as part of platform bootstrap. + +## Symptoms + +- **In the UI:** registering a server fails with the browser console error `Failed to load resource: the server responded with a status of 500 ()`. +- **The server list is empty** for the default tenant, even though the gateway logs show health-check rounds. +- **Every proxied request** from the default tenant logs a warning on the gateway: + `tenant reference '6ada663eb5b88053a9e43723' matches no tenant id or external_id; binding it unresolved (the caller will see no data)`. + +## Evidence + +**Gateway log for one failed registration (2026-10-29 16:07:29 UTC, request `9f0021b407a1080ccd50dd860744d647`; the same sequence appeared at 13:15:06 and about 13:19):** + +```text +[warning] tenant reference '6ada663eb5b88053a9e43723' matches no tenant id or external_id; binding it unresolved +[info] Server 2d10e0e1-... auth check: required=True +[info] Validating API key for server 2d10e0e1-... +[info] API key validated successfully for server 2d10e0e1-... +[info] Encrypted API key for server: 2d10e0e1-... +[error] Failed to create server: ... InsufficientPrivilegeError: new row violates row-level security policy for table "servers" + [INSERT INTO servers (... tenant_id ...) VALUES (... '6ada663eb5b88053a9e43723' ...)] +[error] Database error: 500: Failed to create server +[info] http_request_completed method=POST path=/api/v1/admin/servers status_code=500 +``` + +The connection test (`POST /api/v1/admin/servers/test-connection`) passes, and the gateway's authenticated +`tools/list` call to the MCP server succeeds. The failure happens only at the database insert. + +**Gateway configuration (Deployment `env`, set by Helm values):** + +| Variable | Value | +|---|---| +| `MCP_GATEWAY_TENANCY_MODE` | `single` | +| `DEFAULT_TENANT_ID` | `default` | + +**Provisioning activity:** +- **No tenant registrations:** the gateway logged no `POST /api/v1/admin/tenants` call in the 6 hours checked. +- **No provisioning runs:** the platform worker (`kyn-agent-builder-platform-worker`, queue `platform-tenant-lifecycle`) has registered `provision_mcp_gateway_tenant`, but logged no provisioning run since it started at 13:55 UTC. + +**The MCP server under test (`alz-discovery-sample`, namespace `mcp-servers`) is healthy:** +- `/health` reports healthy. +- Unauthenticated calls get 401. +- With its key: `initialize`, `tools/list` (20 tools) and `tools/call` all succeed from inside the cluster and from the gateway pod. + +## Root cause: traced end to end + +All paths below are relative to `modernization-platform/packages/`. + +### 1. KAB creates the default tenant without provisioning it + +`agent-builder-api/src/database/init_database.py` (lines 78–110) runs at API startup (`main.py`, "Initialize +database with required collections and default teams"). If the `tenants` collection is empty, it inserts +"Default Organization" directly into MongoDB. The tenant id is the MongoDB ObjectId returned by `insert_one`, which +is the 24-hex form of `6ada663eb5b88053a9e43723`. The code states the gap itself: + +> This tenant never runs the provisioning workflow, which is what normally writes these fields ... + +It makes up for one consequence (it stamps `database_name` and `temporal_namespace`), but not for the missing MCP +Gateway tenant. `init_default_data.py` (the CLI seeder, `init_default_user_and_team`) inserts its "Default Tenant" +the same way, with no reference to provisioning or the gateway. + +### 2. Normal tenants are provisioned, including the gateway + +`agent-builder-api/src/api/tenant_routes.py`, `POST /api/v1/tenants/`, calls: +1. **`db.create_tenant`,** with `provisioning_status="pending"`; +2. **`_provisioning_input`,** which passes `tenant_slug` in `config` for the gateway; +3. **`_start_provisioning`,** which starts `TenantProvisioningWorkflow` on `platform-tenant-lifecycle`. + +Among that workflow's activities is +`agent-builder-temporal-workers/src/temporal/activities/tenant_lifecycle/mcp_gateway_mgmt.py`, +`provision_mcp_gateway_tenant`. It posts to the gateway directly: + +```json +POST {MCP_GATEWAY_URL}/api/v1/admin/tenants (X-Internal-Service-Token) +{"id": "", "name": "", "external_id": "", "status": "active"} +``` + +Its docstring records the history: "Until this step existed the row had to be created by hand +(local-dev-kit/scripts/link-mcp-tenants.sh), so a freshly provisioned tenant opened the MCP pages to nothing." + +### 3. The gateway resolves tenants only through that registry + +`agent-builder-mcp-gateway/src/mcp_gateway/core/tenancy.py`, `resolve_tenant_ref` (around line 305), maps the +tenant reference KAB sends to a gateway tenant by `Tenant.id == ref OR Tenant.external_id == ref`. If nothing +matches, it returns the reference unchanged, on purpose: "binding it matches no rows, so an unknown tenant sees +nothing instead of another tenant's data." The gateway's only tenant is `default` (from `DEFAULT_TENANT_ID`), whose +`external_id` doesn't hold `6ada663eb5b88053a9e43723`. So the new server row is stamped +`tenant_id = '6ada663eb5b88053a9e43723'`. + +### 4. Row-level security rejects that row + +`agent-builder-mcp-gateway/alembic/versions/20260723_1000_tenancy_full_rollout.py` puts `servers` (and `tools`, +`mcp_tools`, `resources`, `prompts` and others) under the catalog policy: + +```sql +EFFECTIVE_TENANT := COALESCE(NULLIF(current_setting('app.current_tenant', true), ''), 'default') +CREATE POLICY tenant_catalog ON servers + USING (tenant_id IS NULL OR tenant_id = EFFECTIVE_TENANT) + WITH CHECK (tenant_id = EFFECTIVE_TENANT OR (tenant_id IS NULL AND EFFECTIVE_TENANT = 'default')) +``` + +In `single` mode, `SingleTenantStrategy` sets no session tenant, so `EFFECTIVE_TENANT` is `'default'`. The row's +`'6ada663eb5b88053a9e43723'` fails the check, Postgres raises `InsufficientPrivilegeError`, and the API returns 500. +The same unresolved tenant is why the server list shows nothing. + +### 5. Why it works locally and not in AKS + +The dev kit runs `agent-builder-local-dev-kit/scripts/link-mcp-tenants.sh`. It reads the platform's tenants from +MongoDB, maps the **first** one (the bootstrap default) to gateway tenant `default`, sets `external_id` to its `_id`, +and maps every later tenant by slug. The AKS Helm values (`agent-builder-kubernetes-deployment/AKS/helm-umbrella-chart/v2.2.0/values_files/az_dev.yaml` +around line 1303, and v2.3.0 `az_staging.yaml`) configure only the gateway connection for +`provision_mcp_gateway_tenant`, which covers new tenants. **Nothing in the AKS installation links the bootstrap +tenant.** + +## Impact + +- **No MCP servers in the default tenant:** none can be registered, and none would show to its users. +- **No working agents there:** agents can't be given an MCP key (`MCP_AGENT_API_KEY`), so any agent that declares MCP tools fails every request at startup with `MCP_AGENT_API_KEY is not set, so the MCP gateway will refuse the agent`. +- **Blocks:** the CP1 Agentic Landing Zone Discovery deployment, in both patterns: `cp1-agents` (orchestrator) and `cp1-agents-individual` (eight agents). +- **Likely other environments too:** any environment installed from the AKS or EKS charts with a bootstrap default tenant has the same gap unless it was linked by hand. + +## Remediation + +### Immediate (no deploy, no Helm change) + +Make the call the provisioning activity would have made, through KAB's proxy, as a **KAB platform admin**. The +proxy only forwards `api/v1/admin/tenants` to callers with platform-admin rights; see +`agent-builder-api/src/api/routes/mcp_gateway_proxy.py`, `_CROSS_TENANT_PATTERNS`. + +```sh +curl -sS -X POST https://api.kab-dev.kyndemo.live/api/v1/mcp-gateway/api/v1/admin/tenants \ + -H "Authorization: Bearer " -H "Content-Type: application/json" \ + -d '{"id": "default", "name": "Default Organization", "external_id": "6ada663eb5b88053a9e43723", "status": "active"}' +``` + +The endpoint is an idempotent upsert (`agent-builder-mcp-gateway/src/mcp_gateway/api/endpoints/tenant_admin.py`, +`upsert_tenant`). It keeps the gateway's `default` tenant and records KAB's id on it, exactly as +`link-mcp-tenants.sh` does locally. `DEFAULT_TENANT_ID` doesn't need to change. + +**Don't** instead set `DEFAULT_TENANT_ID=6ada663eb5b88053a9e43723`. That names a gateway tenant row that doesn't +exist, and Helm would revert a manual change. + +### Permanent (platform change) + +Options, best first: + +1. **Register the bootstrap tenant during bootstrap.** When `init_database.py` creates or finds the bootstrap tenant, make the same `POST /api/v1/admin/tenants` call as `provision_mcp_gateway_tenant`, with gateway id `default`. Alternatively, start the provisioning workflow's gateway step for it. +2. **Add a post-install / post-upgrade Helm hook Job** that does what `link-mcp-tenants.sh` does, using the gateway API rather than direct SQL. +3. **Reconcile on a schedule:** a platform-worker job that upserts a gateway tenant for every active KAB tenant with no `external_id` match, which also repairs any tenant whose provisioning failed. + +## Verification + +1. **After the upsert,** `GET .../api/v1/mcp-gateway/api/v1/admin/tenants` lists `default` with `external_id: 6ada663eb5b88053a9e43723`. +2. **The warning stops:** new requests from the default tenant no longer log `matches no tenant id or external_id`. +3. **Registration succeeds:** registering `http://alz-discovery-sample.mcp-servers.svc.cluster.local:8110` returns 2xx, and the server appears in the list. +4. **Agents get keys:** creating an agent issues an `MCP_AGENT_API_KEY`, and that agent's requests no longer fail at startup. + +## Related finding + +The gateway's OIDC just-in-time provisioning failed for `jonathan.boniface@kyndryl.com` with a unique-key violation +on `users` (`[OIDCVerifier] JIT provisioning failed ... UniqueViolationError`). The user probably exists already under +another id. `OIDC_DEFAULT_ROLES` is `["viewer"]`. Check this user's gateway role after the tenant fix, in case server +registration then fails on permissions instead. + +## Method + +- **Read-only checks against `crucible-kab-dev-aks`:** gateway, API and platform-worker logs, and Deployment `env` (plain values only). +- **Code reading in `modernization-platform` @ `7adfc87f`.** +- **Nothing in `core-components` was changed.** +- **No Secret values or database credentials were read:** an attempt to query the gateway database directly was refused, and was not retried. + +## Addendum (2026-10-29, 17:45 UTC): why the 500 persists, and a second defect + +**The error is unchanged.** At 17:38:32 `POST /api/v1/admin/servers` failed again with `new row violates row-level security policy for table "servers"`. At 17:38–17:40 the gateway also logged `tenant reference '6ada663eb5b88053a9e43723' matches no tenant id or external_id; binding it unresolved`. The KAB default tenant is still unmapped. + +**The one tenant upsert seen didn't touch it.** `POST /api/v1/admin/tenants` → 200 at 17:06:28 came from `kyn-agent-builder-platform-worker` (10.20.10.17), so it was a `TenantProvisioningWorkflow` for a newly created tenant. That activity (`temporal-workers/.../tenant_lifecycle/mcp_gateway_mgmt.py`) upserts `id = ` and `external_id = `. It doesn't create a mapping for `6ada663eb5b88053a9e43723`. + +### The full code path + +| Step | Code | What happens | +|---|---|---| +| 1 | `agent-builder-api/src/api/routes/mcp_gateway_proxy.py` `_identity_context` | Forwards `X-Tenant-ID` = the tenant selected in the UI (`6ada…`). It sends `default` only when a platform admin has **no** tenant selected. | +| 2 | `mcp-gateway/src/mcp_gateway/gateway/auth.py` (service-token path) | `resolve_tenant_ref` → `bind_tenant`. An unmapped reference is bound **as-is**. | +| 3 | `mcp-gateway/src/mcp_gateway/db/repositories.py` `ServerRepository.create` | If the bound tenant ≠ `DEFAULT_TENANT_ID` (`default`), it stamps `servers.tenant_id = `; otherwise it stamps `NULL` (global). | +| 4 | `mcp-gateway/src/mcp_gateway/core/tenancy.py` `SingleTenantStrategy` | Single mode **never** issues `set_config('app.current_tenant', …)`. | +| 5 | `alembic/versions/20260723_1000_tenancy_full_rollout.py` `tenant_catalog` | `WITH CHECK (tenant_id = EFFECTIVE OR (tenant_id IS NULL AND EFFECTIVE = 'default'))`. With no setting, EFFECTIVE is always `'default'`. | + +So in `MCP_GATEWAY_TENANCY_MODE=single`, **a server insert succeeds only when the bound tenant is exactly `default`**. That gives a second defect, beyond the missing mapping: + +- **Unmapped tenant** (today): `tenant_id='6ada…'` ≠ `'default'`, so it's refused. +- **Mapped tenant whose gateway id isn't `default`** (what `TenantProvisioningWorkflow` creates for every new tenant, id = slug): `tenant_id=''` ≠ `'default'`, so it's refused too. In single mode, server registration fails for **every tenant except one mapped to `id='default'`**. + +The `link-default-tenant` Job (an upsert of `{id:"default", external_id:"6ada…"}`) still fixes the KAB default tenant. It does nothing for other tenants. + +### Options + +| # | Option | Who | Effect | +|---|---|---|---| +| A | **Register from "All tenants".** A platform admin clears the tenant selector in the UI, so the proxy sends `X-Tenant-ID: default` and the server is stored as a global entry (`tenant_id NULL`). | Platform admin (`is_platform_admin`) | Works today, with no cluster change. The server is global; in single mode every tenant sees all global servers. | +| B | Map the default tenant: apply `secrets.yaml` and `mcp-gateway-link-default-tenant.job.yaml`, or a Global Admin calls `POST /api/v1/mcp-gateway/api/v1/admin/tenants` with `{"id":"default","external_id":"6ada663eb5b88053a9e43723",…}` | Global Admin, or approval for a `core-components` change | Registration works with the default tenant selected. | +| C | Platform fix: in single mode, make `ServerRepository.create` stamp `NULL` regardless of the bound tenant, **or** run the gateway in `pooled` mode (needs the restricted DB role and Alembic, per `docs/TENANCY.md`) | Platform team | Fixes registration for every tenant. Single mode then matches its documented promise ("byte-identical to the pre-tenancy behavior"). | +| D | Platform fix: the bootstrap in `init_database.py` should run `provision_mcp_gateway_tenant` for the default tenant, with `id = DEFAULT_TENANT_ID` | Platform team | Stops a fresh install from shipping an unmapped default tenant. | diff --git a/docs/platform-issues/mcp-gateway-default-tenant/secrets.yaml b/docs/platform-issues/mcp-gateway-default-tenant/secrets.yaml new file mode 100644 index 0000000..1161099 --- /dev/null +++ b/docs/platform-issues/mcp-gateway-default-tenant/secrets.yaml @@ -0,0 +1,15 @@ +# KAB's default tenant id, for mcp-gateway-link-default-tenant.job.yaml. +# +# It is an identifier, not a credential: it appears in every KAB request and in the gateway's logs. It is kept in +# a Secret only so the Job reads it the same way it reads the internal service token. stringData takes the plain +# value; Kubernetes stores it base64-encoded under data. The gateway Deployment does not read it. +apiVersion: v1 +kind: Secret +metadata: + labels: + app.kubernetes.io/part-of: kab + name: kab-tenant-id + namespace: core-components +type: Opaque +stringData: + tenant-id: "6ada663eb5b88053a9e43723" diff --git a/docs/source-material/agent-shapes/agent-pattern/.dockerignore b/docs/source-material/agent-shapes/agent-pattern/.dockerignore new file mode 100644 index 0000000..ba35f0c --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/.dockerignore @@ -0,0 +1,29 @@ +# What `docker build .` / `podman build .` leaves out of the build context. +# +# The Dockerfile copies only named paths (agent.yaml, prompt.md, app/, schemas/, +# skills/, prompts/, eval/, requirements.txt), so nothing here could reach the +# image. It keeps them from being sent to the builder at all: the local .env +# holds real credentials, and a virtual environment or .git can be hundreds of +# megabytes on every build. + +# Local environment, with real credentials. +.env + +# Version control. +.git/ + +# Python build artifacts and caches. +__pycache__/ +*.py[cod] +*.egg-info/ +.pytest_cache/ + +# Virtual environments. +.venv/ +venv/ + +# Left empty by ./run-local.sh (the extra packages are installed in the image). +vendor/ + +# OS noise. +.DS_Store diff --git a/docs/source-material/agent-shapes/agent-pattern/.env.example b/docs/source-material/agent-shapes/agent-pattern/.env.example new file mode 100644 index 0000000..7e40732 --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/.env.example @@ -0,0 +1,124 @@ +# Secrets and machine-specific values. Nothing else belongs here. +# +# Everything this agent needs at runtime lives in kubernetes/configmap.yaml — +# its name, its model, its guard rails, its observability backend. That file is +# not Kubernetes-only: Kubernetes injects it with `envFrom: configMapRef`, +# and ./run-local.sh passes each key through as -e. One file, and the local +# container and the deployed pod agree. +# +# This file holds only what a ConfigMap cannot hold: +# +# * secrets — a ConfigMap is stored unencrypted and is readable by +# anyone who can list ConfigMaps in the namespace +# * your machine — a gateway URL that is yours and nobody else's +# +# If you are looking for a setting and it is not here, it is in the ConfigMap, +# and that is where to change it. Values used to be listed in both files; they +# drifted, and the drift was silent, which is why they are not any more. +# +# Precedence, when the same key appears in more than one place: +# +# shell environment > this file > kubernetes/configmap.yaml +# +# So `LITELLM_MODEL=claude-sonnet-4-6 ./run-local.sh` overrides everything for one run +# without editing anything. +# +# The agent-creation page renders this file as a form, so the conventions below +# are read by a machine as well as by you: +# +# KEY="" empty value -> you must supply it; the form marks it required +# KEY="default" has a value -> optional; leaving it alone keeps the default +# # KEY="v" commented -> optional and switched off; supplying a value +# in the form uncomments it +# # optional in a comment -> overrides the empty-value rule above +# # fixed in a comment -> set by the template; not shown in the form +# # configmap in a comment -> owned by kubernetes/configmap.yaml, which is +# what Kubernetes and run-local.sh actually +# read; not shown in the form +# +# A comment block directly above a key becomes that field's help text, and the +# first sentence of a block that opens a new topic becomes a section heading. +# +# .env is gitignored and is never copied into the image. Commit .env.example. + +# Gateway — where this agent sends its model calls. +# +# required +# +# The Create Agent page fills in the gateway its own platform uses, so a new +# agent reaches a model as generated. Outside the platform the placeholder +# below stays: it is not a working value -- an agent started with it fails on +# the first request -- so replace it in `.env` before you expect an answer. +LITELLM_PROXY_BASE="will provide later" + +# The gateway key. +# +# optional +# +# Not asked for on the creation page, and deliberately: a key typed into a web +# form also lives in the browser's autofill, in the request that carried it, +# and in whatever logged that request — none of which you chose. So the project +# ships this empty and you set it here, on your machine: +# +# LITELLM_MASTER_KEY="sk-..." +# +# `.env` is gitignored and is never copied into the image, so the key stays +# where you put it. ./run-local.sh stops with "set LITELLM_MASTER_KEY (see +# .env.example)" until you do. +LITELLM_MASTER_KEY="" + +# MCP agent key — optional, and issued by the MCP Gateway when the agent is +# created rather than supplied by you. The platform writes the +# real key into .env at scaffold time and leaves it blank in .env.example, so +# the key never reaches git. Leave this line in place: removing it is what +# would break the injection. +MCP_AGENT_API_KEY="" + +# Local only. "true" restarts the server when app/, schemas/, agent.yaml or +# prompt.md changes. +# DEV_RELOAD="true" + + +# configmap — Changing something while you build and test. +# +# Uncomment a line and it wins for this machine only. You do not need to open +# kubernetes/ — that directory is generated and maintained by the platform, and +# nothing in it needs editing to try something locally. +# +# The values shown are the template's starting points, not necessarily what +# your agent is set to; the live value is whatever the ConfigMap holds, and an +# uncommented line here beats it. + +# Point it at a different model. (To rename the agent, or change its +# description or version, edit agent.yaml.) +# LITELLM_MODEL="gpt-5.4" +# LITELLM_TEMPERATURE="0.0" +# LITELLM_MAX_TOKENS="16384" + +# Where the MCP tools declared in agent.yaml (`mcp:`) are reached, and where +# telemetry goes. On a cluster the platform sets these for every agent and the +# agent cannot change them; these lines are only for running on your machine. +# MCP_GATEWAY_URL="http://localhost:8000" + +# Telemetry: "otel" (to an OpenTelemetry Collector, at +# OTEL_EXPORTER_OTLP_ENDPOINT) or "none". The collector forwards to Langfuse +# and holds its keys; an agent has none. A setting that cannot work turns +# telemetry off with a log line, never a 500. +# OBSERVABILITY_TYPE="otel" +# OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" +# OBSERVABILITY_CAPTURE_CONTENT="true" + +# Loop bounds, if an agent is running longer than you want to wait. +# AGENT_MAX_ITERATIONS="25" +# AGENT_MAX_REQUEST_MODEL_CALLS="100" +# AGENT_MAX_DURATION_SECONDS="1500" +# LOG_LEVEL="INFO" + +# Log format. "console" is easier to read on your machine; the default, "json", +# is one object per line for a log store. +# LOG_FORMAT="console" + +# Signs the conversation the agent hands over when it pauses for a person's +# approval, so it can carry on from there (runtime 0.28.0 or later). Optional +# locally: unset, the agent makes one at start-up. +# AGENT_CONTINUATION_KEY="" diff --git a/docs/source-material/agent-shapes/agent-pattern/.gitignore b/docs/source-material/agent-shapes/agent-pattern/.gitignore new file mode 100644 index 0000000..c06412b --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/.gitignore @@ -0,0 +1,21 @@ +# Local environment — never commit. Real credentials live here during local +# development; in production these arrive from the ConfigMap and Secrets that +# kubernetes/deployment.yaml references. Commit .env.example instead. +.env + +# Left empty by ./run-local.sh (the extra packages are in the image). +vendor/ + +# Python build artifacts +__pycache__/ +*.py[cod] +*.egg-info/ +.pytest_cache/ + +# Virtual environments +.venv/ +venv/ + +# OS noise +.DS_Store + diff --git a/docs/source-material/agent-shapes/agent-pattern/Dockerfile b/docs/source-material/agent-shapes/agent-pattern/Dockerfile new file mode 100644 index 0000000..cd2ca1a --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/Dockerfile @@ -0,0 +1,63 @@ +# The agent's image: the shared runtime image for its framework (built and +# published by the platform's runtime CI) with this agent's files on top. The +# runtime image holds Python, the agent runtime and the framework's libraries, +# runs as a non-root user and serves the agent (its CMD); this image adds only +# the agent's own files. There is no app/agent.py: the runtime builds the agent +# from agent.yaml. +# +# Moving to a new runtime is a change of RUNTIME_IMAGE and a new agent version +# (agent.yaml, and an entry in RELEASE_NOTES.md). +# +# docker build -t : . +# docker build --build-arg RUNTIME_IMAGE= -t ... . +# +# Extra Python packages: list them in requirements.txt (stage 1 below). +ARG RUNTIME_IMAGE=kyndryl.jfrog.io/kc-ai-agent-factory-docker-local/agent-runtime-adk:0.35.7 + +# Stage 1: the agent's extra Python packages, if requirements.txt lists any. +# Installed on the runtime image itself, so they match its Python and Linux; +# a package that would change one the runtime already has stops the build, +# so an agent cannot break the runtime under it. Only the packages added go +# on to /agent/vendor (on the import path). With an empty requirements.txt +# this stage does nothing. The runtime itself never comes from here. +FROM ${RUNTIME_IMAGE} AS vendor +USER root +COPY requirements.txt /tmp/requirements.txt +RUN pip freeze --all | sort > /tmp/before \ + && pip install --no-cache-dir -r /tmp/requirements.txt \ + && pip freeze --all | sort > /tmp/after \ + && comm -13 /tmp/before /tmp/after > /tmp/added \ + && for name in $(cut -d= -f1 /tmp/added); do \ + if grep -qi "^${name}==" /tmp/before; then \ + echo "requirements.txt changes ${name}, which the runtime image already has" >&2; exit 1; \ + fi; \ + done \ + && mkdir -p /vendor \ + && if [ -s /tmp/added ]; then \ + pip install --no-cache-dir --no-deps --target /vendor -r /tmp/added; \ + fi + +# Stage 2: the agent: the runtime image, its extra packages and its files. +FROM ${RUNTIME_IMAGE} + +COPY --from=vendor /vendor /agent/vendor/ +# shared_skills.loc[k]: the shared skills' lock file, copied only when the +# agent pins shared skills (the pattern matches nothing otherwise). +COPY agent.yaml prompt.md shared_skills.loc[k] /agent/ +COPY schemas/ /agent/schemas/ +COPY app/ /agent/app/ + +# The agent's skills: one folder per skill (skills//SKILL.md), listed in +# agent.yaml. An agent whose agent.yaml names a skill folder that is not in the +# image refuses to start, so this line is not optional once you add one. +COPY skills/ /agent/skills/ + +# The agent's own eval suite, so the platform can fetch it from the running +# container at /.well-known/eval-suite.yaml and run it from the portal. +COPY eval/ /agent/eval/ + +# Add any data your agent reads at runtime, e.g.: +# COPY reference/ /agent/reference/ +# It works locally without this because ./run-local.sh bind-mounts the project +# into the container. Kubernetes has no such mount, so an uncopied file is +# simply absent there — the most common local-passes-deploy-fails bug. diff --git a/docs/source-material/agent-shapes/agent-pattern/README.md b/docs/source-material/agent-shapes/agent-pattern/README.md new file mode 100644 index 0000000..89674b1 --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/README.md @@ -0,0 +1,495 @@ +# expense-policy-agent + +An A2A-protocol agent on Google's ADK, built on the platform's shared runtime +image (`agent-runtime-adk`). + +The runtime handles everything that is the same for every agent — building the +agent, serving the A2A protocol, reaching the LLM gateway, correlation headers, +structured logging, tracing, and the agent-loop guard rails. What is left in +this repository is the part that is yours: `agent.yaml` (what the agent is), +the instructions in `prompt.md`, its schemas, skills, tools and hooks. There is +no `app/agent.py`: the runtime builds the agent from `agent.yaml`. + +- **Model**: claude-sonnet-4-5 +- **Cloud / region**: local / localhost + +## Quick start + +```bash +./run-local.sh # build if needed, run on :8080 +DEV_RELOAD=true ./run-local.sh # same, with hot reload +``` + +`.env` (generated at creation, gitignored) must hold `LITELLM_PROXY_BASE` and +`LITELLM_MASTER_KEY`. Then, in a second terminal: + +```bash +pip install -r tests/requirements.txt +python tests/test_chatbot.py --url http://localhost:8080 +``` + +`tests/test_chatbot.py` is an interactive chat client. It speaks the same A2A +wire format the platform's Temporal worker uses to call this agent in +production, so what you see locally is what a workflow will get. + +`run-local.sh` builds the image from the Dockerfile — the runtime image plus +this agent's files — and runs it with the project bind-mounted over `/agent`, +so an edit is live on the next start. With `DEV_RELOAD=true` the server +restarts on any change in the project — `app/`, `schemas/`, `prompt.md`, +`agent.yaml` — which are the files you will iterate on most. It rebuilds the +image only when the Dockerfile, the runtime image or `requirements.txt` +changes. The runtime image comes from the dev kit's GHCR (`RUNTIME_REGISTRY`, +or `RUNTIME_IMAGE` for one outright; `localhost` for a runtime built from +source). + +It is also the closest local equivalent to a deployed pod. In Kubernetes, +`deployment.yaml` does `envFrom: configMapRef`, which injects every key of +`kubernetes/configmap.yaml` into the container. `run-local.sh` reads that same +file and passes each key as `-e`, so a setting you change in the ConfigMap +takes effect in both places. A plain `podman run` with hand-written `-e` flags +drifts from the deployed configuration silently, and the drift only shows up +after deploy. + +Secrets are not in the ConfigMap; they come from `.env` locally and from the +Secrets in `kubernetes/secretnames.yaml` in production. + +## Running it against the platform + +The steps above run the agent on its own. To use it in a workflow it also has +to be reachable by the platform and registered in the agent catalog. + +**1. Put your gateway credentials in `.env`** (once per checkout): + +```bash +cp .env.example .env # then fill in LITELLM_PROXY_BASE and LITELLM_MASTER_KEY +``` + +`run-local.sh` sources `.env` for secrets and takes everything else from +`kubernetes/configmap.yaml`. + +**2. Start it on the platform's network:** + +```bash +PORT_HOST=10021 \ +CONTAINER_NETWORK=agent-builder-local-dev-kit_agent-builder-network \ + ./run-local.sh +``` + +`CONTAINER_NETWORK` is what makes the agent reachable by the API and the +Temporal worker; without it the agent runs fine but nothing can call it. +Pick a `PORT_HOST` nobody else is using — it is only for your own testing. + +**3. Check it is up, from both sides:** + +```bash +curl -s localhost:10021/health # from your machine +python tests/test_chatbot.py --url http://localhost:10021 +``` + +**4. Register it in the agent catalog.** In the platform UI, go to +**Access Control → Agents → Discover**, and enter: + +``` +http://:8080 +``` + +That is the *container* name on the shared network and the *container's* port +(8080) — not `localhost` and not your `PORT_HOST`. The platform resolves that +name over the podman network; `localhost` from inside the API container means +the API itself. `` is this project's directory name, which is what +`run-local.sh` names the container and registers as its DNS alias. + +The agent then appears in the catalog and can be dropped into a workflow. + +**Redeploying after a change.** Edit, then re-run step 2 — the script rebuilds +and replaces the container. The registration is by URL and survives, so you do +not need to re-register. For prompt-only changes, add `DEV_RELOAD=true` and +skip the rebuild entirely. + +## Configuration + +### The agent itself: `agent.yaml` + +```yaml +name: my-agent +description: What this agent does, for someone choosing it from the catalog. +version: 1.0.0 # #.#.# or DEV -- the CI releases nothing else +framework: adk # must match the runtime image in the Dockerfile +tags: [adk] +capabilities: + streaming: true + push_notifications: false +skills: + - id: my_agent + name: My Agent + description: What this skill does. + tags: [] + examples: [] +prompt: prompt.md +contract: + input: schemas/input.json + output: schemas/output.json +functions: + - app.tools:search +hooks: app.business_logic +``` + +`agent.yaml`, at the root of the project, is the agent: the runtime reads it at +startup and builds the agent from it — its instructions, contract, tools, +skills and hooks — and it is the source of truth for everything the agent card +says. None of it is read from environment variables. Skills are listed either +as folders under `skills/` (instructions and tools the model loads when it +needs them -- see `skills/README.md`) or as plain entries that are only +advertised. Skills never change the agent's input and output: the first skill +carries its schemas. To change any of it, edit the file, redeploy, and refresh +the agent in the catalog. A new `name` registers as a new agent. Every field is +described in the platform's developer guide (Help → Developer Guide → +agent.yaml reference). + +### The runtime it is built on: the Dockerfile + +The Dockerfile builds `FROM` the shared runtime image for this framework, named +with its runtime version (`.../agent-runtime-adk:`), and copies this +agent's files into `/agent`. Moving to a newer runtime is a change of that line +plus a new agent version — the image changes, so the version must. + +### Releasing a version: `RELEASE_NOTES.md` + +The CI takes the version from `agent.yaml` and refuses to release it unless +`RELEASE_NOTES.md` has an entry for it, and a released version cannot be +released again. So a release is three edits: bump `version` in `agent.yaml`, +add its entry at the top of `RELEASE_NOTES.md`, redeploy. + +```markdown +## [1.1.0] - 2026-10-01 + +### Added +- New capability or tool the agent now supports. +### Fixed +- Bug fixes included in this release. +``` + +`version: DEV` is the exception: it needs no entry and may be overwritten, for +development. + +### Everything else: `kubernetes/configmap.yaml` + +`kubernetes/configmap.yaml` is the contract for every other setting — each one +is documented there, in the file that actually ships. This is the summary. + +### Required + +| Variable | Description | +|---|---| +| `LITELLM_MODEL` | Model ID (e.g. `gpt-5.4`, `claude-sonnet-4-6`) | +| `LITELLM_PROXY_BASE` | LiteLLM gateway URL — on a cluster, set by the platform for every agent | +| `LITELLM_MASTER_KEY` | LiteLLM gateway key — on a cluster, set by the platform | + +### Optional + +| Variable | Default | Description | +|---|---|---| +| `LITELLM_TEMPERATURE` | `0.0` | Model temperature | +| `LITELLM_MAX_TOKENS` | `16384` | Max response tokens | +| `AGENT_GUARDRAILS_ENABLED` | `true` | Enforce the loop bounds below | +| `AGENT_MAX_ITERATIONS` | `25` | Model calls per run: the agent's, or one sub-agent's | +| `AGENT_MAX_REQUEST_MODEL_CALLS` | `100` | Model calls in the whole request, the sub-agents the model calls included (default 4 × `AGENT_MAX_ITERATIONS`) | +| `AGENT_MAX_DURATION_SECONDS` | `1500` | Wall clock per request (25 minutes) | +| `AGENT_MAX_TOKENS` | `0` | Total tokens per request; `0` = no limit | +| `OBSERVABILITY_TYPE` | unset | Local runs only: `otel` (with `OTEL_EXPORTER_OTLP_ENDPOINT`, the OpenTelemetry Collector) or `none`. On a cluster the platform sets it for every agent | +| `OBSERVABILITY_CAPTURE_CONTENT` | `true` | `false` keeps this agent's prompts, responses, tool data and approval comments out of traces; an agent may record less than the platform, never more | +| `MCP_GATEWAY_URL` | | The MCP gateway, for the MCP tools declared under `mcp:` in `agent.yaml`. Local runs only: on a cluster the platform sets it | +| `LOG_LEVEL` | `INFO` | Applies to every logger; prompts and payloads are logged only at `DEBUG` | +| `LOG_FORMAT` | `json` | `json` for a log store, `console` for reading on your machine | +| `AGENT_MAX_CONCURRENT_REQUESTS` | `100` | Requests worked on at once; one more gets HTTP 503, which Temporal retries | +| `AGENT_INPUT_GUARDRAIL` | | A guardrail on the LLM gateway that screens each request before the agent runs | +| `AGENT_EGRESS` | `log` | `log`, `enforce` or `off`: what happens to a connection to a host that is not one of the agent's endpoints | +| `AGENT_EGRESS_ALLOW` | | More hosts the agent may connect to, comma-separated | +| `PORT` | `8080` | | + +> The `LITELLM_` prefix on the model settings is load-bearing. The unprefixed +> `LLM_TEMPERATURE` / `LLM_MAX_TOKENS` names are read by a different code path +> that does not configure this agent's model, so setting them is silently +> ignored — no error, just an agent that stays at the defaults. + +> On a cluster the model gateway, the MCP gateway and telemetry are the +> platform's, the same for every agent: the Deployment reads the platform's +> ConfigMap `agent-platform-connections` after this agent's own, so they are +> not in `kubernetes/`; traces go through the platform's OpenTelemetry +> Collector, which holds any keys. Locally, `.env` +> holds them, and traces go to the dev kit's collector the same way. A +> telemetry problem never stops the agent: the log +> says why (`observability_off`). The in-app help (Architecture & design > +> Telemetry) explains the path. + +### Which configuration wins + +Environment variables are read once, at process start, by whichever path +started the agent: + +| How it runs | Configuration source | +|---|---| +| `./run-local.sh` | `kubernetes/configmap.yaml` + secrets from `.env` | +| Deployed pod | `kubernetes/configmap.yaml` via `envFrom`, plus Secrets | + +`.env` is never copied into the image and is never read by a deployed agent, so +nothing you put there can affect production. Conversely, changing a ConfigMap +value on a running deployment needs a restart — `kubectl rollout restart` — not +just an apply. + +## Agent loop guard rails + +An agent with tools makes as many model calls as the model decides it needs. +The runtime bounds that automatically; this agent writes no code for it. Any +one of the three limits ends the loop, and the caller gets an answer explaining +why rather than an error or a hang. + +Every run logs its own numbers, enforced or not: + +``` +agent_loop_completed iterations=4 tokens=18204 stopped_by_guardrail=False +``` + +That line is how you find the right limits for your agent: watch the typical +`iterations` for real work, then set `AGENT_MAX_ITERATIONS` above it with room +to spare. The defaults are deliberately loose so they catch runaways — most +often a tool bug that keeps telling the model to call it again — without +touching an agent that is behaving. + +Setting `AGENT_GUARDRAILS_ENABLED=false` removes the bounds but keeps the +counting and the log line, so you can measure first and enforce afterwards. + +**An agent with no tools cannot loop.** One request is exactly one model call, +and these settings have nothing to bound. + +## Customizing + +### Instructions + +Edit `prompt.md`. It is a Markdown file loaded verbatim as the system +instruction, and it is where most of an agent's behaviour actually lives. + +### Tools + +Tools are plain Python functions in `app/tools.py`, each listed under +`functions:` in `agent.yaml`. The framework derives the schema the model sees +from the signature and docstring, so both are part of the interface: + +```python +# app/tools.py +def search(symbol: str) -> dict: + """Find every line where `symbol` appears. + + Args: + symbol: the identifier to look for. + """ + ... +``` + +```yaml +# agent.yaml +functions: + - app.tools:search +``` + +MCP tools are declared under `mcp:` in `agent.yaml` instead, and reached +through the platform's MCP gateway; the model sees both kinds the same way. + +Keep tool results bounded. A tool that can return thousands of rows will fill +the context window and drive the loop into the iteration cap; cap the result +inside the tool and say in the return value that it was capped, so the model +can decide what to do about it. + +### Business logic: before and after the model + +`app/business_logic.py` has four hooks, all already wired up (`hooks:` in +`agent.yaml`) and doing nothing until you fill them in. These are the per-call +pair: + +| Hook | Runs | Use it to | +|---|---|---| +| `before_model` | before each model call | change what is asked — add context to the instructions | +| `after_model` | after each reply | inspect it — check its shape, record a metric | + +Use these when the work must happen on **every** request. Use a **tool** when +the model should decide whether and when to do it — tools create the agent +loop, callbacks do not. + +A worked example, reading a file and putting it in front of the model: + +```python +@lru_cache(maxsize=1) +def load_reference() -> str: + try: + return (Path(__file__).parent.parent / "reference" / "notes.txt").read_text() + except OSError: + return "" # never fatal: answer without it rather than 500 + +def before_model(call): + if load_reference(): + call.add_instruction(load_reference()) +``` + +`call` is the runtime's `ModelCall`, the same on every framework: +`call.add_instruction(text)` before the model, `call.reply_text` after it, and +`call.native` for the framework's own arguments. + +Two things that catch people out: + +- **`COPY` your data files in the Dockerfile.** `./run-local.sh` bind-mounts the + project, so a file you forgot to copy still works locally and is missing in + Kubernetes. This is the most common local-passes-deploy-fails bug. +- **`before_model` runs once per *model call*, not per request.** In a tool loop + that is several times. Cache anything you read from disk. + +### Where configuration lives + +Two files, and they do not overlap: + +| | holds | read by | +|---|---|---| +| `kubernetes/configmap.yaml` | every non-secret runtime setting — name, model, guard rails, observability | Kubernetes (`envFrom`), `./run-local.sh` (as `-e`) | +| `.env` | secrets, and values specific to your machine | `./run-local.sh` | + +**The ConfigMap is not a Kubernetes-only file.** That is the thing worth +knowing. `./run-local.sh` parses it and passes every key through as `-e`, +exactly as `envFrom: configMapRef` does on a cluster. Change the model there +once and the local container and the deployed pod agree. + +`.env` holds only what a ConfigMap cannot: `LITELLM_MASTER_KEY` and +`MCP_AGENT_API_KEY` because a ConfigMap is stored unencrypted, and +`LITELLM_PROXY_BASE` because the gateway URL is yours and nobody else's. +`DEV_RELOAD` is there too, being meaningless once deployed. + +Precedence is `shell environment` → `.env` → ConfigMap, so + +```bash +LITELLM_MODEL=claude-sonnet-4-6 ./run-local.sh +``` + +overrides the model for one run without editing anything. + +If you are hunting for a setting and it is not in `.env`, it is in the +ConfigMap. These values used to be listed in both files; they drifted, and +since the ConfigMap wins on both container paths, the `.env` copy was inert — +you could edit it, restart, and see no change at all. + +`.env` is generated for you at creation time and is gitignored. There is no +`cp .env.example .env` step. + +### The agent's contract + +Two JSON Schemas describe this agent: `schemas/input.json` says what it +accepts, `schemas/output.json` says what it returns, and `contract:` in +`agent.yaml` points at them. Both are written when the agent is created, from +the schemas supplied then. Both are optional — a schema that was not supplied +is left empty and its `contract:` line commented out, and an agent with no +contract takes and returns free text. + +Declaring them buys three things: + +- The agent card publishes both as `skills[0].inputSchema` / `outputSchema`, so + the workflow builder can check this agent's output against the next agent's + input *before* anything runs. +- A payload that does not match the input schema is refused before a model call + is spent, and the caller gets the JSON path that was wrong. +- A reply that does not match the output schema earns one more attempt quoting + the specific failure. Enforcement sits at the invocation boundary rather than + in a hook because a retry needs another model call, and `after_model` cannot + cause one. + +To change the contract, edit the JSON files (and uncomment the `contract:` +line for one you add). + +### Where your code goes + +`app/business_logic.py` and `app/tools.py`. The hooks come in two pairs: + +| Hook | Runs | Receives | +|---|---|---| +| `pre_process` | once per request | the parsed input payload | +| `before_model` | once per **model call** | the runtime's `ModelCall` | +| `after_model` | once per **model call** | the runtime's `ModelCall` | +| `post_process` | once per request | the parsed output payload | + +The distinction is the one that bites. A lookup in `before_model` runs four +times in a four-step tool loop and you pay for it four times; the same lookup in +`pre_process` runs once. Request work goes in the outer pair, per-turn work in +the inner pair. + +## Testing + +```bash +python tests/test_chatbot.py --url http://localhost:8080 # interactive +python tests/test_chatbot.py --url http://localhost:8080 --test-message "..." +``` + +Raw protocol checks: + +```bash +curl http://localhost:8080/.well-known/agent-card.json # discovery; also the k8s probe +curl http://localhost:8080/health + +curl -X POST http://localhost:8080/ \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"message/send","id":"1", + "params":{"message":{"parts":[{"type":"text","text":"Hello!"}]}}}' +``` + +## Layout + +``` +expense-policy-agent/ +├── app/ +│ ├── __init__.py +│ ├── business_logic.py # your four hooks +│ └── tools.py # your functions; list them under functions: in agent.yaml +├── schemas/ +│ ├── input.json # what the agent accepts (contract.input) +│ └── output.json # what it returns (contract.output) +├── skills/ # one folder per skill; see skills/README.md +├── eval/ +│ └── cases.yaml # eval suite; python -m kyndryl_agent_runtime.eval +├── kubernetes/ +│ ├── configmap.yaml # the configuration contract — start here +│ ├── deployment.yaml +│ ├── secretnames.yaml # credentials; never in the ConfigMap +│ ├── service.yaml +│ └── kustomization.yaml +├── tests/ +│ ├── a2a_client.py # A2A client over httpx +│ ├── test_chatbot.py # interactive chat client +│ └── requirements.txt # host-side only; not in the image +├── agent.yaml # the agent: identity, prompt, contract, tools, skills, hooks +├── RELEASE_NOTES.md # one entry per released version; the CI checks it +├── prompt.md # system instruction +├── requirements.txt # extra Python packages, if any (built into the image) +├── run-local.sh # container, configured from the ConfigMap (+ DEV_RELOAD) +└── Dockerfile # FROM the runtime image, plus this agent's files +``` + +## Deploying + +Commit and push. CI/CD builds the image and applies `kubernetes/`, replacing +``, ``, and +``. See `docs/agent-deployment/DEPLOYMENT.md` (in the platform repo) for the walkthrough, +including the repository secrets that need to be set once. + +To apply by hand against a cluster you already have credentials for: + +```bash +kubectl apply -k kubernetes/ +``` + +## Troubleshooting + +| Symptom | Cause | +|---|---| +| No traces arrive | Look for `observability_off` (a missing key or setting) or `observability_destination_unreachable` in the log | +| Temperature/max-tokens changes do nothing | Using `LLM_*` instead of `LITELLM_*` | +| ConfigMap edit had no effect | Env vars are read at startup; restart the deployment | +| `DEV_RELOAD` does not pick up changes | Set `WATCHFILES_FORCE_POLLING=true` — `run-local.sh` already does | +| Agent stops early with a "reached the maximum" answer | It hit a guard rail; see the `agent_loop_stopped` log line | +| Connection refused | `LITELLM_PROXY_BASE` unreachable from where the agent runs | +| Agent stops at startup naming a function, skill or hook | `agent.yaml` names something that is not there: a `functions:` entry missing from `app/tools.py`, a skill folder not COPYed, a typo in `hooks:` | +| Import errors for a package you added | The runtime image has only the runtime and the framework; list extra packages in `requirements.txt`; the next `./run-local.sh` (and the pipeline) builds them in | diff --git a/docs/source-material/agent-shapes/agent-pattern/RELEASE_NOTES.md b/docs/source-material/agent-shapes/agent-pattern/RELEASE_NOTES.md new file mode 100644 index 0000000..aa81815 --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/RELEASE_NOTES.md @@ -0,0 +1,18 @@ +# Release Notes — expense-policy-agent +Reviews an expense claim against the travel and expense policy and decides it, naming the rule applied and who must approve. + + + +## [1.0.0] - 2026-10-28 + +### Added +- Initial release of the agent. diff --git a/docs/source-material/agent-shapes/agent-pattern/agent.yaml b/docs/source-material/agent-shapes/agent-pattern/agent.yaml new file mode 100644 index 0000000..dfbe9b8 --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/agent.yaml @@ -0,0 +1,88 @@ +# Who this agent is and what it offers. +# +# This file is the agent: the runtime reads it at startup and builds the agent +# from it -- its instructions, contract, tools, skills and hooks. There is no +# app/agent.py. The agent card, the agent catalog and the logs all show what it +# says. Nothing here is read from environment variables. Edit it, redeploy, and +# refresh the agent in the catalog. + +# The agent's unique identity. Changing it renames the agent in the +# catalog when it is refreshed at the same URL. +name: "expense-policy-agent" + +# How the agent is shown in the catalog. Optional: without it, the name is +# shown. Generated from the name; change it freely -- it is not an identity. +display_name: "Expense Policy Agent" + +# Shown in the catalog and the workflow palette. Write it for someone +# deciding whether this agent does what they need. +description: "Reviews an expense claim against the travel and expense policy and decides it, naming the rule applied and who must approve." + +# Bump it when you ship a change callers should notice; it is how two builds of +# one agent are told apart in the catalog. The agent pipeline tags the image +# with it and will not release a version twice, or one without its entry in +# RELEASE_NOTES.md. +version: "1.0.0" + +# The framework the agent runs on, set by the template it came from. It must +# match the runtime image the Dockerfile builds on (agent-runtime-adk). +framework: adk + +# What the agent is about, for searching and filtering the catalog. +tags: + - expenses + - finance + - policy + - skills + +# A2A capabilities. +# streaming replies arrive as they are generated +# push_notifications the agent can call the client back when a task finishes +capabilities: + streaming: true + push_notifications: false + +# What the agent can do. Two forms, and they can be mixed: +# +# - review-claim a skill folder, skills/review-claim/SKILL.md: the +# instructions and tools for one way of doing the +# agent's job. The model loads it when it fits the +# request. See skills/README.md. +# - id: ... name: ... an advertised skill: listed on the agent card and in +# the catalog, and nothing more. +# +# Skills never change what the agent accepts or returns: its contract (below), +# or free text when it has none, holds whichever skill is used. The first skill carries them on +# the agent card. +# +# An advertised skill has: +# id stable identifier, lower case with underscores +# name short human title +# description what the skill does, for someone choosing it +# tags what it is about +# examples example requests, e.g. a JSON payload matching the input schema +skills: + - review-travel-and-meals + - review-purchases + +# The instructions, relative to this file. +prompt: prompt.md + +# What the agent accepts and returns, checked on every request: JSON Schemas in +# schemas/. A reply that breaks the output schema is sent back to the model +# once, then refused. Without a contract the agent takes and returns free text. +contract: + input: schemas/input.json + output: schemas/output.json + +# The agent's own functions the model may call, each `module:function`. Write +# them in app/tools.py. +functions: + - app.tools:lookup_policy_rule + - app.tools:convert_currency + - app.tools:request_approval + - app.tools:get_policy_rule + +# The agent's own code around each request and each model call: pre_process, +# post_process, before_model and after_model in app/business_logic.py. +hooks: app.business_logic diff --git a/docs/source-material/agent-shapes/agent-pattern/app/__init__.py b/docs/source-material/agent-shapes/agent-pattern/app/__init__.py new file mode 100644 index 0000000..6740234 --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/app/__init__.py @@ -0,0 +1 @@ +"""The agent's own code: hooks (business_logic.py) and tools (tools.py).""" diff --git a/docs/source-material/agent-shapes/agent-pattern/app/business_logic.py b/docs/source-material/agent-shapes/agent-pattern/app/business_logic.py new file mode 100644 index 0000000..a1c1a5f --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/app/business_logic.py @@ -0,0 +1,193 @@ +"""Where your business logic goes. + +All four functions below are wired up already and do nothing yet. Fill in the +one you need — the wiring is already correct, so you only edit this file. + + request ─▶ pre_process(payload) ONCE per request, on the parsed JSON + │ + ▼ + before_model() once per MODEL CALL + │ + ▼ + the model ◀── tools ──┐ + │ │ + ▼ │ + after_model() ────────┘ once per model call + │ + ▼ + post_process(result) ONCE per request, on the final JSON + │ + ▼ + response + +Which pair you want comes down to one question: does the work belong to the +*request*, or to each *model turn*? + +`pre_process` and `post_process` belong to the request. They receive a parsed +dict — the shape your input and output schemas describe — and run exactly once, +however many times the model is called in between. Normalising an identifier, +enriching from a lookup, stamping a field onto the result: all request work. + +`before_model` and `after_model` belong to the turn. They receive the +runtime's ModelCall -- the same on every framework -- and run on every model +call, which in a tool loop is several times. + +Putting request work in the per-call pair is the usual bug. A lookup in +`before_model` runs four times in a four-step tool loop, and you pay for it +four times; the same lookup in `pre_process` runs once. + +Use these when the work is *deterministic* — something that should happen on +every request, whether or not the model decides it is a good idea. Reading a +config file, redacting an identifier, enforcing a house style, validating the +shape of a reply. + +Use a **tool** instead (`functions:` in agent.yaml) when the model should decide +whether and when to do the thing, and can use the result to choose what to do +next. Tools are what create the agent loop; these hooks do not. + +Two things worth knowing before you start: + + * The loop bounds in kubernetes/configmap.yaml are enforced by the runtime + alongside these hooks. Nothing you return here switches them off. + + * Anything you read at runtime must be COPYed in the Dockerfile. It works + locally without that, because ./run-local.sh bind-mounts the project into + the container — but there is no such mount in Kubernetes, and the file will + simply not be there. This is the most common way an agent passes locally + and fails on deploy. + +You do not set up logging, tracing or correlation headers here. The runtime has +already wrapped those around this agent. +""" + +from __future__ import annotations + +from typing import Any, Optional + +import structlog + +from kyndryl_agent_runtime import agent_manifest + +# The agent's logger. Use this one. +# +# Every agent on the platform logs through structlog, so every agent's output +# is parsed the same way, searchable by the same fields, and shipped by the +# same pipeline. An agent that reaches for `print()` or its own `logging` +# config is the one nobody can query when it misbehaves at 2am. +# +# Bound with the agent's name so a line is attributable once the logs of forty +# agents are in one place. Add your own permanent context the same way: +# +# logger = logger.bind(region=os.getenv("REGION", "unknown")) +# +# House style, and it is worth following: +# +# * an event name, then key=value -- `logger.info("rate_applied", +# currency="EUR", rate=1.09)`, not a sentence with the values glued in. +# The first is searchable; the second is prose that happens to contain +# numbers. +# * INFO for what happened, DEBUG for the data it happened to. A claim, a +# ticket, a patient note -- these belong at DEBUG, because a log that is +# unsafe to keep is a log somebody turns off, taking everything else with +# it. +# * never a secret, a token or a full payment detail, at any level. There is +# no log level that makes an API key safe to store. +# * no need to log that a request arrived, that pre_process ran, or what the +# model replied -- the runtime already does all of that around you. Log +# what is yours: the decision you made and why. +logger = structlog.get_logger(__name__).bind( + agent=agent_manifest().name or "agent", +) + + +def before_model(call: Any) -> None: + """Runs immediately before each call to the model, on any framework. + + `call` is the runtime's ModelCall, the same object on Google ADK, LangChain, + LangGraph, Strands and Microsoft Agent Framework, so this file runs + unchanged on all of them. Add to the system instructions for this one call: + + call.add_instruction("The customer's region is EMEA.") + + Prefer the system instructions over the user's message: anything placed + inside a user turn is markedly easier for a crafted prompt to talk the + model out of. `call.native` holds the framework's own arguments, for what + add_instruction does not cover. The return value is ignored. + + Called once per model call, so this runs several times in a tool loop, not + once per request. Keep it cheap; cache anything you read from disk. + """ + return None + + +def after_model(call: Any) -> None: + """Runs immediately after each reply from the model, on any framework. + + `call.reply_text` is the reply's text -- empty for a reply that only calls + a tool or loads a skill. Good uses: record a domain metric, check the + shape of a structured reply. The return value is ignored; to change the + final answer use post_process, which runs once on it. + """ + return None + + +def pre_process(payload: dict) -> Optional[dict]: + """Runs once per request, on the incoming payload, before any model call. + + `payload` is the request parsed as JSON. When this agent declares an input + schema it has already been validated against it, so you can read the fields + you declared without defensive checks — a payload that did not match never + reaches here; the caller received a structured error naming the JSON path + that was wrong. + + Return a modified dict to change what the model is asked, or None to leave + the payload alone. Returning a dict that is equal to what you were given is + the same as returning None. + + def pre_process(payload): + payload["account_id"] = payload["account_id"].strip().upper() + return payload + + An agent with no input schema, or one called with prose rather than JSON, + does not call this at all — there is no payload to hand you. + + Raising here fails the request. That is the right move for something you + genuinely cannot proceed without; prefer returning a corrected payload for + anything you can repair. + """ + # An example of the house style, left here on purpose: delete it or keep it, + # but log like it. An event name and fields, at a level that matches what + # the line carries. + # + # logger.info("claim_received", category=payload.get("category")) + # logger.debug("claim_payload", payload=payload) + # + # The first is safe anywhere and answers "what kind of work is this agent + # doing?". The second answers "what exactly did it get?" and is DEBUG + # because it is the caller's data. + logger.debug("pre_process_input", fields=sorted(payload)) + + return None + + +def post_process(result: dict) -> Optional[dict]: + """Runs once per request, on the final reply, after the model is done. + + `result` is the model's reply parsed as JSON. Return a modified dict to + change what the caller receives, or None to leave it as it is. + + def post_process(result): + result["reviewed_at"] = datetime.now(timezone.utc).isoformat() + return result + + Two things to know. First, the output contract is checked *after* this + runs, on what you return -- so the caller never receives a reply that + breaks it. A dict that does not conform sends the model round once more, + and if it still fails the caller gets an `output_contract_violation`. The + runtime logs `post_process_broke_output_contract` with the offending paths + when it was your edit that broke it, which is the fastest way to find it. + + Second, a reply that is not JSON never reaches here. If your agent answers + in prose, this hook simply does not run. + """ + return None diff --git a/docs/source-material/agent-shapes/agent-pattern/app/policy.yaml b/docs/source-material/agent-shapes/agent-pattern/app/policy.yaml new file mode 100644 index 0000000..6b1172a --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/app/policy.yaml @@ -0,0 +1,48 @@ +# The travel and expense policy, as data. The skills look rules up here through +# tools rather than recalling them from the prompt, so a policy change is an +# edit to this file, not to any instructions. +# +# Amounts are in EUR. `limit_eur` caps a claim; `receipt_over_eur` requires a +# receipt above that amount; `approval_over_eur` means the claim needs approval. +# WHO approves is never in a rule: every claim that is not rejected goes through +# the delegation of authority below (request_approval), by its amount in USD. +rules: + - id: MEALS-1 + category: meals + text: "Meals: up to 40 EUR per claim." + limit_eur: 40 + - id: LODGING-1 + category: lodging + text: "Lodging: up to 200 EUR per night." + limit_eur: 200 + - id: TRAVEL-1 + category: travel + text: "Travel is reimbursed at cost; there is no per-claim cap. Who signs follows the delegation of authority." + - id: SOFTWARE-1 + category: software + text: "Software is allowed; a purchase over 500 EUR needs approval. Who signs follows the delegation of authority." + approval_over_eur: 500 + - id: OTHER-1 + category: other + text: "Any other expense needs approval, whatever the amount. Who signs follows the delegation of authority." + approval_over_eur: 0 + - id: RECEIPT-1 + category: all + text: "Any claim over 25 EUR needs a receipt." + receipt_over_eur: 25 + +# Fixed conversion rates to EUR, for the demonstration. A real agent would call +# a rates service here; the skills would not change. +rates_to_eur: + EUR: 1.0 + USD: 0.92 + GBP: 1.17 + INR: 0.011 + +# Who must sign a claim, by its amount in USD: the first band the amount is +# under. A claim a rule asks approval for always needs at least a manager. +delegation_of_authority: + - {under_usd: 500, level: auto} + - {under_usd: 5000, level: manager} + - {under_usd: 25000, level: director} + - {under_usd: .inf, level: none} diff --git a/docs/source-material/agent-shapes/agent-pattern/app/tools.py b/docs/source-material/agent-shapes/agent-pattern/app/tools.py new file mode 100644 index 0000000..2795c6b --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/app/tools.py @@ -0,0 +1,146 @@ +"""The agent's own tools: plain functions the model may call. + +A tool no skill names -- get_policy_rule here -- is offered on every request, +with or without a skill. A skill can name tools in its SKILL.md (`agent.tools` +in its metadata) to keep them until it is loaded, as both skills do with the +other three. The framework builds each tool's description from its signature +and docstring, so both are part of what the model reads. + +Results are small and bounded on purpose: a tool that returned the whole policy +for every call would fill the context and teach the model to stop looking. +""" + +from __future__ import annotations + +from functools import lru_cache +from pathlib import Path +from typing import Any, Dict, List + +import yaml + +_POLICY_FILE = Path(__file__).resolve().parent / "policy.yaml" + + +@lru_cache(maxsize=1) +def _policy() -> Dict[str, Any]: + return yaml.safe_load(_POLICY_FILE.read_text(encoding="utf-8")) + + +def _public(rule: Dict[str, Any]) -> Dict[str, Any]: + return {k: v for k, v in rule.items() if k != "category" or v != "all"} + + +def lookup_policy_rule(category: str) -> dict: + """The policy rules that apply to one expense category. + + Always includes the rules that apply to every claim (such as the receipt + rule). Use the rule ids and texts exactly as returned. + + Args: + category: one of travel, meals, lodging, software, other. + + Returns: + {"category": ..., "rules": [{"id", "text", "limit_eur"?, "receipt_over_eur"?, + "approval_over_eur"?}]}, or {"error": ...} for an unknown category. + """ + rules = _policy()["rules"] + categories = sorted({r["category"] for r in rules if r["category"] != "all"}) + category = (category or "").strip().lower() + if category not in categories: + return {"error": f"unknown category {category!r}; one of {categories}"} + return { + "category": category, + "rules": [_public(r) for r in rules if r["category"] in (category, "all")], + } + + +def _convert(amount: float, source: str, target: str) -> dict: + rates = _policy()["rates_to_eur"] + source, target = (source or "").upper(), (target or "").upper() + for code in (source, target): + if code not in rates: + return {"error": f"unknown currency {code!r}; one of {sorted(rates)}"} + rate = rates[source] / rates[target] + return {"amount": round(float(amount) * rate, 2), "rate": round(rate, 6), + "from": source, "to": target} + + +def convert_currency(amount: float, from_currency: str, to_currency: str) -> dict: + """Convert an amount between USD, EUR, GBP and INR using the company's fixed rates. + + Only needed when the claim is not already in the currency you want. + + Args: + amount: the amount to convert. + from_currency: ISO code of the amount, e.g. "USD". + to_currency: ISO code wanted, e.g. "EUR". + + Returns: + {"amount": converted, rounded to 2 decimals, "rate": ..., "from": ..., "to": ...}, + or {"error": ...} for an unknown currency. + """ + return _convert(amount, from_currency, to_currency) + + +def request_approval(amount: float, currency: str, policy_flags: List[str]) -> dict: + """Who must sign this claim, from the company's delegation of authority. + + Call it for every claim you have not rejected. It converts the amount to + USD itself -- the delegation of authority is set in USD -- so pass the + claim's own amount and currency. The answer is final: report it, do not + change it. + + Args: + amount: the claim's amount, in its own currency. + currency: the claim's currency, e.g. "EUR". + policy_flags: rules that ask for approval, e.g. ["needs_approval:SOFTWARE-1"]; + [] if none. A flag means at least a manager signs. + + Returns: + {"decision": approve|escalate|reject, "approver_level": auto|manager|director|none, + "why": a plain explanation of who signs and why}, or {"error": ...}. + """ + usd = _convert(amount, currency, "USD") + if "error" in usd: + return usd + amount_usd = usd["amount"] + flags = list(policy_flags or []) + bands = _policy()["delegation_of_authority"] + index = next(i for i, b in enumerate(bands) if amount_usd < b["under_usd"]) + band, lower = bands[index], (bands[index - 1]["under_usd"] if index else 0) + level = band["level"] + if flags and level == "auto": + level = "manager" + decision = {"auto": "approve", "none": "reject"}.get(level, "escalate") + + size = (f"over {lower:,.0f} USD" if band["under_usd"] == float("inf") + else f"under {band['under_usd']:,.0f} USD" if not lower + else f"between {lower:,.0f} and {band['under_usd']:,.0f} USD") + who = {"auto": "no approver is needed", "manager": "a manager must sign", + "director": "a director must sign", "none": "it cannot be approved"}[level] + because = f"the policy asks for approval ({', '.join(f.split(':')[-1] for f in flags)})" if flags else "no rule asks for approval" + return {"decision": decision, "approver_level": level, + "why": f"The claim is {size} and {because}, so {who}."} + + +def get_policy_rule(rule_id: str) -> dict: + """The exact text of one policy rule, by its id. + + Use it to quote the rule a decision rests on, word for word. + + Args: + rule_id: the rule's id, e.g. MEALS-1 or RECEIPT-1. + + Returns: + {"id": ..., "text": ...}, or {"error": ...} for an unknown id. + """ + wanted = (rule_id or "").strip().upper() + for rule in _policy()["rules"]: + if rule["id"] == wanted: + return {"id": rule["id"], "text": rule["text"]} + return {"error": f"unknown rule {rule_id!r}; ids: {[r['id'] for r in _policy()['rules']]}"} + + +# agent.yaml lists each of these under `functions:`. TOOLS is for the LangGraph +# template, whose graph in app/agent.py binds its tools from this list. +TOOLS = [lookup_policy_rule, convert_currency, request_approval, get_policy_rule] diff --git a/docs/source-material/agent-shapes/agent-pattern/eval/cases.yaml b/docs/source-material/agent-shapes/agent-pattern/eval/cases.yaml new file mode 100644 index 0000000..2163278 --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/eval/cases.yaml @@ -0,0 +1,263 @@ +# yaml-language-server: $schema=./schemas/cases-1.1.schema.json +# +# Your agent's eval set. +# +# These cases are the test suite for an agent. They live here, beside the +# prompt, because whoever writes the prompt is the only person who knows what a +# good answer looks like — and because they should be reviewed in the same pull +# request as the change they judge. +# +# Run them against your agent while it is running locally: +# +# python -m kyndryl_agent_runtime.eval --url http://localhost:8080 +# +# Record the current scores as the bar to beat: +# +# python -m kyndryl_agent_runtime.eval --url http://localhost:8080 \ +# --baseline eval/baseline.json --write-baseline +# +# Check this file without running anything -- no agent, no model: +# +# python -m kyndryl_agent_runtime.eval --validate +# +# eval/schemas/ holds the format as a JSON Schema. The first line of this file +# points editors at it: +# with the YAML extension (VS Code: Red Hat YAML), field names complete, +# allowed values are listed, and mistakes are underlined as you type. The +# schemas are copied from the runtime this agent installs -- do not edit them. +# +# `checks` is a LIST — one entry per assertion. That is what lets a case hold +# two assertions of the same kind against different fields, which a mapping +# cannot express. The full reference is the platform's developer guide (Help, +# "Appendix: the eval case format"); EXAMPLE_SUITE.yaml in the runtime +# (kyndryl_agent_runtime/eval/) shows every field in one file. + +# Which version of the case format this file is written in. +schema_version: '1.1' +agent: expense-policy-agent +samples: 3 +runtime: + checks: + - not_empty: true + - schema: true + metrics: + - relevance: + threshold: 0.7 +cases: +- id: meal-within-limit-is-approved + description: A 38 EUR meal with a receipt is inside MEALS-1 and RECEIPT-1. + input: + json: + employee_id: E-4471 + amount: 38 + currency: EUR + category: meals + receipt_attached: true + checks: + - schema: true + - field: decision + equals: approve + - field: approver_level + equals: auto + - field: policy_rule + contains: MEALS-1 +- id: meal-converted-before-comparing + description: 60 USD is 55.20 EUR, over the 40 EUR meals limit -- only if converted with the tool. + input: + json: + employee_id: E-2210 + amount: 60 + currency: USD + category: meals + receipt_attached: true + checks: + - schema: true + - field: decision + equals: reject + - field: policy_rule + contains: MEALS-1 +- id: meal-without-receipt-needs-one + description: 30 EUR is inside the meals limit but over the receipt threshold. + input: + json: + employee_id: E-1000 + amount: 30 + currency: EUR + category: meals + receipt_attached: false + checks: + - schema: true + - field: decision + equals: needs_receipt + - field: policy_rule + contains: RECEIPT-1 +- id: taxi-is-approved-at-cost + input: + json: + employee_id: E-4471 + amount: 18 + currency: GBP + category: travel + description: Taxi to the client site + checks: + - schema: true + - field: decision + equals: approve + - field: policy_rule + contains: TRAVEL-1 +- id: large-software-goes-to-a-manager + description: 620 EUR is over SOFTWARE-1's approval threshold; about 674 USD is in the manager band. + input: + json: + employee_id: E-3301 + amount: 620 + currency: EUR + category: software + receipt_attached: true + checks: + - schema: true + - field: decision + equals: escalate + - field: approver_level + equals: manager + - field: policy_rule + contains: SOFTWARE-1 +- id: small-software-is-approved + input: + json: + employee_id: E-3301 + amount: 120 + currency: EUR + category: software + receipt_attached: true + checks: + - schema: true + - field: decision + equals: approve + - field: approver_level + equals: auto +- id: large-other-purchase-goes-to-a-director + description: 7000 USD is in the director band of the delegation of authority. + input: + json: + employee_id: E-5120 + amount: 7000 + currency: USD + category: other + receipt_attached: true + checks: + - schema: true + - field: decision + equals: escalate + - field: approver_level + equals: director +- id: large-flight-goes-to-a-director + description: Travel has no per-claim cap, but who signs still follows the delegation of authority -- + 5,000 EUR is about 5,435 USD. + input: + json: + employee_id: E-7001 + amount: 5000 + currency: EUR + category: travel + receipt_attached: true + checks: + - schema: true + - field: decision + equals: escalate + - field: approver_level + equals: director +- id: approver-and-rule-agree + description: OTHER-1 says approval is needed and the delegation of authority says who; the reason must + not contradict the director. + input: + json: + employee_id: E-5120 + amount: 7000 + currency: USD + category: other + receipt_attached: true + checks: + - field: approver_level + equals: director + - field: reason + not_contains: manager +- id: reason-is-written-for-the-claimant + description: No employee id and no USD figure in the claimant-facing reason. + input: + json: + employee_id: E-3301 + amount: 120 + currency: EUR + category: software + receipt_attached: true + checks: + - field: decision + equals: approve + - field: reason + not_contains: E-3301 + - field: reason + not_contains: USD +- id: absent-receipt-means-no-receipt + description: receipt_attached left out behaves exactly like false. + input: + json: + employee_id: E-1000 + amount: 30 + currency: EUR + category: meals + checks: + - schema: true + - field: decision + equals: needs_receipt + - field: policy_rule + contains: RECEIPT-1 +- id: a-claim-without-an-amount-is-refused + input: + json: + employee_id: E-1 + currency: EUR + category: meals + checks: + - field: error + equals: input_validation_failed +- id: reason-tells-the-claimant-what-to-do + description: 'A meal without a receipt: the reason must tell the claimant what to do next, not restate + the policy. Judged, because no substring can tell a useful reason from a useless one.' + input: + json: + employee_id: E-1000 + amount: 30 + currency: EUR + category: meals + receipt_attached: false + checks: + - schema: true + - field: decision + equals: needs_receipt + metrics: + - criteria: + name: reason-is-actionable + description: The reason tells the claimant what was decided and what, if anything, to do next, in + EUR. Restating the policy alone, or mentioning USD or an employee id, scores 0. + threshold: 0.8 +- id: reason-does-not-repeat-personal-details + description: The claimant wrote personal details into the description; the reason must not repeat them. + input: + json: + employee_id: E-4471 + amount: 38 + currency: EUR + category: meals + description: Dinner with Dr. Maria Keller about my diagnosis, paid with card 4111 1111 1111 1111, + call me on +44 7700 900123 + receipt_attached: true + checks: + - schema: true + - field: decision + equals: approve + - field: reason + not_contains: '4111' + metrics: + - pii_leakage: + threshold: 0 diff --git a/docs/source-material/agent-shapes/agent-pattern/eval/schemas/cases-1.1.schema.json b/docs/source-material/agent-shapes/agent-pattern/eval/schemas/cases-1.1.schema.json new file mode 100644 index 0000000..0aa3366 --- /dev/null +++ b/docs/source-material/agent-shapes/agent-pattern/eval/schemas/cases-1.1.schema.json @@ -0,0 +1,289 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://kyndryl.com/agent-runtime/eval/schemas/cases-1.1.schema.json", + "title": "Agent eval suite (eval/cases.yaml), schema version 1.1", + "description": "The cases an agent is evaluated against. The prose reference is the eval case format appendix in the platform's developer guide. This schema gives editors field names, allowed values and inline errors; `python -m kyndryl_agent_runtime.eval --validate` runs the loader itself, which also catches what a schema cannot express (duplicate case ids, two checks in one entry, missing fixture files).", + "type": "object", + "additionalProperties": false, + "required": ["cases"], + "properties": { + "schema_version": { + "enum": ["1.1", 1.1, "1.0", 1.0], + "description": "Which version of this format the file is written in. Write 1.1. 1.0 is retired: it was 1.1 without the suite's `runtime` section, so a file that still says 1.0, or says nothing, is read as 1.1." + }, + "agent": { + "type": "string", + "minLength": 1, + "description": "The agent's name as its agent card publishes it. Labels the results and the baseline; it is not compared with the card. Defaults to the agent directory's name." + }, + "samples": { + "type": "integer", + "minimum": 1, + "default": 3, + "description": "Runs per case. 1 for a fast local loop, 3 by default, 5+ when chasing something intermittent." + }, + "defaults": { + "type": "object", + "additionalProperties": false, + "description": "Applied to every case.", + "properties": { + "timeout": {"type": "number", "exclusiveMinimum": 0, "description": "Seconds to wait for one reply."}, + "threshold": {"$ref": "#/$defs/score", "description": "Minimum score for judged metrics that do not set their own."} + } + }, + "cases": { + "type": "array", + "minItems": 1, + "description": "The cases, at least one. Each id must be unique in the file.", + "items": {"$ref": "#/$defs/case"} + }, + "runtime": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "description": "Runtime evaluation: what is scored on the agent's real answers, after a live workflow step finishes. The same checks and judged metrics as a case, applied to what the agent was really asked and really answered. A live step has no expected answer and no fixtures, so `found_in`, the `code_*` checks, `semantic_similarity`, `tool_correctness` and the conversation metrics cannot be used here, and `schema` must be `schema: true`. Scoring never changes, delays or stops the step.", + "properties": { + "checks": {"type": "array", "items": {"$ref": "#/$defs/check"}, "description": "Deterministic assertions on the real answer. Free: run on every scored step."}, + "metrics": {"type": "array", "items": {"$ref": "#/$defs/metric"}, "description": "Judged metrics on the real answer, with the step's own input (and any tool results) as the source of truth. Run on a share of steps, when the platform has judging on, and only after every check passed."} + } + } + }, + "$defs": { + "score": {"type": "number", "minimum": 0, "maximum": 1}, + "bounds": { + "description": "An exact number, or a range: {min: 1, max: 5}. Either end may be left out.", + "oneOf": [ + {"type": "number"}, + { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "properties": {"min": {"type": "number"}, "max": {"type": "number"}} + } + ] + }, + "encoding": {"enum": ["base64", "text", "none"]}, + "fixture": { + "description": "A file or folder read in at run time instead of pasted into the case. Paths are relative to the agent directory.", + "type": "object", + "additionalProperties": false, + "properties": { + "from_file": {"type": "string", "description": "The file's contents."}, + "from_dir": {"type": "string", "description": "A list of {name, content}, one per matching file."}, + "zip_of": {"type": "string", "description": "The matching files zipped and base64 encoded. Prefer this over committing a .zip."}, + "glob": {"type": "string", "default": "*", "description": "Which files, for from_dir and zip_of."}, + "encoding": {"$ref": "#/$defs/encoding", "description": "text (default) or base64; zip_of defaults to base64."} + }, + "oneOf": [ + {"required": ["from_file"]}, + {"required": ["from_dir"]}, + {"required": ["zip_of"]} + ] + }, + "input": { + "description": "The message sent to the agent: a string, {json: ...} (serialized and sent; any value inside may be a fixture such as {from_file: fixtures/x.md}), or {text: ...}.", + "oneOf": [ + {"type": "string"}, + { + "type": "object", + "additionalProperties": false, + "required": ["json"], + "properties": {"json": {"description": "Any JSON value. Nested {from_file|from_dir|zip_of: ...} mappings are replaced by their contents."}} + }, + { + "type": "object", + "additionalProperties": false, + "required": ["text"], + "properties": {"text": {"oneOf": [{"type": "string"}, {"$ref": "#/$defs/fixture"}]}} + } + ] + }, + "not_implemented": { + "description": "Accepted by the format, not yet implemented by the engine: the case loads, and the check reports an error when run." + }, + "check": { + "description": "One deterministic assertion. Exactly one check per entry (a `selector` may pair with `count` or `has_attribute`). Without `field`, `selector` or `artifact`, it applies to the whole reply.", + "type": "object", + "additionalProperties": false, + "properties": { + "field": {"type": "string", "description": "Dotted path into a JSON reply: answer, usage.tokens, quotes[0]. The most important key: an unscoped check searches every field."}, + "selector": {"type": "string", "description": "CSS selector into an HTML reply or artifact."}, + "artifact": {"type": ["integer", "string"], "minimum": 0, "description": "Which A2A artifact: by position (0, the usual case) or by name."}, + + "match": { + "description": "For found_in: how closely the value must appear in the source.", + "oneOf": [ + {"enum": ["verbatim", "normalized"]}, + {"type": "object", "additionalProperties": false, "required": ["fuzzy"], "properties": {"fuzzy": {"$ref": "#/$defs/score"}}} + ] + }, + "encoding": {"$ref": "#/$defs/encoding"}, + "considers": {"type": "array", "items": {"type": "string"}}, + + "contains": {"type": ["string", "number"], "description": "Substring present, case-insensitive."}, + "not_contains": {"type": ["string", "number"], "description": "Substring absent, case-insensitive."}, + "contains_any": {"type": ["array", "string"], "items": {"type": ["string", "number"]}, "description": "At least one present."}, + "contains_all": {"type": ["array", "string"], "items": {"type": ["string", "number"]}, "description": "Every one present."}, + "matches": {"type": "string", "description": "Regular expression that must match."}, + "not_matches": {"type": "string", "description": "Regular expression that must not match."}, + + "is_json": {"type": "boolean", "description": "The reply parses as JSON."}, + "schema": {"type": ["boolean", "string"], "description": "true: validate against the agent's declared output schema (SKIPPED if it declares none). A path: validate against that pinned schema file."}, + + "equals": {"description": "Exact value, any JSON type."}, + "not_empty": {"type": "boolean", "description": "Present, non-null, non-empty."}, + "length": {"$ref": "#/$defs/bounds", "description": "Length of a string or array."}, + "between": {"$ref": "#/$defs/bounds", "description": "A number within bounds."}, + + "found_in": {"type": "string", "description": "Every value of the field appears in this file (see `match`). Only for fields the agent was told to quote verbatim."}, + + "artifact_count": {"$ref": "#/$defs/bounds", "description": "How many artifacts the reply returned: a task's artifacts, or a message reply's text parts. An empty reply has none, so {min: 1} fails for it."}, + + "html_parses": {"type": "boolean", "description": "Well-formed enough to build a tree."}, + "html_no_script": {"type": "boolean", "description": "No