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)
Reference template — <your-agent-name>
Spec version: 1.0.0 — see
../SPEC.md
A working, copy-and-fill skeleton for a new Python/Starlette agent that conforms to the harness spec.
Quickstart
# 1. Copy the template
cp -r template/ ../my-new-agent/
cd ../my-new-agent
# 2. Rename placeholders
git grep -l '<agent-name>\|<agent_name>\|<AgentName>\|<role>' | xargs sed -i \
-e 's/<agent-name>/my-new-agent/g' \
-e 's/<agent_name>/my_new_agent/g' \
-e 's/<AgentName>/MyNewAgent/g' \
-e 's/<role>/my-new-agent/g'
# 3. Pin the initial version
echo "0.1.0" > .image-version
# 4. Add your domain code
# - Replace the `/echo` route in app/agent.py with your endpoints
# - Add your skills to app/skills.py
# - Add custom metrics to app/metrics.py
# 5. Configure local dev
cp .env.local.example .env.local
# edit .env.local with your secrets
# 6. Run locally
./scripts/deploy-local.sh
# 7. Build & deploy to the cluster
./scripts/full-deploy.sh
What's in the box
template/
├── .env.local.example # all env vars the agent reads, with safe defaults
├── .gitignore
├── .image-version # 0.1.0
├── Dockerfile # python:3.12-slim, non-root, HEALTHCHECK
├── README.md # (this file)
├── requirements.txt # harness floor + LLM stack
├── app/
│ ├── __init__.py
│ ├── agent.py # Starlette entry point, all required routes,
│ │ # lifespan + self-registration, _skill_dict helper
│ ├── logging_setup.py # OTel log bridge (copy verbatim — do not edit)
│ ├── metrics.py # Meter + example counter/histogram
│ └── skills.py # AGENT_SKILLS list + AGENT_CONFIG dict
├── k8s/
│ ├── configmap.yaml # REGISTRY_URL, AGENT_SELF_URL, LOG_LEVEL, PORT
│ └── deployment.yaml # Deployment + Service, OTel annotations + env block
└── scripts/
├── deploy.sh # az acr build + kubectl apply + rollout
├── deploy-local.sh # docker/podman + .env.local
└── full-deploy.sh # preflight + deploy.sh + post-deploy smoke
Editing rules
| Touch freely | Touch carefully | Do not edit |
|---|---|---|
app/skills.py |
app/agent.py (keep lifespan + registration + manifest intact) |
app/logging_setup.py |
app/metrics.py (rename instruments to your domain) |
k8s/deployment.yaml env vars (only change OTEL_* values, not keys) |
The _skill_dict helper in app/agent.py |
requirements.txt (add your domain deps) |
Dockerfile (only change EXPOSE and the uvicorn port) |
scripts/deploy.sh flow |
k8s/configmap.yaml data section |
k8s/deployment.yaml probes (only initialDelaySeconds for slow startup) |
OTel annotations on the pod template |
Conformance
Before opening a PR for your new agent, walk the conformance checklist in SPEC.md. The reference template ticks every box out of the box; you should only need to verify your domain-specific additions don't regress anything.