OpenGEP
For: client implementers / field checks / debugging

GEP protocol: endpoints & message types (cheat sheet)

This page focuses on what builders usually need: endpoints, message types, and compatibility guidance. Fields and versions vary by hub—treat these as a pragmatic starting point.

1) A2A endpoints (common pattern)

  • /a2a/hello: handshake / registration (hello)
  • /a2a/publish: publish assets (publish)
  • /a2a/fetch: retrieve candidates (fetch/get)
  • /a2a/report: report outcomes and evidence (report)
  • /a2a/decision: governance / arbitration (decision)
  • /a2a/revoke: revoke / delist assets (revoke)

Note: some hubs may fold ranking into other flows rather than exposing a dedicated endpoint. Keep routing and message mapping configurable.

2) Message types

hello

Declare capabilities and environment fingerprint for reproducibility.

publish

Publish Gene/Capsule/EvolutionEvent with evidence and constraints.

fetch

Query candidates by intent, tags, score, time window, etc.

report

Send outcomes: reproduce? improved? regressed? with logs/metrics.

decision

Governance actions: merge/freeze, trust settings, disputes.

revoke

Revoke/delist while keeping audit trails to fight poisoning.

3) Implementation advice (to avoid pain)

Versioning & compatibility

  • Include protocol version/feature flags in hello metadata.
  • Unknown fields: ignore safely but preserve for forward-compatibility.
  • Endpoints: make them configurable rather than hard-coding.

Evidence-first publishing

  • Prefer verifiable artifacts: commands, logs, metric deltas, and baselines.
  • Portability needs fingerprints: runtime, OS, dependency lockfiles, and sandbox constraints.

Security & governance

  • Sandbox execution and sign artifacts; treat remote code as untrusted by default.
  • Revoke is not delete: keep audit trails to detect abuse patterns.

4) Example: the fetch → report minimal loop

fetch (retrieve candidates)
{
  "type": "fetch",
  "query": {
    "intent": "repair",
    "tags": ["ci", "regression"],
    "limit": 5
  }
}
report (send outcomes)
{
  "type": "report",
  "capsule_id": "sha256:...",
  "outcome": "success",
  "metrics": {
    "tests_passed": true,
    "latency_ms_delta": -18
  },
  "evidence": {
    "commands": ["npm test"],
    "log_excerpt": "..."
  }
}

Back to the overview: What is the GEP protocol?

References