Files
cp1-agents/.agents/CONTEXT.md
Jonathan Boniface c14a94f33b
Some checks failed
check agents / check (push) Failing after 12s
Add hyperscaler discovery MCP servers and Well-Architected guidance
azure-discovery, aws-discovery and gcp-discovery collect read-only metadata
on servers, workloads, Kubernetes clusters, networks, data stores, policies
and provider recommendations. Credentials arrive per call from the vault.
Replies are paged, scrubbed of secrets and anonymised, and throttled calls
back off. cloud-knowledge searches each provider's Well-Architected guidance
from fixed lists only, so no customer detail can leave the platform.

Adds shared skills, the render and test tooling, a public Python Dockerfile
until the hardened base image is reachable, the customer access guide, the
implementation plan and the Vault Service platform issue.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-30 20:11:57 +00:00

62 lines
5.4 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; 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 <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; `cloud-knowledge` takes Kyndryl's, tenant-wide. 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`. 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/<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 |