feat: initial harness spec v1.0.0 + reference template
Adds the normative contract every platform agent must conform to, plus a
working reference template under template/ that ticks every box out of
the box.
Spec is derived from the production agents shipped in
cjot-backstage-az/agents/ on branch sandbox/jonathan:
- agent-registry, agent-factory, decomposer, discovery-agent,
golden-path, modernization-factory, modernization-factory-v2,
policy-transformer, scaffold-agent, support-intake-agent, the-watcher
Contents:
- SPEC.md normative contract (13 sections + conformance checklist)
- CHANGELOG.md spec versioning (1.0.0)
- docs/
registration.md self-registration with the agent-gateway
observability.md OTel logs/metrics/traces wiring
manifest.md /.well-known/agent.json schema + AgentSkill
serialisation (pydantic vs protobuf)
kubernetes.md k8s deployment shape, mandatory cross-refs,
per-namespace agents, resource sizing
deployment.md .image-version, ACR build, deploy scripts, rollback
deviations.md tracked debts against the spec
- template/
.env.local.example, .gitignore, .image-version (0.1.0),
Dockerfile (python:3.12-slim, non-root UID 1001, HEALTHCHECK),
requirements.txt (harness floor + optional LLM stack),
app/agent.py (Starlette entry, lifespan + self-registration,
defensive _skill_dict for pydantic vs protobuf),
app/logging_setup.py (canonical OTel log bridge — copy verbatim),
app/metrics.py (meter + example counter/histogram),
app/skills.py (AGENT_CONFIG + AgentSkill list),
k8s/configmap.yaml + deployment.yaml (Deployment + Service,
OTel annotations + 6-var env block,
agents-sa + agents-kv-spc bindings),
scripts/deploy.sh (auto-bump + az acr build + apply + rollout),
scripts/full-deploy.sh (preflight + deploy + post-deploy smoke),
scripts/deploy-local.sh (docker/podman + .env.local)
This commit is contained in:
38
template/scripts/deploy-local.sh
Executable file
38
template/scripts/deploy-local.sh
Executable file
@@ -0,0 +1,38 @@
|
||||
#!/bin/bash
|
||||
# deploy-local.sh — Build the image locally and run it against .env.local.
|
||||
#
|
||||
# Useful for iterating on prompts/skills without touching the cluster.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
|
||||
AGENT_DIR=$(cd "${SCRIPT_DIR}/.." && pwd)
|
||||
|
||||
APP_NAME="<agent-name>"
|
||||
PORT=8000
|
||||
ENV_FILE="${AGENT_DIR}/.env.local"
|
||||
|
||||
if [ ! -f "${ENV_FILE}" ]; then
|
||||
echo "ERROR: ${ENV_FILE} not found. Copy .env.local.example first." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Pick docker or podman
|
||||
if command -v docker >/dev/null; then
|
||||
RUNTIME=docker
|
||||
elif command -v podman >/dev/null; then
|
||||
RUNTIME=podman
|
||||
else
|
||||
echo "ERROR: neither docker nor podman found on PATH" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Building ${APP_NAME}:local with ${RUNTIME}..."
|
||||
"${RUNTIME}" build -t "${APP_NAME}:local" "${AGENT_DIR}"
|
||||
|
||||
echo "Running ${APP_NAME}:local on http://localhost:${PORT} ..."
|
||||
exec "${RUNTIME}" run --rm -it \
|
||||
--name "${APP_NAME}" \
|
||||
-p "${PORT}:${PORT}" \
|
||||
--env-file "${ENV_FILE}" \
|
||||
"${APP_NAME}:local"
|
||||
75
template/scripts/deploy.sh
Executable file
75
template/scripts/deploy.sh
Executable file
@@ -0,0 +1,75 @@
|
||||
#!/bin/bash
|
||||
# deploy.sh — Build <agent-name> image in ACR and deploy to AKS.
|
||||
#
|
||||
# Usage:
|
||||
# ./scripts/deploy.sh # auto-bump patch version
|
||||
# ./scripts/deploy.sh --tag 1.2.3 # use an explicit tag (does not bump)
|
||||
#
|
||||
# Conforms to platform agent-harness-spec §10.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
|
||||
AGENT_DIR=$(cd "${SCRIPT_DIR}/.." && pwd)
|
||||
|
||||
ACR_NAME="bstagecjotdevacr"
|
||||
APP_NAME="<agent-name>"
|
||||
NAMESPACE="agents"
|
||||
VERSION_FILE="${AGENT_DIR}/.image-version"
|
||||
TAG=""
|
||||
|
||||
# ─── Parse args ─────────────────────────────────────────────────────────
|
||||
while [[ "$#" -gt 0 ]]; do
|
||||
case $1 in
|
||||
--tag)
|
||||
TAG="$2"
|
||||
shift
|
||||
;;
|
||||
-h|--help)
|
||||
sed -n '2,8p' "$0"
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
echo "unknown arg: $1" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
# ─── Auto-bump patch version if --tag not given ─────────────────────────
|
||||
if [ -z "$TAG" ]; then
|
||||
if [ -f "$VERSION_FILE" ]; then
|
||||
CURRENT_VERSION=$(cat "$VERSION_FILE")
|
||||
else
|
||||
CURRENT_VERSION="0.1.0"
|
||||
fi
|
||||
IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
|
||||
PATCH=$((PATCH + 1))
|
||||
TAG="${MAJOR}.${MINOR}.${PATCH}"
|
||||
echo "$TAG" > "$VERSION_FILE"
|
||||
fi
|
||||
|
||||
IMAGE="${ACR_NAME}.azurecr.io/${APP_NAME}:${TAG}"
|
||||
IMAGE_LATEST="${ACR_NAME}.azurecr.io/${APP_NAME}:latest"
|
||||
|
||||
echo "======================================================================"
|
||||
echo " ${APP_NAME} — build & deploy"
|
||||
echo " Image: ${IMAGE}"
|
||||
echo "======================================================================"
|
||||
|
||||
# ─── Build & push in ACR ────────────────────────────────────────────────
|
||||
az acr build --registry "$ACR_NAME" \
|
||||
--image "${APP_NAME}:${TAG}" \
|
||||
--image "${APP_NAME}:latest" \
|
||||
"${AGENT_DIR}"
|
||||
|
||||
# ─── Apply manifests ────────────────────────────────────────────────────
|
||||
kubectl apply -f "${AGENT_DIR}/k8s/configmap.yaml"
|
||||
kubectl apply -f "${AGENT_DIR}/k8s/deployment.yaml"
|
||||
|
||||
# ─── Wait for rollout ───────────────────────────────────────────────────
|
||||
kubectl -n "${NAMESPACE}" rollout status "deployment/${APP_NAME}" --timeout=180s
|
||||
|
||||
echo ""
|
||||
echo "Deployed ${IMAGE} to ${NAMESPACE}/${APP_NAME}"
|
||||
74
template/scripts/full-deploy.sh
Executable file
74
template/scripts/full-deploy.sh
Executable file
@@ -0,0 +1,74 @@
|
||||
#!/bin/bash
|
||||
# full-deploy.sh — Preflight checks + build + deploy + post-deploy smoke.
|
||||
#
|
||||
# Run this for first-time deploys or after an outage to validate cluster state.
|
||||
# For routine redeploys, use scripts/deploy.sh.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
|
||||
AGENT_DIR=$(cd "${SCRIPT_DIR}/.." && pwd)
|
||||
|
||||
APP_NAME="<agent-name>"
|
||||
NAMESPACE="agents"
|
||||
SA_NAME="agents-sa"
|
||||
SPC_NAME="agents-kv-spc"
|
||||
PORT=8000
|
||||
|
||||
fail() { echo "preflight FAIL: $1" >&2; exit 1; }
|
||||
ok() { echo "preflight OK : $1"; }
|
||||
|
||||
# ─── Preflight ──────────────────────────────────────────────────────────
|
||||
echo "─── Preflight ──────────────────────────────────────────"
|
||||
|
||||
command -v kubectl >/dev/null || fail "kubectl not on PATH"
|
||||
ok "kubectl on PATH"
|
||||
|
||||
command -v az >/dev/null || fail "az CLI not on PATH"
|
||||
ok "az CLI on PATH"
|
||||
|
||||
kubectl cluster-info >/dev/null 2>&1 || fail "kubectl can't reach a cluster"
|
||||
ok "cluster reachable: $(kubectl config current-context)"
|
||||
|
||||
kubectl get namespace "${NAMESPACE}" >/dev/null 2>&1 \
|
||||
|| fail "namespace ${NAMESPACE} missing"
|
||||
ok "namespace ${NAMESPACE} exists"
|
||||
|
||||
kubectl -n "${NAMESPACE}" get serviceaccount "${SA_NAME}" >/dev/null 2>&1 \
|
||||
|| fail "ServiceAccount ${NAMESPACE}/${SA_NAME} missing"
|
||||
ok "ServiceAccount ${SA_NAME} exists"
|
||||
|
||||
kubectl -n "${NAMESPACE}" get secretproviderclass "${SPC_NAME}" >/dev/null 2>&1 \
|
||||
|| fail "SecretProviderClass ${NAMESPACE}/${SPC_NAME} missing"
|
||||
ok "SecretProviderClass ${SPC_NAME} exists"
|
||||
|
||||
echo ""
|
||||
|
||||
# ─── Build & deploy ─────────────────────────────────────────────────────
|
||||
echo "─── Build & deploy ─────────────────────────────────────"
|
||||
"${SCRIPT_DIR}/deploy.sh" "$@"
|
||||
|
||||
echo ""
|
||||
|
||||
# ─── Post-deploy smoke ──────────────────────────────────────────────────
|
||||
echo "─── Post-deploy smoke ──────────────────────────────────"
|
||||
|
||||
POD=$(kubectl -n "${NAMESPACE}" get pod -l "app=${APP_NAME}" \
|
||||
-o jsonpath='{.items[0].metadata.name}')
|
||||
|
||||
echo "Probing /health on ${POD}..."
|
||||
kubectl -n "${NAMESPACE}" exec "${POD}" -c "${APP_NAME}" -- \
|
||||
curl -fs "http://localhost:${PORT}/health" \
|
||||
| jq -e '.status == "healthy"' >/dev/null \
|
||||
&& ok "/health returns healthy" \
|
||||
|| fail "/health did not return healthy"
|
||||
|
||||
echo "Probing /.well-known/agent.json on ${POD}..."
|
||||
kubectl -n "${NAMESPACE}" exec "${POD}" -c "${APP_NAME}" -- \
|
||||
curl -fs "http://localhost:${PORT}/.well-known/agent.json" \
|
||||
| jq -e '.name and .version and (.skills | type == "array")' >/dev/null \
|
||||
&& ok "/.well-known/agent.json valid" \
|
||||
|| fail "/.well-known/agent.json invalid"
|
||||
|
||||
echo ""
|
||||
echo "Done. ${APP_NAME} is up and conforming to the harness spec."
|
||||
Reference in New Issue
Block a user