Files

Jonathan Boniface e6f10ba8c9 feat: initial harness spec v1.0.0 + reference template

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)

2026-06-09 15:54:18 +01:00

1.7 KiB

Raw Permalink Blame History

Changelog — agent-harness-spec

All notable changes to the spec are recorded here. The spec follows semver.

[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.

1.7 KiB Raw Permalink Blame History Unescape Escape

Changelog — agent-harness-spec

[1.0.0] — 2026-06-09

1.7 KiB

Raw Permalink Blame History