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)
agent-harness-spec
Standard definition and reference template for Python/Starlette agents running on the platform.
This repository defines:
- The normative contract every platform agent must conform to — see SPEC.md.
- A working reference template under
template/you copy when starting a new agent. - Deep-dive docs under
docs/covering registration, observability, the agent manifest, Kubernetes shape, and deployment.
The spec is derived from the production agents shipped in cjot-backstage-az/agents/ (branch sandbox/jonathan) — agent-registry, golden-path, policy-transformer, modernization-factory-v2, scaffold-agent, decomposer, discovery-agent, the-watcher, support-intake-agent, etc. If an agent in that repository disagrees with this spec, the spec wins on net-new work; existing deviations are tracked under docs/deviations.md and brought into line at the next minor version bump.
When to use this repo
- Starting a new agent:
cp -r template/ ../my-new-agent/and followtemplate/README.md. - Auditing an existing agent: walk the conformance checklist in
SPEC.md. - Changing the contract: open a PR against
SPEC.md+ bump the spec version in CHANGELOG.md.
Spec version
The current spec version is 1.0.0 (see CHANGELOG.md).
Quick links
| Topic | File |
|---|---|
| Normative contract | SPEC.md |
| Self-registration with the gateway | docs/registration.md |
| OpenTelemetry wiring (logs / metrics / traces) | docs/observability.md |
/.well-known/agent.json manifest schema |
docs/manifest.md |
| Kubernetes deployment shape | docs/kubernetes.md |
Build & deploy flow (ACR, scripts, .image-version) |
docs/deployment.md |
| Known deviations from the spec | docs/deviations.md |
| Reference template walkthrough | template/README.md |