Files
cp1-agents/.agents/CONTEXT.md
Jonathan Boniface f659564208 Platform scripts, MCP servers, deployment and docs for the KAB runs
- Scripts to run workflows from a YAML context or run inputs (kab_run_workflow.py, with
  --input name=@file), store per-project discovery connections, bootstrap agent MCP keys,
  refresh the KAB token, publish reports and build estate snapshots.
- Hyperscaler discovery servers extended in place; cloud-knowledge folded into them.
- deploy/crucible-kab-dev.yaml: the Discovery package agent and the Assessment agents.
- Platform issue write-ups and current-wiring notes under docs/platform-issues/.

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

62 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Context: cp1-agents
Repository-wide facts for coding agents. Pattern- and agent-specific context lives in `individual-agents/<Feature>/.agents/` and in `<agent>/.agents/`.
## Layout
- **`<pattern>/<Feature>/<agent>/`.** The patterns are `sub-agents` and `individual-agents`. A Feature folder is named `ALZ-F0N: <Feature> Workflow Agent`. ALZ-F01 is built in both patterns; ALZ-F02 is built in the individual pattern only (not deployed); the 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 <Feature folder>` (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/`.
## MCP servers
`mcp-servers/` holds rendered servers: never edit `server.py` by hand. See `mcp-servers/README.md`. `azure-discovery`, `aws-discovery` and `gcp-discovery` take a customer credential per project. Well-Architected guidance is a tool on the Azure and GCP servers; the separate `cloud-knowledge` server was retired on 2026-11-04. They're deployed to `mcp-servers` on public Python images (not hardened; no customer data yet), are registered in the `CP1 Agentic Landing Zone` tenant (`6ae37d13999438461a529409`), aren't tested on a real cloud, and no agent declares them.
## 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: `<agent>/docs/adr/`. Individual agents: `individual-agents/<Feature>/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/<component>:<version>`.
- **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/<profile>.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 `<agent>-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://<agent>.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`. The cluster's LiteLLM serves `gpt-4o`, `gpt-5.4`, `gpt-5.6-sol` and `text-embedding-3-small` (checked 2026-11-01); `claude-sonnet-5-5` isn't served there, and a call to it fails.
## 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/<engagement>/<run>/` |
| 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 |