Shape of the conversation
The agent initiates every exchange over HTTPS. Requests are wrapped in an agent envelope and responses in a control-plane envelope; both carry the protocol version, a unique message id used for de-duplication, identity, a timestamp and a correlation id.
| Endpoint | Purpose |
|---|---|
POST /v1/agent/enroll | First registration with a one-time token |
POST /v1/agent/token | Exchange a signed assertion for a short-lived access token |
POST /v1/agent/heartbeat | Liveness and capability report; learns if it has been revoked |
POST /v1/agent/leases | Long-poll for a command lease |
POST /v1/agent/leases/{id}/ack and /renew | Accept or reject a lease; keep it alive while working |
POST /v1/agent/reports | Job events, discovery findings, manifests, certification results, evidence references |
Commands are declarative
A command names what to do — discover metadata, validate a source, build or refresh a dataset, cancel, revoke — and references policies by version and checksum. The agent re-verifies the checksum and that the policy is approved and not revoked, and rejects stale, duplicate or cross-tenant commands.
What a report may contain
Only classified fields: control metadata, aggregate metrics, evidence metadata and secret references. Values, rows, samples and credentials are prohibited by the contract itself and by the agent's egress guard, and the control plane validates again on arrival without logging rejected content.
The authoritative reference is docs/contracts/PROTOCOL.md in the repository.