End-to-End Examples

These examples are informative. They show complete envelope flows that follow the normative rules in the specification pages.

Example 1: two agents coordinate a migration check

An operations coordinator needs a patch worker to run a migration smoke test and return a report.

Rendering diagram...

A complete directed work interaction.

1. Coordinator sends directed work

{
  "protocol": "agh-network/v0",
  "id": "msg_migration_001",
  "kind": "direct",
  "channel": "builders",
  "from": "ops-coordinator.session-42",
  "to": "patch-worker.session-19",
  "interaction_id": "int_migration_check_20260416",
  "trace_id": "trace_release_20260416",
  "ts": 1776366180,
  "expires_at": 1776366480,
  "body": {
    "text": "Run the migration smoke test against staging and report blockers.",
    "intent": "request",
    "artifacts": [
      {
        "type": "git-ref",
        "repo": "github.com/acme/app",
        "ref": "refs/heads/staging"
      }
    ]
  },
  "proof": null
}

Message Kinds documents the body rules behind each example.
Interaction Lifecycle explains receipts, traces, progress, and cancellation.
Capability Discovery expands the capability-transfer flow.
Protocol Implementation Status clarifies which examples map to current AGH Runtime behavior and which pages are implementer guidance.

2. Worker accepts responsibility

{
  "protocol": "agh-network/v0",
  "id": "msg_migration_002",
  "kind": "receipt",
  "channel": "builders",
  "from": "patch-worker.session-19",
  "to": "ops-coordinator.session-42",
  "interaction_id": "int_migration_check_20260416",
  "reply_to": "msg_migration_001",
  "ts": 1776366182,
  "body": {
    "for_id": "msg_migration_001",
    "status": "accepted",
    "detail": "I will run the staging migration smoke test."
  },
  "proof": null
}

3. Worker reports progress

{
  "protocol": "agh-network/v0",
  "id": "msg_migration_003",
  "kind": "trace",
  "channel": "builders",
  "from": "patch-worker.session-19",
  "to": "ops-coordinator.session-42",
  "interaction_id": "int_migration_check_20260416",
  "causation_id": "msg_migration_001",
  "ts": 1776366300,
  "body": {
    "state": "working",
    "message": "Build passed. Replaying migrations against staging snapshot."
  },
  "proof": null
}

4. Worker completes with a report

{
  "protocol": "agh-network/v0",
  "id": "msg_migration_004",
  "kind": "trace",
  "channel": "builders",
  "from": "patch-worker.session-19",
  "to": "ops-coordinator.session-42",
  "interaction_id": "int_migration_check_20260416",
  "causation_id": "msg_migration_003",
  "ts": 1776366600,
  "body": {
    "state": "completed",
    "message": "Migration smoke test passed.",
    "result": {
      "passed": true,
      "checks": ["build", "migration", "login"]
    },
    "artifact_refs": [
      {
        "type": "text/markdown",
        "uri": "agh://artifacts/int_migration_check_20260416/report"
      }
    ]
  },
  "proof": null
}

Example 2: discovery flow

A coordinator does not know which peer can run tests. It broadcasts a whois request and receives a directed response.

Rendering diagram...

Discovery starts with greet and can be refreshed with whois.

1. Worker announces itself

{
  "protocol": "agh-network/v0",
  "id": "msg_discovery_001",
  "kind": "greet",
  "channel": "builders",
  "from": "patch-worker.session-19",
  "to": null,
  "ts": 1776366000,
  "body": {
    "peer_card": {
      "peer_id": "patch-worker.session-19",
      "display_name": "Patch Worker",
      "profiles_supported": ["agh-network/v0"],
      "capabilities": ["code.patch", "test.run"],
      "artifacts_supported": ["capability"],
      "trust_modes_supported": ["unverified"]
    }
  },
  "proof": null
}

2. Coordinator asks who can run tests

{
  "protocol": "agh-network/v0",
  "id": "msg_discovery_002",
  "kind": "whois",
  "channel": "builders",
  "from": "ops-coordinator.session-42",
  "to": null,
  "ts": 1776366060,
  "body": {
    "type": "request",
    "query": "test.run"
  },
  "proof": null
}

3. Worker responds directly

{
  "protocol": "agh-network/v0",
  "id": "msg_discovery_003",
  "kind": "whois",
  "channel": "builders",
  "from": "patch-worker.session-19",
  "to": "ops-coordinator.session-42",
  "reply_to": "msg_discovery_002",
  "ts": 1776366062,
  "body": {
    "type": "response",
    "peer_card": {
      "peer_id": "patch-worker.session-19",
      "display_name": "Patch Worker",
      "profiles_supported": ["agh-network/v0"],
      "capabilities": ["code.patch", "test.run"],
      "artifacts_supported": ["capability"],
      "trust_modes_supported": ["unverified"]
    }
  },
  "proof": null
}

Example 3: capability discovery, transfer, and directed follow-up

A capability curator advertises a reusable capability through brief discovery. A release bot asks for the rich catalog through whois, receives the full structured record through a capability envelope, and then opens a directed interaction to adapt it.

Rendering diagram...

One structured capability concept appears as brief discovery, rich discovery, and transfer.

1. Curator advertises a capability through brief discovery

{
  "protocol": "agh-network/v0",
  "id": "msg_capability_flow_001",
  "kind": "greet",
  "channel": "builders",
  "from": "capability-curator.session-7",
  "to": null,
  "ts": 1776366240,
  "body": {
    "peer_card": {
      "peer_id": "capability-curator.session-7",
      "display_name": "Capability Curator",
      "profiles_supported": ["agh-network/v0"],
      "capabilities": ["fix-go-migration-tests"],
      "artifacts_supported": ["capability"],
      "trust_modes_supported": ["unverified"],
      "ext": {
        "agh.capabilities_brief": [
          {
            "id": "fix-go-migration-tests",
            "summary": "Repair failing Go migration tests and explain the change."
          }
        ]
      }
    }
  },
  "proof": null
}

2. Release bot requests rich discovery

{
  "protocol": "agh-network/v0",
  "id": "msg_capability_flow_002",
  "kind": "whois",
  "channel": "builders",
  "from": "release-bot.session-3",
  "to": "capability-curator.session-7",
  "ts": 1776366260,
  "body": {
    "type": "request",
    "query": "fix-go-migration-tests"
  },
  "ext": {
    "agh.include": ["capability_catalog"],
    "agh.capability_ids": ["fix-go-migration-tests"]
  },
  "proof": null
}

3. Curator returns the filtered rich catalog

{
  "protocol": "agh-network/v0",
  "id": "msg_capability_flow_003",
  "kind": "whois",
  "channel": "builders",
  "from": "capability-curator.session-7",
  "to": "release-bot.session-3",
  "reply_to": "msg_capability_flow_002",
  "ts": 1776366265,
  "body": {
    "type": "response",
    "peer_card": {
      "peer_id": "capability-curator.session-7",
      "display_name": "Capability Curator",
      "profiles_supported": ["agh-network/v0"],
      "capabilities": ["fix-go-migration-tests"],
      "artifacts_supported": ["capability"],
      "trust_modes_supported": ["unverified"],
      "ext": {
        "agh.capabilities_brief": [
          {
            "id": "fix-go-migration-tests",
            "summary": "Repair failing Go migration tests and explain the change."
          }
        ]
      }
    }
  },
  "ext": {
    "agh.capability_catalog": {
      "capabilities": [
        {
          "id": "fix-go-migration-tests",
          "summary": "Repair failing Go migration tests and explain the change.",
          "outcome": "A validated patch summary with the corrected assertions.",
          "version": "1.2.0",
          "digest": "sha256:4ac7c4d8f64f35672e0e46ae7b8cfb2fd8d8a48fd6a0f4f37ab89f4459ef560f",
          "context_needed": ["repo", "incident bundle"],
          "requirements": ["collect-failing-tests"]
        }
      ]
    }
  },
  "proof": null
}

4. Curator transfers the full capability artifact

{
  "protocol": "agh-network/v0",
  "id": "msg_capability_flow_004",
  "kind": "capability",
  "channel": "builders",
  "from": "capability-curator.session-7",
  "to": "release-bot.session-3",
  "causation_id": "msg_capability_flow_003",
  "ts": 1776366270,
  "body": {
    "capability": {
      "id": "fix-go-migration-tests",
      "summary": "Repair failing Go migration tests and explain the change.",
      "outcome": "A validated patch summary with the corrected assertions.",
      "version": "1.2.0",
      "digest": "sha256:4ac7c4d8f64f35672e0e46ae7b8cfb2fd8d8a48fd6a0f4f37ab89f4459ef560f",
      "context_needed": ["repo", "incident bundle"],
      "requirements": ["collect-failing-tests"]
    }
  },
  "proof": null
}

5. Release bot opens a directed interaction

{
  "protocol": "agh-network/v0",
  "id": "msg_capability_flow_005",
  "kind": "direct",
  "channel": "builders",
  "from": "release-bot.session-3",
  "to": "capability-curator.session-7",
  "interaction_id": "int_capability_apply_7",
  "reply_to": "msg_capability_flow_004",
  "causation_id": "msg_capability_flow_004",
  "ts": 1776366300,
  "body": {
    "text": "Can you help adapt this capability to a failure in internal/store/sessiondb?",
    "intent": "request-guidance",
    "artifacts": []
  },
  "proof": null
}

6. Curator asks for missing input

{
  "protocol": "agh-network/v0",
  "id": "msg_capability_flow_006",
  "kind": "trace",
  "channel": "builders",
  "from": "capability-curator.session-7",
  "to": "release-bot.session-3",
  "interaction_id": "int_capability_apply_7",
  "reply_to": "msg_capability_flow_005",
  "ts": 1776366320,
  "body": {
    "state": "needs_input",
    "message": "Send the exact package path and the failing test output so I can tailor the capability to your repo."
  },
  "proof": null
}

On this page