#!/usr/bin/env bash # # Run this agent locally with the SAME configuration it will get in production. # # In Kubernetes, deployment.yaml does `envFrom: configMapRef`, which injects # every key in kubernetes/configmap.yaml into the container as an environment # variable. Nothing reads that file locally, so a plain `podman run` drifts from # the deployed configuration the moment either one changes — and the drift is # silent, which is the worst kind. # # This script closes that gap: it reads kubernetes/configmap.yaml and passes # each key through as -e, exactly as Kubernetes would. Change a setting in the # ConfigMap and it takes effect both here and on deploy — one source of truth. # # Secrets are NOT in the ConfigMap (in production they arrive from Secrets; see # kubernetes/secretnames.yaml), so they are passed separately below, read from # your shell or from .env. # # Usage: # ./run-local.sh # build if needed, run on port 8080 # PORT_HOST=8081 ./run-local.sh # different host port # DEV_RELOAD=true ./run-local.sh # restart the server on source edits # RUNTIME_REGISTRY=localhost ./run-local.sh # a runtime built from source # # Works with podman or docker; set CONTAINER_CLI to choose. set -euo pipefail cd "$(dirname "$0")" # The directory name is the agent name — no template variable needed, and it # stays correct if the project is renamed. AGENT="$(basename "$(pwd)")" IMAGE="localhost/${AGENT}:local" PORT_HOST="${PORT_HOST:-8080}" CONFIGMAP="kubernetes/configmap.yaml" CLI="${CONTAINER_CLI:-podman}" # --- configuration, straight from the ConfigMap -------------------------- # Mirrors `envFrom: configMapRef`. Keys whose values are placeholders for the # CI/CD pipeline are skipped, since they are meaningless locally. # # Read into an array with a while-loop rather than `mapfile`, which needs # bash 4 — macOS still ships bash 3.2, so this script would not run there. ENV_ARGS=() while IFS= read -r line; do ENV_ARGS+=("$line") done < <( python3 - "$CONFIGMAP" <<'PY' import sys, yaml data = yaml.safe_load(open(sys.argv[1])) or {} for key, value in (data.get("data") or {}).items(): text = str(value) if "/dev/null; then MOUNTS+=(-v "${EXECUTION_STORAGE_VOLUME}:/data/executions:rw") SECRET_ARGS_STORAGE=(-e "EXECUTION_STORAGE_ROOT=/data/executions") else echo "note: volume '$EXECUTION_STORAGE_VOLUME' not found; the agent will not be" echo " able to read large payloads passed by reference. Start the dev kit" echo " first, or set EXECUTION_STORAGE_VOLUME to the right name." SECRET_ARGS_STORAGE=() fi # The image's own entry point serves the agent, exactly as in production. CMD=() # Hot reload is local-only. DEV_RELOAD is read case-insensitively, and 1/yes # count too, so DEV_RELOAD=TRUE is not quietly ignored. # # tr rather than ${VAR,,} because macOS still ships bash 3.2. DEV_RELOAD_NORMALISED="$(printf '%s' "${DEV_RELOAD:-}" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')" case "$DEV_RELOAD_NORMALISED" in 1|true|yes) DEV_RELOAD_ON=1 ;; *) DEV_RELOAD_ON=0 ;; esac if [[ "$DEV_RELOAD_ON" == "1" ]]; then # WATCHFILES_FORCE_POLLING is required because the file-change events a # bind mount would normally deliver do not cross the podman-machine VM # boundary on macOS or Windows — without it the watcher simply never fires. # # The runtime's own server, under uvicorn's reloader: it restarts on any # change under /agent -- code, prompt.md, agent.yaml, schemas, skills -- # which needs watchfiles, installed here for this container only. SECRET_ARGS+=(-e "WATCHFILES_FORCE_POLLING=true") CMD=(sh -c "pip install --quiet --user watchfiles && exec python -m uvicorn \ kyndryl_agent_runtime.a2a.server:create_a2a_server --factory --host 0.0.0.0 --port 8080 \ --reload --reload-dir /agent --reload-include '*.md' --reload-include '*.json' --reload-include '*.yaml'") fi # Optional: run against a checkout of the runtime SDK instead of the runtime # in the image. Only useful if you are changing the SDK itself. if [[ -n "${SDK_SRC:-}" ]]; then SDK_PACKAGE="${SDK_SRC%/}/src/kyndryl_agent_runtime" if [[ ! -f "${SDK_PACKAGE}/__init__.py" ]]; then echo "error: SDK_SRC must point to the kyndryl-agent-runtime checkout root" >&2 exit 1 fi MOUNTS+=(-v "${SDK_PACKAGE}:/sdk-override/kyndryl_agent_runtime:ro") PYTHONPATH_VALUE="/sdk-override:${PYTHONPATH_VALUE}" echo "note: using SDK source from ${SDK_PACKAGE}" fi SECRET_ARGS+=(-e "PYTHONPATH=${PYTHONPATH_VALUE}") # Seeded with the flags that are always present, because `set -u` on bash 3.2 — # still what macOS ships — treats expanding an empty array as an unbound # variable and aborts. Appending to a non-empty array sidesteps that. RUN_ARGS=(-d --name "$AGENT" -p "${PORT_HOST}:8080") # Optional: join a shared network so the platform can reach this agent. # # --network-alias is not optional here. `--name` alone registers only the # container ID with podman's DNS, so other containers cannot resolve the agent # by name and the platform's registration URL never connects. The alias is what # makes http://:8080 work from the API and the Temporal worker. if [[ -n "${CONTAINER_NETWORK:-}" ]]; then RUN_ARGS+=(--network "${CONTAINER_NETWORK}" --network-alias "$AGENT") fi # The runtime image the agent is built FROM. The Dockerfile names the one the # agent pipeline builds on; locally the same image (name and version) comes # from RUNTIME_REGISTRY: the dev kit's GHCR by default, where an FDE pulls it, # or localhost for a runtime built from source. RUNTIME_IMAGE, in .env or the # shell, names one outright. PIPELINE_RUNTIME="$(sed -n 's/^ARG RUNTIME_IMAGE=//p' Dockerfile | head -1)" RUNTIME_IMAGE="${RUNTIME_IMAGE:-${RUNTIME_REGISTRY:-ghcr.io/kyndryl-agentic-ai}/${PIPELINE_RUNTIME##*/}}" # Rebuild only when what the image is made of changed -- the Dockerfile, the # runtime image, requirements.txt -- and not on every run: the agent's code is # mounted, so edits to it need no rebuild. (It used to build only when the # image was missing, so a new runtime version in the Dockerfile was ignored # until the image was removed by hand.) BUILD_KEY="$( { cat Dockerfile requirements.txt 2>/dev/null; echo "$RUNTIME_IMAGE"; } | cksum | cut -d' ' -f1)" CURRENT_KEY="$("$CLI" image inspect "$IMAGE" 2>/dev/null | python3 -c ' import json, sys try: image = json.load(sys.stdin)[0] except Exception: sys.exit(0) labels = image.get("Labels") or (image.get("Config") or {}).get("Labels") or {} print(labels.get("agent.build-key", ""))' || true)" if [[ "$CURRENT_KEY" != "$BUILD_KEY" ]]; then echo "building ${IMAGE} on ${RUNTIME_IMAGE}" "$CLI" build --build-arg RUNTIME_IMAGE="$RUNTIME_IMAGE" --label agent.build-key="$BUILD_KEY" \ -t "$IMAGE" -f Dockerfile . fi "$CLI" rm -f "$AGENT" >/dev/null 2>&1 || true "$CLI" run "${RUN_ARGS[@]}" \ "${ENV_ARGS[@]}" \ ${DOTENV_ARGS[@]+"${DOTENV_ARGS[@]}"} \ ${SECRET_ARGS[@]+"${SECRET_ARGS[@]}"} \ ${SECRET_ARGS_STORAGE[@]+"${SECRET_ARGS_STORAGE[@]}"} \ "${MOUNTS[@]}" "$IMAGE" ${CMD[@]+"${CMD[@]}"} >/dev/null echo "${AGENT} on http://localhost:${PORT_HOST} (config from ${CONFIGMAP})" echo " card: curl -s localhost:${PORT_HOST}/.well-known/agent-card.json" echo " chat: python tests/test_chatbot.py --url http://localhost:${PORT_HOST}" echo " logs: ${CLI} logs -f ${AGENT}"