platform/agent-harness-spec
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: initial harness spec v1.0.0 + reference template

Browse Source 
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:
Jonathan Boniface
2026-06-09 15:54:18 +01:00
parent c87dd3fa55
commit e6f10ba8c9
25 changed files with 1933 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
README.md
View File

@@ -1,3 +1,34 @@
# agent-harness-spec
Standard definition and specification for the agent harness used across the platform.
Standard definition and reference template for **Python/Starlette agents** running on the platform.
This repository defines:
1. The **normative contract** every platform agent must conform to — see [SPEC.md](SPEC.md).
2. A working **reference template** under [`template/`](template/) you copy when starting a new agent.
3. **Deep-dive docs** under [`docs/`](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`](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 follow [`template/README.md`](template/README.md).
- **Auditing an existing agent**: walk the [conformance checklist](SPEC.md#conformance-checklist) in `SPEC.md`.
- **Changing the contract**: open a PR against `SPEC.md` + bump the spec version in [CHANGELOG.md](CHANGELOG.md).
## Spec version
The current spec version is **`1.0.0`** (see [CHANGELOG.md](CHANGELOG.md)).
## Quick links
| Topic | File |
|---|---|
| Normative contract | [SPEC.md](SPEC.md) |
| Self-registration with the gateway | [docs/registration.md](docs/registration.md) |
| OpenTelemetry wiring (logs / metrics / traces) | [docs/observability.md](docs/observability.md) |
| `/.well-known/agent.json` manifest schema | [docs/manifest.md](docs/manifest.md) |
| Kubernetes deployment shape | [docs/kubernetes.md](docs/kubernetes.md) |
| Build & deploy flow (ACR, scripts, `.image-version`) | [docs/deployment.md](docs/deployment.md) |
| Known deviations from the spec | [docs/deviations.md](docs/deviations.md) |
| Reference template walkthrough | [template/README.md](template/README.md) |