Impose Human Approval on an Agent the Developer Built

import json
import os

from google.adk import Agent
from google.adk.models.lite_llm import LiteLlm
from google.adk.tools.mcp_tool.mcp_toolset import (
    MCPToolset,
    StreamableHTTPConnectionParams,
)

from .prompts_loader import build_instruction

# Set the OTel service name before the providers are initialised, so traces for
# this agent are attributable per agent.
os.environ.setdefault("OTEL_SERVICE_NAME", "__NAME__")

from google.adk.telemetry.setup import maybe_set_otel_providers  # noqa: E402

maybe_set_otel_providers()


INSTRUCTION = """
You are an SRE assistant for a small Kubernetes estate. You have tools from the
sre-tools MCP server to inspect and repair workloads.

Work in this order:

1. Look before you touch. Use list_pods to find unhealthy pods, get_pod_logs to
   read why they are failing, and describe_deployment to check replica counts and
   images.
2. Say what you found. State the diagnosis in one or two sentences, citing the
   specific evidence from the logs or the restart counts.
3. Then act, if acting is warranted. restart_deployment and scale_deployment
   change the running system. Before calling either, say in one sentence what you
   are about to change and why it follows from the diagnosis.
4. Report what changed. After a tool returns, summarise the new state.

Some tool calls take a while to come back. That is normal; wait for the result
rather than retrying or assuming failure.

If a tool call comes back refused or denied, report the reason you were given,
verbatim, and stop. Do not retry it, do not work around it, and do not try a
different tool to achieve the same effect.
"""


def create_model():
    return LiteLlm(model="anthropic/claude-haiku-4-5")


def _gated_tools():
    raw = os.environ.get("KAGENT_REQUIRE_APPROVAL", "")
    return {t.strip() for t in raw.split(",") if t.strip()}


def build_mcp_tools():
    gated = _gated_tools()

    raw = os.environ.get("MCP_SERVERS_CONFIG", "")
    try:
        servers = json.loads(raw) if raw else []
    except ValueError:
        servers = []

    timeout = float(os.environ.get("MCP_CONNECT_TIMEOUT", "60"))
    terminate = os.environ.get("MCP_TERMINATE_ON_CLOSE", "true").lower() != "false"

    def conn(url):
        return StreamableHTTPConnectionParams(
            url=url, timeout=timeout, terminate_on_close=terminate
        )

    toolsets = []
    for srv in servers:
        url = srv.get("url") or ""
        if not url:
            continue

        if not gated:
            # Nothing is gated for this agent: one plain toolset, no confirmation.
            toolsets.append(MCPToolset(connection_params=conn(url)))
            continue

        if "*" in gated:
            # The whole server is gated, so there is no ungated half to build.
            toolsets.append(
                MCPToolset(connection_params=conn(url), require_confirmation=True)
            )
            continue

        # Everything the platform did NOT name — runs straight through.
        toolsets.append(
            MCPToolset(
                connection_params=conn(url),
                tool_filter=lambda tool, ctx=None: tool.name not in gated,
            )
        )
        # The tools the platform DID name — ADK pauses and kagent asks a human.
        toolsets.append(
            MCPToolset(
                connection_params=conn(url),
                tool_filter=lambda tool, ctx=None: tool.name in gated,
                require_confirmation=True,
            )
        )
    return toolsets


mcp_tools = build_mcp_tools()
root_agent = Agent(
    model=create_model(),
    name="__NAME___agent",
    description="SRE assistant: triage and remediate unhealthy workloads via the sre-tools MCP server.",
    instruction=build_instruction(INSTRUCTION),
    tools=mcp_tools if mcp_tools else [],
)

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: srenative
  namespace: kagent
spec:
  type: Declarative
  declarative:
    runtime: python              # which ADK implementation to run
    modelConfig: default-model-config
    systemMessage: |
      You are an SRE assistant. Look before you touch...
    tools:
      - type: McpServer
        mcpServer:
          apiGroup: kagent.dev
          kind: RemoteMCPServer
          name: sre-tools
          toolNames:
            - list_pods
            - get_pod_logs
            - describe_deployment
            - restart_deployment
            - scale_deployment
          # no requireApproval — the developer did not add one

name: agent risk register
on:
  push:
    paths: [platform/risk/**]        # owned by the platform team, not by agent repos

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Publish both halves of the decision. Reviewed like any other change: a pull
      # request, an owner, an audit trail.
      #
      # create --dry-run | apply rather than patch, because `gated` is a multi-line
      # value and a JSON merge patch cannot carry a literal newline.
      - name: Publish the risk register
        run: |
          kubectl -n kyverno create configmap agent-risk-register \
            --from-literal=red="$(paste -sd, platform/risk/red-agents.txt)" \
            --from-literal=default=green \
            --from-file=gated=platform/risk/gated.yaml \
            --dry-run=client -o yaml | kubectl apply -f -

# THE CONTROL — one policy that puts a human in front of an agent whose developer
# never agreed to it and cannot remove it.
#
# It reads one ConfigMap, the risk register, and for any agent named there it turns
# on kagent's own approval flow. The approval then appears in the kagent UI. No
# gateway, no approval service, nothing extra to run.
#
# NOTHING IN THIS FILE NAMES A TOOL. The register answers both questions:
#
#   red      which agents need a human. `*` means every agent, which turns this
#            into a purely tool-driven control: any agent that uses a gated tool
#            needs approval, and no agent is ever named.
#   gated    which tools need approval, per MCP server
#
# So adding the hundredth tool, or a whole new MCP server, is a ConfigMap edit and
# the policy never changes. That matters because the policy is cluster-wide
# admission control: editing it is a change-managed event, editing a register entry
# is not.
#
# Both kinds of kagent agent are covered, because the field to set differs:
#
#   spec.type: Declarative   kagent knows the tool list, so add requireApproval to
#                            it. kagent pauses the tool itself.
#
#   spec.type: BYO           kagent sees only a pod, so instead set the env var
#                            KAGENT_REQUIRE_APPROVAL. The agent's ADK toolsets read
#                            it and pass ADK's require_confirmation, which pauses
#                            the tool and emits the SAME confirmation kagent renders.
#
# Either way the result is identical from the outside: the tool does not run, and a
# human approves or rejects in the kagent UI (or over its API).
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: verdict-hitl-enrolment
  annotations:
    policies.kyverno.io/title: Require human approval for agents named red
    policies.kyverno.io/category: Platform
    policies.kyverno.io/description: >-
      Agents named on the red list of the agent-risk-register ConfigMap have human
      approval turned on, for the tools that same register marks as needing it,
      surfaced in the kagent UI. Applied at admission, so it is in force before the
      agent serves a request. No tool name appears in the policy.
spec:
  background: false            # admission-time only; this policy mutates
  rules:

    # ── Declarative agents: add requireApproval to the tool stanza ─────────────
    #
    # The register's tool list is intersected with the agent's own toolNames, which
    # is not cosmetic. A CEL rule on the Agent CRD requires every requireApproval
    # entry to appear in toolNames, so naming a tool this agent does not have would
    # produce a resource the API server REJECTS — the deploy fails instead of the
    # agent being gated. Intersecting lets one register cover a whole fleet of
    # agents with different tool sets, each getting only the entries that apply.
    - name: approval-declarative
      match:
        any:
          - resources:
              kinds: [kagent.dev/v1alpha2/Agent]
              namespaces: [kagent]
      context:
        - name: register
          configMap: { name: agent-risk-register, namespace: kyverno }
      preconditions:
        all:
          - key: "{{ request.object.spec.type || '' }}"
            operator: Equals
            value: Declarative
        any:
          - key: "{{ contains(split(register.data.red || '', ','), request.object.metadata.name) }}"
            operator: Equals
            value: true
          # red: "*" — every agent is in scope, so the register gates on TOOLS alone.
          # Without this clause a `*` would match no agent name, the agent would be
          # labelled green, and nothing would be gated: a silent fail-open for the
          # most natural thing to write.
          - key: "{{ contains(split(register.data.red || '', ','), '*') }}"
            operator: Equals
            value: true
          - key: "{{ register.data.default || 'green' }}"
            operator: Equals
            value: red
      mutate:
        foreach:
          - list: "request.object.spec.declarative.tools"
            context:
              # What the register says about THIS stanza's MCP server.
              # `{{ element.mcpServer.name }}` is substituted before the JMESPath
              # runs, so this stays an ordinary filter rather than a dynamic map
              # key — dynamic ConfigMap keys need nested interpolation and are
              # fragile across Kyverno releases.
              - name: want
                variable:
                  jmesPath: "parse_yaml(register.data.gated || '[]')[?server=='{{ element.mcpServer.name }}'].tools | [0] || `[]`"
              # `tools: ['*']` gates every tool the server exposes; otherwise take
              # the intersection. The backtick literal is what makes the match
              # exact — contains() against a raw CSV string would let an entry
              # named `scale` match `scale_deployment`.
              - name: gated
                variable:
                  jmesPath: "contains(`{{ want }}`, '*') && element.mcpServer.toolNames || element.mcpServer.toolNames[?contains(`{{ want }}`, @)]"
            preconditions:
              all:
                - key: "{{ element.type || '' }}"
                  operator: Equals
                  value: McpServer
                # Servers the register says nothing about are left exactly as the
                # developer wrote them.
                - key: "{{ length(gated) }}"
                  operator: GreaterThan
                  value: 0
                # Idempotence: re-applies arrive as admission UPDATEs.
                - key: "{{ element.mcpServer.requireApproval || `[]` | length(@) }}"
                  operator: Equals
                  value: 0
            patchesJson6902: |-
              - op: add
                path: "/spec/declarative/tools/{{ elementIndex }}/mcpServer/requireApproval"
                value: {{ gated }}

    # ── BYO agents: set the env var its ADK toolsets read ──────────────────────
    #
    # kagent cannot see a BYO agent's tools, but the agent's own MCP wiring is right
    # there in its env: MCP_SERVERS_CONFIG lists the servers it connects to, by
    # name. That is the same key the register is written against, so this is the
    # same lookup as the declarative rule — the policy reads which servers this
    # agent actually uses and gates only those.
    #
    # patchesJson6902, never patchStrategicMerge: the Agent CRD has no merge key for
    # spec.byo.deployment.env, so a strategic merge replaces the WHOLE list and
    # silently drops the registry-injected MCP wiring and the model key.
    - name: approval-byo
      match:
        any:
          - resources:
              kinds: [kagent.dev/v1alpha2/Agent]
              namespaces: [kagent]
      context:
        - name: register
          configMap: { name: agent-risk-register, namespace: kyverno }
        # The MCP servers this agent connects to, by name.
        - name: mine
          variable:
            jmesPath: "parse_json(request.object.spec.byo.deployment.env[?name=='MCP_SERVERS_CONFIG'].value | [0] || '[]')[].name"
        # Every gated tool across those servers, flattened, because one agent can
        # connect to more than one.
        - name: gated
          variable:
            jmesPath: "parse_yaml(register.data.gated || '[]')[?contains(`{{ mine }}`, server)].tools[]"
      preconditions:
        all:
          - key: "{{ request.object.spec.type || '' }}"
            operator: Equals
            value: BYO
          # Nothing in the register covers this agent's servers — leave it alone.
          - key: "{{ length(gated) }}"
            operator: GreaterThan
            value: 0
          # Idempotence: without this, every reconcile appends a duplicate.
          - key: "{{ request.object.spec.byo.deployment.env[?name=='KAGENT_REQUIRE_APPROVAL'] | length(@) }}"
            operator: Equals
            value: 0
        any:
          - key: "{{ contains(split(register.data.red || '', ','), request.object.metadata.name) }}"
            operator: Equals
            value: true
          # red: "*" — every agent is in scope, so the register gates on TOOLS alone.
          # Without this clause a `*` would match no agent name, the agent would be
          # labelled green, and nothing would be gated: a silent fail-open for the
          # most natural thing to write.
          - key: "{{ contains(split(register.data.red || '', ','), '*') }}"
            operator: Equals
            value: true
          - key: "{{ register.data.default || 'green' }}"
            operator: Equals
            value: red
      mutate:
        patchesJson6902: |-
          - op: add
            path: "/spec/byo/deployment/env/-"
            value:
              name: KAGENT_REQUIRE_APPROVAL
              value: "{{ join(',', gated) }}"


    # ── Taking an agent OFF the register must actually un-gate it ──────────────
    #
    # Without these two rules the control is one-way. Clearing `red`, or dropping a
    # server from `gated`, leaves the previous mutation in place: the agent keeps its
    # requireApproval or its env var, keeps pausing, and is labelled green while doing
    # it. Safe, in that it fails closed, but it makes the register a lie.
    #
    # These fire only on the green path, so they can never race the add rules.
    - name: ungate-declarative
      match:
        any:
          - resources:
              kinds: [kagent.dev/v1alpha2/Agent]
              namespaces: [kagent]
      context:
        - name: register
          configMap: { name: agent-risk-register, namespace: kyverno }
      preconditions:
        all:
          - key: "{{ request.object.spec.type || '' }}"
            operator: Equals
            value: Declarative
          - key: "{{ contains(split(register.data.red || '', ','), request.object.metadata.name) }}"
            operator: Equals
            value: false
          - key: "{{ contains(split(register.data.red || '', ','), '*') }}"
            operator: Equals
            value: false
          - key: "{{ register.data.default || 'green' }}"
            operator: NotEquals
            value: red
      mutate:
        foreach:
          - list: "request.object.spec.declarative.tools"
            preconditions:
              all:
                - key: "{{ element.mcpServer.requireApproval || `[]` | length(@) }}"
                  operator: GreaterThan
                  value: 0
            patchesJson6902: |-
              - op: remove
                path: "/spec/declarative/tools/{{ elementIndex }}/mcpServer/requireApproval"

    - name: ungate-byo
      match:
        any:
          - resources:
              kinds: [kagent.dev/v1alpha2/Agent]
              namespaces: [kagent]
      context:
        - name: register
          configMap: { name: agent-risk-register, namespace: kyverno }
      preconditions:
        all:
          - key: "{{ request.object.spec.type || '' }}"
            operator: Equals
            value: BYO
          - key: "{{ contains(split(register.data.red || '', ','), request.object.metadata.name) }}"
            operator: Equals
            value: false
          - key: "{{ contains(split(register.data.red || '', ','), '*') }}"
            operator: Equals
            value: false
          - key: "{{ register.data.default || 'green' }}"
            operator: NotEquals
            value: red
      mutate:
        foreach:
          # Only ever one matching entry, so removing by elementIndex cannot shift
          # the index of another entry this same foreach still has to visit.
          - list: "request.object.spec.byo.deployment.env"
            preconditions:
              all:
                - key: "{{ element.name || '' }}"
                  operator: Equals
                  value: KAGENT_REQUIRE_APPROVAL
            patchesJson6902: |-
              - op: remove
                path: "/spec/byo/deployment/env/{{ elementIndex }}"


    # ── ...and so must dropping the SERVER, while the agent stays red ───────────
    #
    # The two rules above only fire on the green path, so they miss the other way an
    # agent stops needing approval: it is still red, but its MCP server is no longer
    # in `gated`, or its tools were narrowed. Kyverno's preconditions are a flat
    # all/any and cannot express "green OR nothing-gated" in one rule, so that case
    # is its own rule rather than a nested condition.
    #
    # Scope is not checked here on purpose: if the register gates nothing on this
    # agent's servers then it should carry no gating, red or green.
    - name: ungate-declarative-unlisted
      match:
        any:
          - resources:
              kinds: [kagent.dev/v1alpha2/Agent]
              namespaces: [kagent]
      context:
        - name: register
          configMap: { name: agent-risk-register, namespace: kyverno }
      preconditions:
        all:
          - key: "{{ request.object.spec.type || '' }}"
            operator: Equals
            value: Declarative
      mutate:
        foreach:
          - list: "request.object.spec.declarative.tools"
            context:
              - name: want
                variable:
                  jmesPath: "parse_yaml(register.data.gated || '[]')[?server=='{{ element.mcpServer.name }}'].tools | [0] || `[]`"
              - name: gated
                variable:
                  jmesPath: "contains(`{{ want }}`, '*') && element.mcpServer.toolNames || element.mcpServer.toolNames[?contains(`{{ want }}`, @)]"
            preconditions:
              all:
                - key: "{{ element.mcpServer.requireApproval || `[]` | length(@) }}"
                  operator: GreaterThan
                  value: 0
                - key: "{{ length(gated) }}"
                  operator: Equals
                  value: 0
            patchesJson6902: |-
              - op: remove
                path: "/spec/declarative/tools/{{ elementIndex }}/mcpServer/requireApproval"

    - name: ungate-byo-unlisted
      match:
        any:
          - resources:
              kinds: [kagent.dev/v1alpha2/Agent]
              namespaces: [kagent]
      context:
        - name: register
          configMap: { name: agent-risk-register, namespace: kyverno }
        - name: mine
          variable:
            jmesPath: "parse_json(request.object.spec.byo.deployment.env[?name=='MCP_SERVERS_CONFIG'].value | [0] || '[]')[].name"
        - name: gated
          variable:
            jmesPath: "parse_yaml(register.data.gated || '[]')[?contains(`{{ mine }}`, server)].tools[]"
      preconditions:
        all:
          - key: "{{ request.object.spec.type || '' }}"
            operator: Equals
            value: BYO
          - key: "{{ length(gated) }}"
            operator: Equals
            value: 0
          - key: "{{ request.object.spec.byo.deployment.env[?name=='KAGENT_REQUIRE_APPROVAL'] | length(@) }}"
            operator: GreaterThan
            value: 0
      mutate:
        foreach:
          - list: "request.object.spec.byo.deployment.env"
            preconditions:
              all:
                - key: "{{ element.name || '' }}"
                  operator: Equals
                  value: KAGENT_REQUIRE_APPROVAL
            patchesJson6902: |-
              - op: remove
                path: "/spec/byo/deployment/env/{{ elementIndex }}"

    # ── Record the decision, for humans reading the cluster ────────────────────
    # The label is a record, not the mechanism. Do not key enforcement off it.
    - name: label-red
      match:
        any:
          - resources:
              kinds: [kagent.dev/v1alpha2/Agent]
              namespaces: [kagent]
      context:
        - name: register
          configMap: { name: agent-risk-register, namespace: kyverno }
      preconditions:
        any:
          - key: "{{ contains(split(register.data.red || '', ','), request.object.metadata.name) }}"
            operator: Equals
            value: true
          # red: "*" — every agent is in scope, so the register gates on TOOLS alone.
          # Without this clause a `*` would match no agent name, the agent would be
          # labelled green, and nothing would be gated: a silent fail-open for the
          # most natural thing to write.
          - key: "{{ contains(split(register.data.red || '', ','), '*') }}"
            operator: Equals
            value: true
          - key: "{{ register.data.default || 'green' }}"
            operator: Equals
            value: red
      mutate:
        patchStrategicMerge:
          metadata:
            labels:
              risk.platform.solo.io/verdict: red

    - name: label-green
      match:
        any:
          - resources:
              kinds: [kagent.dev/v1alpha2/Agent]
              namespaces: [kagent]
      context:
        - name: register
          configMap: { name: agent-risk-register, namespace: kyverno }
      preconditions:
        all:
          - key: "{{ contains(split(register.data.red || '', ','), request.object.metadata.name) }}"
            operator: Equals
            value: false
          - key: "{{ contains(split(register.data.red || '', ','), '*') }}"
            operator: Equals
            value: false
          - key: "{{ register.data.default || 'green' }}"
            operator: NotEquals
            value: red
      mutate:
        patchStrategicMerge:
          metadata:
            labels:
              risk.platform.solo.io/verdict: green

def _gated_tools():
    """Tool names the PLATFORM decided need approval."""
    raw = os.environ.get("KAGENT_REQUIRE_APPROVAL", "")
    return {t.strip() for t in raw.split(",") if t.strip()}


def build_mcp_tools():
    gated = _gated_tools()
    servers = json.loads(os.environ.get("MCP_SERVERS_CONFIG", "") or "[]")

    toolsets = []
    for srv in servers:
        if not gated:
            toolsets.append(MCPToolset(connection_params=conn(srv["url"])))
            continue

        # everything the platform did NOT name — runs straight through
        toolsets.append(MCPToolset(
            connection_params=conn(srv["url"]),
            tool_filter=lambda tool, ctx=None: tool.name not in gated,
        ))
        # the tools it DID name — ADK pauses and kagent asks a human
        toolsets.append(MCPToolset(
            connection_params=conn(srv["url"]),
            tool_filter=lambda tool, ctx=None: tool.name in gated,
            require_confirmation=True,
        ))
    return toolsets