Jonathan Boniface
e6f10ba8c9
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)
118 lines
3.3 KiB
YAML
118 lines
3.3 KiB
YAML
apiVersion: apps/v1
|
|
kind: Deployment
|
|
metadata:
|
|
name: <agent-name>
|
|
namespace: agents
|
|
labels:
|
|
app: <agent-name>
|
|
component: agent
|
|
spec:
|
|
replicas: 1
|
|
selector:
|
|
matchLabels:
|
|
app: <agent-name>
|
|
template:
|
|
metadata:
|
|
labels:
|
|
app: <agent-name>
|
|
azure.workload.identity/use: "true"
|
|
annotations:
|
|
# ─── OTel SDK injection ─────────────────────────────────────────
|
|
instrumentation.opentelemetry.io/inject-python: "monitoring/otel-instrumentation"
|
|
instrumentation.opentelemetry.io/container-names: "<agent-name>"
|
|
spec:
|
|
serviceAccountName: agents-sa
|
|
containers:
|
|
- name: <agent-name>
|
|
image: bstagecjotdevacr.azurecr.io/<agent-name>:latest
|
|
imagePullPolicy: Always
|
|
ports:
|
|
- name: http
|
|
containerPort: 8000
|
|
protocol: TCP
|
|
envFrom:
|
|
- configMapRef:
|
|
name: <agent-name>-config
|
|
env:
|
|
# ─── OTel (mandatory — keep these keys verbatim) ───────────
|
|
- name: OTEL_SERVICE_NAME
|
|
value: "<agent-name>"
|
|
- name: OTEL_RESOURCE_ATTRIBUTES
|
|
value: "service.namespace=agents,service.version=0.1.0,deployment.environment=prod,agent.type=<role>"
|
|
- name: OTEL_LOGS_EXPORTER
|
|
value: "otlp"
|
|
- name: OTEL_METRICS_EXPORTER
|
|
value: "otlp"
|
|
- name: OTEL_METRIC_EXPORT_INTERVAL
|
|
value: "15000"
|
|
- name: OTEL_SEMCONV_STABILITY_OPT_IN
|
|
value: "http"
|
|
|
|
# ─── Secrets from agents-kv-sync (sync'd from Key Vault) ───
|
|
- name: AZURE_OPENAI_ENDPOINT
|
|
valueFrom:
|
|
secretKeyRef:
|
|
name: agents-kv-sync
|
|
key: azure-openai-endpoint
|
|
- name: AZURE_OPENAI_API_KEY
|
|
valueFrom:
|
|
secretKeyRef:
|
|
name: agents-kv-sync
|
|
key: azure-openai-api-key
|
|
|
|
resources:
|
|
requests:
|
|
memory: "512Mi"
|
|
cpu: "250m"
|
|
limits:
|
|
memory: "1Gi"
|
|
cpu: "500m"
|
|
|
|
livenessProbe:
|
|
httpGet:
|
|
path: /health
|
|
port: http
|
|
initialDelaySeconds: 20
|
|
periodSeconds: 15
|
|
timeoutSeconds: 5
|
|
failureThreshold: 3
|
|
|
|
readinessProbe:
|
|
httpGet:
|
|
path: /health
|
|
port: http
|
|
initialDelaySeconds: 10
|
|
periodSeconds: 10
|
|
timeoutSeconds: 3
|
|
failureThreshold: 3
|
|
|
|
volumeMounts:
|
|
- name: secrets-store
|
|
mountPath: "/mnt/secrets-store"
|
|
readOnly: true
|
|
|
|
volumes:
|
|
- name: secrets-store
|
|
csi:
|
|
driver: secrets-store.csi.k8s.io
|
|
readOnly: true
|
|
volumeAttributes:
|
|
secretProviderClass: agents-kv-spc
|
|
---
|
|
apiVersion: v1
|
|
kind: Service
|
|
metadata:
|
|
name: <agent-name>
|
|
namespace: agents
|
|
labels:
|
|
app: <agent-name>
|
|
spec:
|
|
selector:
|
|
app: <agent-name>
|
|
ports:
|
|
- name: http
|
|
port: 80
|
|
targetPort: 8000
|
|
protocol: TCP
|
|
type: ClusterIP
|