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)
35 lines
1.7 KiB
Markdown
35 lines
1.7 KiB
Markdown
# Changelog — agent-harness-spec
|
||
|
||
All notable changes to the spec are recorded here. The spec follows [semver](https://semver.org/).
|
||
|
||
## [1.0.0] — 2026-06-09
|
||
|
||
Initial draft derived from the production agents shipped in `cjot-backstage-az/agents/` on branch `sandbox/jonathan`:
|
||
|
||
- `agent-registry` (FastAPI, registry/gateway)
|
||
- `agent-factory`
|
||
- `decomposer`
|
||
- `discovery-agent`
|
||
- `golden-path`
|
||
- `modernization-factory` (v1)
|
||
- `modernization-factory-v2`
|
||
- `policy-transformer`
|
||
- `scaffold-agent`
|
||
- `support-intake-agent` (FastAPI, intake)
|
||
- `the-watcher`
|
||
|
||
Codifies:
|
||
|
||
- Mandatory `app.agent:app` Starlette entry point
|
||
- `GET /health` and `GET /.well-known/agent.json` contract
|
||
- Self-registration with the agent-gateway via `POST /agents/register-url` (3×5s retry budget)
|
||
- OTel operator-driven SDK injection + the six standard env vars (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_LOGS_EXPORTER`, `OTEL_METRICS_EXPORTER`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_SEMCONV_STABILITY_OPT_IN`)
|
||
- Canonical `app/logging_setup.py` bridge (root logger → `LoggerProvider`)
|
||
- `app/metrics.py` shape (`metrics.get_meter(name, version)` + module-scope instruments, `agent.<type>.*` naming)
|
||
- LangChain instrumentation via `LangChainInstrumentor().instrument()`
|
||
- Container shape (`python:3.12-slim`, non-root UID 1001, HEALTHCHECK)
|
||
- Kubernetes shape (namespace `agents`, ServiceAccount `agents-sa`, `agents-kv-spc` SPC at `/mnt/secrets-store`, named `http` port, OTel inject annotations)
|
||
- `.image-version` file + `scripts/deploy.sh` / `full-deploy.sh` / `deploy-local.sh` cadence
|
||
|
||
Defensive serialisation for `a2a.types.AgentSkill` (pydantic vs protobuf) is mandated in §6 to avoid the `model_dump()` regression observed in `policy-transformer` 1.0.2 → 1.0.3.
|