ACGP-1003: Message Formats & Wire Protocol

Status: Draft
Last Updated: 2026-01-08
Spec ID: ACGP-1003
Normative Keywords: MUST, SHOULD, MAY (per RFC 2119)

Abstract

This specification defines the message formats, security envelope, and transport protocol for the Agentic Cognitive Governance Protocol (ACGP). It details the normative JSON structures for the primary message types: TRACE, EVAL, INTERVENTION, SYNC, and HITL. It also specifies the mandatory use of a secure transport (HTTPS) and a common message envelope that ensures message integrity, authenticity, and non-repudiation through checksums and digital signatures. This document includes version negotiation, retry policies, batch processing specifications, and optional governance contracts extension (ACGP-1010).

This is the authoritative source for ACGP wire protocol versioning. All protocol_version fields in messages reference this specification.

Table of Contents

  1. Introduction
  2. Transport & Serialization
  3. Version Negotiation
  4. Message Envelope
  5. Message Payloads
  6. Batch Processing
  7. Retry and Timeout Behavior
  8. Error Handling
  9. Security Considerations
  10. Formal Message Schemas
  11. Conformance Requirements
  12. References

1. Introduction

For ACGP to be an interoperable standard, all participating components (Operating Agents, Governance Stewards, ReflectionDB) MUST adhere to a common communication protocol. This document provides the definitive specification for that protocol.

1.1 Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2. Transport & Serialization

  • Serialization: All message payloads MUST be serialized as JSON.
  • Transport: The primary transport protocol MUST be HTTPS. HTTP/2 is RECOMMENDED for improved performance.
  • Authentication: Communication channels MUST be authenticated. Implementations SHOULD use either OAuth 2.0 Bearer Tokens or mutual TLS (mTLS) for service-to-service authentication.
  • Connection Management: Implementations SHOULD use persistent connections and connection pooling to minimize overhead.

3. Version Negotiation

3.1 Version Negotiation Process

Before any message exchange, implementations MUST negotiate the protocol version to ensure compatibility.

def negotiate_protocol_version(client_versions: list, server_versions: list) -> str:
    """
    Negotiate the highest common protocol version.

    Args:
        client_versions: List of versions supported by client (e.g., ["1.0.0", "1.0.2"])
        server_versions: List of versions supported by server

    Returns:
        Selected version string

    Raises:
        IncompatibleVersionError: If no common version exists
    """
    common_versions = set(client_versions) & set(server_versions)

    if not common_versions:
        raise IncompatibleVersionError(
            f"No common versions. Client: {client_versions}, Server: {server_versions}"
        )

    # Use semantic versioning comparison
    selected = max(common_versions, key=lambda v: tuple(map(int, v.split('.'))))

    return selected

3.2 Version Negotiation Message

{
  "type": "VERSION_NEGOTIATION",
  "client_versions": ["1.0.0", "1.1.0"],
  "capabilities": {
    "batch_processing": true,
    "streaming": false,
    "compression": ["gzip"],
    "governance_contracts": true
  }
}

Server Response:

{
  "type": "VERSION_SELECTED",
  "selected_version": "1.1.0",
  "server_capabilities": {
    "batch_processing": true,
    "max_batch_size": 100,
    "streaming": false,
    "compression": ["gzip"],
    "governance_contracts": true
  }
}

3.3 Version Compatibility Rules

  • Major version difference: Limited compatibility, use compatibility mode
  • Minor version difference: Full backward compatibility required
  • Patch version difference: Full compatibility assumed

4. Message Envelope

All ACGP messages MUST be encapsulated within a common JSON envelope to provide metadata, routing information, and security assurances.

This is the canonical envelope definition for ACGP. Section 10 provides complete message schemas using this envelope.

4.1 Envelope Structure

{
  "protocol": "acgp",
  "protocol_version": "1.0.0",
  "message_type": "TRACE | EVAL | INTERVENTION | SYNC | HITL",
  "message_id": "uuid-v7-string",
  "timestamp": "ISO8601-UTC-string",
  "sender_id": "unique-identifier-string",
  "receiver_id": "unique-identifier-string",
  "payload": {
    "...": "..."
  },
  "security": {
    "signature": "jws-compact-serialization-string",
    "checksum_alg": "sha256",
    "checksum": "hex-encoded-checksum-of-payload"
  }
}

4.2 Envelope Fields

protocol (string, REQUIRED): Protocol identifier. MUST be exactly "acgp".

protocol_version (string, REQUIRED): The version of the ACGP protocol, following SemVer (e.g., "1.1.0").

message_type (enum, REQUIRED): An enumerated string defining the type of payload. MUST be one of: "TRACE", "EVAL", "INTERVENTION", "SYNC", "HITL".

message_id (string, REQUIRED): A unique UUIDv7 identifier for this specific message. UUIDv7 is RECOMMENDED for time-ordered idempotency.

timestamp (string, REQUIRED): An RFC 3339 formatted timestamp in UTC indicating when the message was created.

sender_id (string, REQUIRED): The unique identifier of the sending component.

receiver_id (string, REQUIRED): The unique identifier of the intended recipient component.

payload (object, REQUIRED): The JSON object containing the message-specific data.

security (object, REQUIRED): An object containing security-related metadata.

  • signature (string, REQUIRED for ACL-3+): A JWS compact serialization signature using ES256 (ECDSA with P-256 and SHA-256) of the payload, providing non-repudiation.
  • checksum_alg (string, REQUIRED): The algorithm used for the checksum (MUST be "sha256").
  • checksum (string, REQUIRED): A hex-encoded SHA-256 checksum of the canonicalized JSON payload to ensure integrity.

5. Message Payloads

5.1 TRACE Payload

Sent by an Operating Agent to a Governance Steward to report its cognitive process for a single step. This aligns with the Agent Telemetry Standard (ATS).

{
  "trace_id": "uuid-v4-string",
  "session_id": "uuid-v4-string",
  "step": 12,
  "inputs": { 
    "user_prompt": "Summarize Q3 earnings for ACME.", 
    "context": "..." 
  },
  "tool_calls": [
    { 
      "name": "search", 
      "args": { "query": "ACME Q3 2025 earnings" }
    }
  ],
  "outputs": { 
    "text": "ACME's Q3 earnings showed a 10% YoY growth." 
  },
  "source_refs": ["reg:sec:10K:2025"],
  "meta": { 
    "model": "gpt-5-pro", 
    "latency_ms": 450, 
    "agent_id": "uuid",
    "agent_acl_tier": "ACL-2"
  }
}

5.2 EVAL Payload

The detailed evaluation result of a TRACE message, generated by the Governance Steward and logged to ReflectionDB. A copy MAY be sent to the Operating Agent as evidence.

{
  "trace_id": "uuid-v4-string",
  "blueprint_id": "finance_qa@2.1",
  "ctq_vector": [
    {"name": "reasoning_quality", "score": 0.87, "weight": 0.25},
    {"name": "knowledge_grounding", "score": 0.88, "weight": 0.20},
    {"name": "ethical_alignment", "score": 0.90, "weight": 0.20},
    {"name": "tool_safety", "score": 0.92, "weight": 0.20},
    {"name": "context_awareness", "score": 0.89, "weight": 0.15}
  ],
  "ctq_final": 0.888,
  "risk_score": 0.112,
  "acl_thresholds": {
    "ok": 0.25,
    "nudge": 0.40,
    "escalate": 0.55,
    "block": 0.70
  },
  "tripwires_checked": [
    {"id": "secrets_leak", "triggered": false},
    {"id": "pii_exposure", "triggered": false}
  ],
  "explanations": "Risk score is within OK threshold for ACL-2.",
  "evidence_result": { 
    "certified_sources_found": ["reg:sec:10K:2025"], 
    "penalties": [] 
  },
  "cost": { 
    "estimate_usd": 0.0021, 
    "meter": "tokens_usd" 
  }
}

5.3 INTERVENTION Payload

The final decision and action sent from the Governance Steward back to the Operating Agent. The decision field MUST be one of the six standard intervention levels.

{
  "trace_id": "uuid-v4-string",
  "decision": "ok",
  "flagged": false,
  "risk_score": 0.1425,
  "ctq_score": 0.8575,
  "reasons": ["All metrics within acceptable range"],
  "actions": [
    { 
      "type": "log", 
      "message": "Standard logging applied" 
    }
  ],
  "evidence": {
    "ctq_final": 0.8575,
    "risk_score": 0.1425,
    "acl_thresholds": {
      "ok": 0.25,
      "nudge": 0.40
    },
    "tripwires_triggered": []
  },
  "trust_debt_update": {
    "previous": 0.2,
    "current": 0.2,
    "change": 0.0
  }
}

Valid decision values: ok, nudge, escalate, block, halt (plus orthogonal flag)

5.4 SYNC Payload

Used for out-of-band updates, such as pushing a new Reflection Blueprint version to a Steward.

{
  "sync_type": "blueprint_update",
  "resource_id": "finance_qa@2.2",
  "action": "update",
  "data": {
    "blueprint": { "...": "..." },
    "effective_at": "2025-01-20T00:00:00Z"
  },
  "checksum": "sha256-hash-of-data"
}

5.5 HITL Payload

Used to package and send an escalate intervention to a human review system, containing the original trace, evaluation, and context.

{
  "escalation_id": "uuid-v4-string",
  "trace_id": "uuid-v4-string",
  "priority": "high",
  "reason": "Risk score in escalate range",
  "context": {
    "agent_id": "uuid",
    "agent_acl_tier": "ACL-3",
    "session_id": "uuid",
    "original_trace": { "...": "..." },
    "evaluation": { "...": "..." }
  },
  "suggested_actions": [
    "approve",
    "modify_and_approve",
    "deny"
  ],
  "timeout_seconds": 300
}

5.6 Governance Contracts Extension (OPTIONAL)

Status: OPTIONAL - implements ACGP-1010

Implementations claiming ACGP-1010 support MAY extend message payloads with governance contract fields. All fields are OPTIONAL and backward compatible (old implementations ignore them).

5.6.1 EVAL_REQUEST with Governance Contract

Extension to TRACE message (EVAL_REQUEST) to include governance contract:

{
  "trace_id": "uuid-v4-string",
  "session_id": "uuid-v4-string",
  "step": 12,
  "inputs": { "...": "..." },
  "tool_calls": [ "...": "..." ],
  "outputs": { "...": "..." },
  "source_refs": ["reg:sec:10K:2025"],
  "meta": { 
    "model": "gpt-5-pro", 
    "latency_ms": 450, 
    "agent_id": "uuid",
    "agent_acl_tier": "ACL-2"
  },

  // OPTIONAL: Governance contract fields (ACGP-1010)
  "governance_contract": {
    "risk_level": "elevated_risk",
    "eval_tier": 1,
    "performance_budget": {
      "latency_budget_ms": 300,
      "fallback_behavior": "cached_decision",
      "tier_budgets": {
        "tier_0": 50,
        "tier_1": 250
      }
    }
  }
}

Governance Contract Fields (all OPTIONAL):

  • risk_level (string): Action risk classification
  • Values: "low_risk", "elevated_risk", "critical_risk"
  • Default: Steward's default (typically low_risk equivalent)

  • See: ACGP-1010 Section 2

  • eval_tier (integer, OPTIONAL): Requested evaluation tier (0-3)

  • Values: 0, 1, 2, 3
  • Default: 0 (must-pass checks only)

  • See: ACGP-1010 Section 3

  • performance_budget (object, REQUIRED if using contracts): Performance constraints

  • latency_budget_ms (integer, REQUIRED): Maximum milliseconds agent will wait
  • fallback_behavior (string, REQUIRED): Behavior when budget exceeded
  • tier_budgets (object, OPTIONAL): Per-tier latency sub-budgets
    • Keys: "tier_0", "tier_1", "tier_2"
    • Values: milliseconds (MUST sum <= latency_budget_ms)
    • Default: Proportional allocation if absent

5.6.2 EVAL_RESPONSE with Governance Status

Extension to EVAL response to include governance evaluation metadata:

{
  "trace_id": "uuid-v4-string",
  "blueprint_id": "finance_qa@2.1",
  "ctq_vector": [ "...": "..." ],
  "ctq_final": 0.888,
  "risk_score": 0.112,
  "acl_thresholds": { "...": "..." },
  "tripwires_checked": [ "...": "..." ],
  "explanations": "...",
  "evidence_result": { "...": "..." },
  "cost": { "...": "..." },

  // OPTIONAL: Governance status (ACGP-1010)
  "governance_status": {
    "status": "OK",
    "completed_tiers": ["tier_0", "tier_1"],
    "budget_consumed_ms": 245,
    "steward_state": "normal",
    "partial_results": {}
  }
}

Governance Status Fields (all OPTIONAL):

  • status (string, REQUIRED if governance_status present): Evaluation result
  • "OK": Evaluation completed within budget
  • "GOVERNANCE_TIMEOUT": Budget exceeded, agent should use fallback
  • "PARTIAL_EVAL": Some tiers completed, others incomplete

  • "UNAVAILABLE": Steward cannot evaluate at all

  • completed_tiers (array of strings): Which evaluation tiers completed

  • Values: ["tier_0"], ["tier_0", "tier_1"], ["tier_0", "tier_1", "tier_2"]

  • Empty array if no tiers completed

  • budget_consumed_ms (integer): Actual milliseconds spent on evaluation

  • Used for monitoring and optimization

  • May exceed latency_budget_ms when status is GOVERNANCE_TIMEOUT

  • steward_state (string): Current steward operational state

  • "normal": Operating normally
  • "degraded": Reduced capacity (some tiers unavailable)
  • "essential": Only Tier 0 available

  • "emergency": Emergency mode, minimal governance only

  • partial_results (object, OPTIONAL): Results from completed tiers when status is PARTIAL_EVAL

  • Contains intermediate decisions or evidence
  • Structure depends on implementation

5.6.3 SYNC Handshake with Capability Negotiation

Extension to SYNC messages for announcing governance contract capabilities:

Agent announces capabilities (SYNC_HELLO):

{
  "sync_type": "handshake",
  "agent_id": "agent-abc-123",
  "agent_acl_tier": "ACL-3",
  "protocol_version": "1.1.0",

  // OPTIONAL: Governance contract capabilities
  "capabilities": {
    "governance_contracts": {
      "supported": true,
      "risk_levels": ["low_risk", "elevated_risk", "critical_risk"],
      "fallback_behaviors": ["deny", "allow_and_log", "cached_decision"],
      "default_budget_ms": 300,
      "default_fallback": "cached_decision"
    }
  }
}

Steward responds with its capabilities (SYNC_HELLO_ACK):

{
  "sync_type": "handshake_ack",
  "steward_id": "steward-xyz-789",
  "protocol_version": "1.1.0",

  // OPTIONAL: Governance contract capabilities
  "capabilities": {
    "governance_contracts": {
      "supported": true,
      "evaluation_tiers": ["tier_0", "tier_1", "tier_2"],
      "tier_0_latency_p99_ms": 45,
      "tier_1_latency_p99_ms": 180,
      "tier_2_available": true,
      "tier_2_async_only": true,
      "max_budget_ms": 10000,
      "default_budget_ms": 500
    }
  }
}

Capability Negotiation:

  • If both support governance contracts, they MAY use contract fields in subsequent messages
  • If either does not support, governance contract fields MUST be ignored
  • Agents SHOULD adapt behavior based on steward capabilities (e.g., lower budgets if steward is slower)

Example: Steward does not support governance contracts:

{
  "sync_type": "handshake_ack",
  "steward_id": "legacy-steward-123",
  "protocol_version": "1.1.0",

  // No governance_contracts capability
  "capabilities": {
    "batch_processing": true
  }
}

Agent receives this and knows NOT to include governance_contract fields in subsequent TRACE messages.

6. Batch Processing

6.1 Batch TRACE Submission

For efficiency, implementations MAY support batch submission of traces:

{
  "batch_id": "uuid-v4-string",
  "traces": [
    { "trace_id": "uuid-1", "...": "..." },
    { "trace_id": "uuid-2", "...": "..." }
  ],
  "batch_size": 2,
  "processing_mode": "parallel"
}

6.2 Batch Processing Constraints

  • Maximum batch size: 100 traces per batch (configurable)
  • Processing mode: parallel (default) or sequential
  • Timeout: Individual trace timeout x batch size
  • Partial failure handling: Continue processing remaining traces

6.3 Batch Response

{
  "batch_id": "uuid-v4-string",
  "results": [
    {
      "trace_id": "uuid-1",
      "status": "success",
      "intervention": { "...": "..." }
    },
    {
      "trace_id": "uuid-2",
      "status": "error",
      "error": { "...": "..." }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  }
}

7. Retry and Timeout Behavior

7.1 Retry Policy

All implementations MUST implement the following retry policy for transient failures:

retry_policy:
  max_attempts: 3
  backoff: exponential
  backoff_multiplier: 2
  initial_delay_ms: 100
  max_delay_ms: 5000
  timeout_ms: 500
  jitter: true
  failure_action: escalate

7.2 Retry Logic Implementation

def send_with_retry(message, max_attempts=3):
    """Send message with exponential backoff retry."""
    attempt = 0
    delay = 100  # ms

    while attempt < max_attempts:
        try:
            response = send_message(message, timeout_ms=500)
            return response
        except TimeoutError:
            attempt += 1
            if attempt >= max_attempts:
                # Escalate on final failure
                return escalate_for_manual_review(message)

            # Exponential backoff with jitter
            jitter = random.uniform(0, delay * 0.1)
            time.sleep((delay + jitter) / 1000)
            delay = min(delay * 2, 5000)
        except PermanentError as e:
            # Don't retry permanent errors
            return handle_permanent_error(message, e)

7.3 Timeout Specifications

Message Type Default Timeout Max Timeout On Timeout
TRACE 500ms 1000ms Retry
EVAL 200ms 500ms Use cached policy
INTERVENTION 100ms 200ms Retry
SYNC 5000ms 10000ms Log and continue
HITL 300000ms (5min) User-defined Deny by default

7.4 Failure Actions

Failure Type Action
Network timeout Retry with backoff
Service unavailable Retry with backoff
Invalid message Reject immediately, no retry
Authentication failure Reject immediately, no retry
Final retry failure Escalate to human review

8. Error Handling

8.1 Error Response Format

When a request fails due to a protocol-level error (e.g., malformed JSON, invalid message type), the responding service SHOULD return a structured JSON error payload with an appropriate HTTP status code.

{
  "error": {
    "code": "InvalidTraceMessage",
    "message": "TRACE message is missing required 'outputs' field.",
    "details": {
      "trace_id": "uuid-of-failed-trace",
      "missing_fields": ["outputs"]
    },
    "timestamp": "2025-01-15T10:00:00Z",
    "request_id": "uuid-v4"
  }
}

8.2 Standard Error Codes

Error Code HTTP Status Description Retry
InvalidMessage 400 Malformed message structure No
InvalidVersion 400 Unsupported protocol version No
MissingField 400 Required field missing No
InvalidSignature 401 Signature verification failed No
Unauthorized 401 Authentication failed No
Forbidden 403 Insufficient permissions No
NotFound 404 Resource not found No
Timeout 408 Request timeout Yes
RateLimitExceeded 429 Too many requests Yes (with backoff)
InternalError 500 Server error Yes
ServiceUnavailable 503 Service temporarily unavailable Yes

8.3 Error Handling Best Practices

Implementations SHOULD:

  • Log all errors with full context
  • Preserve error details for debugging
  • Return user-friendly error messages
  • Implement tripwires for cascading failures
  • Provide metrics on error rates

9. Security Considerations

9.1 Transport Security

All communication MUST occur over TLS 1.3 or higher with the following requirements:

  • Perfect forward secrecy
  • Certificate validation
  • Strong cipher suites only
  • Mutual TLS (mTLS) RECOMMENDED for service-to-service

9.2 Message Integrity

The checksum in the security envelope MUST be validated by the recipient to protect against:

  • Transmission errors
  • Message tampering
  • Man-in-the-middle attacks
def validate_message_integrity(envelope):
    """Validate message checksum."""
    # Extract payload
    payload = envelope['payload']

    # Canonicalize JSON
    canonical = json.dumps(payload, sort_keys=True, separators=(',', ':'))

    # Calculate checksum
    calculated = hashlib.sha256(canonical.encode()).hexdigest()

    # Compare
    if calculated != envelope['security']['checksum']:
        raise IntegrityError("Checksum mismatch")

9.3 Non-Repudiation

For high-stakes actions (ACL-3+), the signature field MUST be used:

  • Operating Agent signs the TRACE payload
  • Governance Steward signs the INTERVENTION payload
  • Signatures use ES256 (ECDSA with P-256 and SHA-256)

This creates a cryptographically verifiable audit trail.

9.4 Data Redaction

Sensitive information (e.g., PII, secrets) SHOULD be redacted from TRACE payloads before transmission:

{
  "outputs": {
    "text": "User SSN: [REDACTED:SSN]",
    "redacted_fields": ["ssn"]
  }
}

10. Formal Message Schemas

10.1 Protocol Envelope Schema

All ACGP messages MUST be wrapped in the envelope structure defined in Section 4.1.

Summary of Required Envelope Fields:

Field Type Description
protocol string MUST be "acgp"
protocol_version string Semantic version (e.g., "1.0.0")
message_type enum One of: TRACE, EVAL, INTERVENTION, SYNC, HITL
message_id string UUIDv7 for time-ordered idempotency
timestamp string RFC 3339 timestamp in UTC
sender_id string Unique identifier of sender
receiver_id string Unique identifier of receiver
payload object Message-specific data (see sections below)
security object Checksum and signature (see Section 4.2)

See Section 4 for complete field specifications and security requirements.

10.2 TRACE Message Schema

Complete TRACE Message:

{
  "protocol": "acgp",
  "protocol_version": "1.0.0",
  "message_type": "TRACE",
  "message_id": "01924a8c-e7f3-7000-8000-000000000001",
  "timestamp": "2025-11-04T12:30:00.000Z",
  "sender_id": "agent-xyz-123",
  "receiver_id": "steward-abc-456",
  "payload": {
    "trace_id": "01924a8c-e7f3-7000-8000-000000000001",
    "agent_id": "agent-xyz-123",
    "session_id": "session-789",
    "acl_tier": "ACL-2",
    "inputs": {
      "user_message": "Issue refund for order #12345",
      "context": {}
    },
    "reasoning": "Customer reported defective product with photographic evidence. Order history shows reliable customer with no prior refund requests. Refund amount $250 is within agent authority.",
    "action": {
      "name": "issue_refund",
      "parameters": {
        "order_id": "12345",
        "amount": 250.00,
        "reason": "defective_product"
      }
    },
    "tools_used": ["payment_api", "order_database"],
    "confidence": 0.92
  },
  "security": {
    "checksum_alg": "sha256",
    "checksum": "a3f2b8c9d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
  }
}

TRACE Payload Required Fields:

  • trace_id (string, REQUIRED): Unique trace identifier
  • agent_id (string, REQUIRED): Agent identifier
  • acl_tier (string, REQUIRED): One of ACL-0 through ACL-5
  • reasoning (string, REQUIRED): Agent's reasoning process
  • action (object, REQUIRED): Planned action with name and parameters

TRACE Payload Optional Fields:

  • session_id (string): Session identifier for multi-turn interactions
  • inputs (object): Context and user input
  • tools_used (array): List of tools/APIs accessed
  • confidence (number): Agent's confidence score [0-1]

10.3 EVAL Message Schema

Complete EVAL Message:

{
  "protocol": "acgp",
  "protocol_version": "1.0.0",
  "message_type": "EVAL",
  "message_id": "01924a8c-e7f4-7000-8000-000000000002",
  "timestamp": "2025-11-04T12:30:00.150Z",
  "sender_id": "steward-abc-456",
  "receiver_id": "audit-db-001",
  "payload": {
    "trace_id": "01924a8c-e7f3-7000-8000-000000000001",
    "blueprint_id": "customer-service-v2",
    "ctq_metrics": {
      "reasoning_quality": {"score": 0.90, "weight": 0.25},
      "knowledge_grounding": {"score": 0.88, "weight": 0.20},
      "ethical_alignment": {"score": 0.95, "weight": 0.20},
      "tool_safety": {"score": 0.92, "weight": 0.20},
      "context_awareness": {"score": 0.89, "weight": 0.15}
    },
    "ctq_score": 0.908,
    "risk_score": 0.092,
    "tripwires_triggered": [],
    "trust_debt": 0.0,
    "evaluation_metadata": {
      "policy_engine_version": "1.2.3",
      "evaluation_duration_ms": 145,
      "model_used": "gpt-5-steward"
    }
  },
  "security": {
    "checksum_alg": "sha256",
    "checksum": "b4f3c9d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3"
  }
}

EVAL Payload Required Fields:

  • trace_id (string, REQUIRED): Matching trace identifier
  • ctq_metrics (object, REQUIRED): Individual metric scores with weights
  • ctq_score (number, REQUIRED): Weighted average CTQ score [0-1]
  • risk_score (number, REQUIRED): Computed as 1.0 - ctq_score
  • tripwires_triggered (array, REQUIRED): List of triggered tripwire IDs (empty if none)

10.4 INTERVENTION Message Schema

Complete INTERVENTION Message:

{
  "protocol": "acgp",
  "protocol_version": "1.0.0",
  "message_type": "INTERVENTION",
  "message_id": "01924a8c-e7f5-7000-8000-000000000003",
  "timestamp": "2025-11-04T12:30:00.200Z",
  "sender_id": "steward-abc-456",
  "receiver_id": "agent-xyz-123",
  "payload": {
    "trace_id": "01924a8c-e7f3-7000-8000-000000000001",
    "decision": "ok",
    "flags": {
      "flagged": false,
      "severity": null
    },
    "message": "Action approved within policy bounds. CTQ score 0.908 exceeds ACL-2 threshold.",
    "modifications": [],
    "trust_debt_delta": 0.0,
    "requires_human_review": false
  },
  "security": {
    "checksum_alg": "sha256",
    "checksum": "c5f4d0e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4"
  }
}

INTERVENTION Payload Required Fields:

  • trace_id (string, REQUIRED): Matching trace identifier
  • decision (enum, REQUIRED): One of: "ok", "nudge", "escalate", "block", "halt"
  • flags (object, REQUIRED): Flagging status with flagged (boolean) and severity (string or null)
  • message (string, REQUIRED): Human-readable explanation of the decision

INTERVENTION Payload Optional Fields:

  • modifications (array): Suggested changes to the action
  • trust_debt_delta (number): Change in trust debt from this evaluation
  • requires_human_review (boolean): Whether escalation to human is needed

10.5 Version Compatibility Matrix

Protocol Version Compatibility:

Client Version Server 1.0.x Server 1.1.x Server 2.0.x
1.0.x Full Compatible Incompatible
1.1.x Compatible Full Incompatible
2.0.x Incompatible Incompatible Full

Compatibility Rules:

  • Same MAJOR version: MUST accept any MINOR version
  • Different MAJOR version: MUST reject with error code 426 (Upgrade Required)
  • PATCH version differences: Always compatible

Version Mismatch Error Response:

{
  "error": {
    "code": 426,
    "type": "ProtocolVersionMismatch",
    "message": "Protocol version 2.0.0 not supported",
    "supported_versions": ["1.0.0", "1.0.1", "1.1.0"],
    "requested_version": "2.0.0"
  }
}

11. Conformance Requirements

A conformant ACGP implementation MUST:

11.1 Message Format Requirements

  • Serialize all messages as JSON
  • Transport them over HTTPS (TLS 1.3+)
  • Encapsulate all messages in the specified envelope structure
  • Generate and validate checksums for every message
  • Correctly generate and parse the payloads for all five message types

11.2 Version Management

  • Implement version negotiation before message exchange
  • Support at least the current major version
  • Reject connections with incompatible versions
  • Gracefully handle version mismatches

11.3 Reliability Requirements

  • Implement the standard retry policy with exponential backoff
  • Handle timeouts according to specifications
  • Support batch processing (RECOMMENDED)
  • Implement tripwires for cascading failures

11.4 Security Requirements

  • Use TLS 1.3 or higher for all communication
  • Validate all message checksums
  • Implement message signing for ACL-3+ agents
  • Redact sensitive data before transmission
  • Maintain audit logs of all message exchanges

11.5 Error Handling Requirements

  • Return structured error responses
  • Use standard HTTP status codes
  • Provide detailed error information for debugging
  • Log all errors with full context

12. References

Normative References

  • ACGP-1000: Core Protocol Specification
  • ACGP-1001: Terminology and Definitions
  • ACGP-1002: Architecture Specification
  • ACGP-1005: ARS-CTQ-ACL Integration Framework
  • ACGP-1007: Security Considerations
  • RFC 2119: Key words for use in RFCs
  • RFC 7515: JSON Web Signature (JWS)
  • RFC 8446: Transport Layer Security (TLS) 1.3

Informative References

  • Agent Telemetry Standard (ATS): Semantic telemetry format
  • JSON Canonicalization Scheme: RFC 8785
  • Semantic Versioning 2.0.0: https://semver.org

End of ACGP-1003