> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AAP Architecture

> System architecture of the Agent Alignment Protocol including component relationships, data flow, and extension points

This document describes the system architecture of the Agent Alignment Protocol (AAP), including component relationships, data flow, and extension points.

## Protocol stack

AAP operates as an alignment layer that extends existing agent protocols:

```
+---------------------------------------------------------------------------+
|                         Applications                                       |
|            (Agent Systems, Orchestration Platforms)                        |
+---------------------------------------------------------------------------+
|                  AGENT ALIGNMENT PROTOCOL (AAP)                            |
|  +------------------+-----------------+----------------------------+      |
|  |  Alignment Card  |    AP-Trace     |   Value Coherence          |      |
|  |  (Declaration)   |  (Audit Trail)  |   (Multi-Agent Check)      |      |
|  +------------------+-----------------+----------------------------+      |
+---------------------------------------------------------------------------+
|           A2A Protocol          |         MCP Protocol                     |
|      (Agent-to-Agent Tasks)     |    (Tool Connectivity)                   |
+---------------------------------------------------------------------------+
|                         Transport Layer                                    |
|                   (HTTP, WebSocket, gRPC, etc.)                           |
+---------------------------------------------------------------------------+
```

**Key insight**: AAP does not replace A2A or MCP -- it extends them with alignment primitives.

## Component architecture

### Overview

```
+---------------------------------------------------------------------------+
|                           AAP SDK                                          |
|                                                                            |
|  +---------------------------------------------------------------------+  |
|  |                      Public API (3 entry points)                     |  |
|  |  verify_trace()    check_coherence()    detect_drift()              |  |
|  +---------------------------------------------------------------------+  |
|                                |                                           |
|  +-----------------------------+---------------------------------------+  |
|  |                    Verification Engine                               |  |
|  |  +-------------+  +-------------+  +---------------------+         |  |
|  |  |   api.py    |  | features.py |  |     models.py       |         |  |
|  |  | Orchestrate |  |  TF-IDF     |  |  Result Dataclasses |         |  |
|  |  | Checks      |  |  Extraction |  |  Violation Types    |         |  |
|  |  +-------------+  +-------------+  +---------------------+         |  |
|  |                          |                                          |  |
|  |  +-----------------------+--------------------------------------+  |  |
|  |  |                    constants.py                               |  |  |
|  |  |  SIMILARITY_THRESHOLD = 0.30  |  SUSTAINED_TURNS = 3         |  |  |
|  |  +--------------------------------------------------------------+  |  |
|  +---------------------------------------------------------------------+  |
|                                                                            |
|  +---------------------------------------------------------------------+  |
|  |                       Schema Layer                                   |  |
|  |  +-----------------+  +------------+  +-------------------+         |  |
|  |  | alignment_card  |  |  ap_trace  |  |  value_coherence  |         |  |
|  |  |   .py / .ts     |  |  .py / .ts |  |     .py / .ts     |         |  |
|  |  |   Pydantic      |  |  Pydantic  |  |     Pydantic      |         |  |
|  |  +-----------------+  +------------+  +-------------------+         |  |
|  +---------------------------------------------------------------------+  |
|                                                                            |
|  +---------------------------------------------------------------------+  |
|  |                    JSON Schemas (Interop)                            |  |
|  |  alignment-card.schema.json  |  ap-trace.schema.json                |  |
|  |                  value-coherence.schema.json                         |  |
|  +---------------------------------------------------------------------+  |
+---------------------------------------------------------------------------+
```

### Schemas module (`aap.schemas`)

The schemas module provides Pydantic models for the three core AAP components:

#### Alignment Card (`alignment_card.py`)

```
AlignmentCard  (unified shape, SDK 2.0.0)
+-- card_version: str ("unified/2026-04-26")
+-- card_id: str (unique identifier)
+-- agent_id: str (agent DID or identifier)
+-- issued_at: datetime
+-- expires_at: datetime (optional)
+-- autonomy_mode: AlignmentMode (off | observe | nudge | enforce)
+-- integrity_mode: AlignmentMode (off | observe | nudge | enforce)
+-- principal: Principal
|   +-- type: PrincipalType (human | organization | agent | unspecified)
|   +-- identifier: str (required unless type == "unspecified")
|   +-- relationship: RelationshipType (delegated_authority | advisory | autonomous)
|   +-- escalation_contact: str (optional, mailto: or https:)
+-- values: Values
|   +-- declared: list[str] (e.g., ["principal_benefit", "transparency"])
|   +-- conflicts_with: list[str] (optional)
|   +-- hierarchy: str (optional, "lexicographic" | "weighted" | "contextual")
|   +-- definitions: dict[str, ValueDefinition] (optional, custom values)
+-- autonomy: Autonomy   (renamed from legacy `autonomy_envelope`)
|   +-- bounded_actions: list[str] (allowed without escalation)
|   +-- escalation_triggers: list[EscalationTrigger]
|   +-- forbidden_actions: list[str] (never allowed)
|   +-- max_autonomous_value: MonetaryValue (optional)
+-- audit: Audit   (renamed from legacy `audit_commitment`; `storage` sub-object removed)
|   +-- retention_days: int
|   +-- queryable: bool
|   +-- tamper_evidence: str (optional, "append_only" | "signed" | "merkle")
+-- extensions: dict (optional, protocol-specific extensions)
```

#### AP-Trace (`ap_trace.py`)

```
APTrace
+-- trace_id: str (unique identifier)
+-- agent_id: str (must match card's agent_id)
+-- card_id: str (references Alignment Card)
+-- timestamp: datetime
+-- action: Action
|   +-- type: ActionType (recommend | execute | escalate | deny)
|   +-- name: str (action identifier)
|   +-- category: ActionCategory (bounded | escalation_trigger | forbidden)
|   +-- target: ActionTarget (optional)
|   +-- parameters: dict (optional)
+-- decision: Decision
|   +-- alternatives_considered: list[Alternative]  (minimum 1)
|   |   +-- option_id: str
|   |   +-- description: str
|   |   +-- score: float (0.0-1.0, optional)
|   +-- selected: str (option_id of chosen alternative)
|   +-- selection_reasoning: str (human-readable explanation)
|   +-- values_applied: list[str] (must be subset of declared values)
|   +-- confidence: float (optional, 0.0-1.0)
|   +-- value_scores: dict[str, ValueScore] (optional, SDK >= 1.3.0)
+-- escalation: Escalation (optional)
|   +-- evaluated: bool (was escalation logic run?)
|   +-- required: bool (did triggers fire?)
|   +-- reason: str
|   +-- escalation_status: str (optional: "pending" | "approved" | "denied" | "timeout")
|   +-- principal_response: dict (optional)
+-- context: TraceContext (optional)
    +-- session_id: str (optional)
    +-- conversation_turn: int (optional)
    +-- prior_trace_ids: list[str] (optional)
    +-- environment: dict (optional)
    +-- metadata: dict (optional)
```

#### Value Coherence (`value_coherence.py`)

```
ValueCoherenceCheck
+-- initiator_card_id: str
+-- responder_card_id: str
+-- task_values: list[str] (optional, values required for task)
+-- result: CoherenceResult
    +-- compatible: bool
    +-- score: float (0.0-1.0)
    +-- value_alignment: ValueAlignment
    |   +-- matched: list[str]
    |   +-- unmatched: list[str]
    |   +-- conflicts: list[ValueConflict]
    +-- proceed: bool
    +-- conditions: list[str]
    +-- proposed_resolution: dict (optional)
```

### Verification engine (`aap.verification`)

The verification engine implements the three core operations:

#### `verify_trace(trace, card) -> VerificationResult`

Performs seven verification checks (SPEC Section 7.3), tracked in `verification_metadata.checks_performed`:

```
1. card_reference        -> Does trace.card_id match card.card_id?
2. card_expiration       -> Is card still valid (not expired)?
3. autonomy              -> Is action.name in bounded_actions?
4. forbidden             -> Is action.name NOT in forbidden_actions?
5. escalation            -> If trigger matched, was escalation.required=true?
6. values                -> Are values_applied subset of declared values?
7. behavioral_similarity -> Is the trace semantically similar to the card (SSM analysis)?
```

Returns `VerificationResult`:

* `verified: bool` -- True if no violations
* `recommended_action: "proceed" | "review" | "deny"` -- Derived from violations/warnings
* `violations: list[Violation]` -- Type, description, severity
* `warnings: list[Warning]` -- Near-boundary and low-similarity conditions
* `verification_metadata` -- Algorithm version, checks performed, duration

#### `check_coherence(my_card, their_card) -> CoherenceResult`

Computes value compatibility score (SPEC Section 6.4):

```
score = (matched / required) * (1 - conflict_penalty)
where conflict_penalty = min(1.0, 0.5 * (conflicts / required))
```

Returns `CoherenceResult`:

* `compatible: bool` -- Zero conflicts AND score >= 0.70 (`MIN_COHERENCE_FOR_PROCEED`)
* `score: float` -- Coherence score \[0, 1]
* `value_alignment` -- Matched, unmatched, conflicts
* `proceed: bool` -- Mirrors `compatible`
* `proposed_resolution` -- If incompatible, suggests escalation

#### `detect_drift(card, traces, thresholds) -> list[DriftAlert]`

Analyzes trace sequence for behavioral drift (SPEC Section 8, v1.2.0 methodology):

```
1. Extract structural features per trace (action, values applied, escalation, confidence)
2. Compute a baseline centroid from the first N traces
3. For each subsequent trace, compare to the baseline centroid via cosine similarity
4. Track low-similarity streak
5. If streak >= sustained_threshold:
   -> Generate DriftAlert with direction inference
```

Drift directions:

* `value_drift` -- Using undeclared values (>30% of recent)
* `autonomy_expansion` -- Escalation rate dropped by >50%
* `principal_misalignment` -- Declining confidence on principal\_benefit
* `unknown` -- Pattern doesn't match known categories

### Feature extraction (`features.py`)

Structural feature extraction for drift detection (not TF-IDF -- see [calibration](/protocols/aap/calibration) for why content tokens are excluded from drift scoring). TF-IDF weighting is used separately, for text-to-text SSM similarity:

```python theme={null}
class FeatureExtractor:
    def extract_card_features(card: dict) -> dict[str, float]:
        # Returns structural feature vector from declared values, bounded/forbidden actions

    def extract_trace_features(trace: dict) -> dict[str, float]:
        # Returns structural feature vector from applied values, action, escalation, confidence

def cosine_similarity(features1: dict, features2: dict) -> float:
    # Computes similarity between feature vectors
```

### Constants (`constants.py`)

Calibrated thresholds derived from corpus analysis (see [calibration](/protocols/aap/calibration)):

```python theme={null}
ALGORITHM_VERSION = "1.2.0"
DEFAULT_SIMILARITY_THRESHOLD = 0.30      # Alert below this
DEFAULT_SUSTAINED_TURNS_THRESHOLD = 3    # Alert after N consecutive low traces (Python name;
                                          # TypeScript SDK: DEFAULT_SUSTAINED_CHECKS_THRESHOLD)
NEAR_BOUNDARY_THRESHOLD = 0.35           # Warn when confidence/score below
CONFLICT_PENALTY_MULTIPLIER = 0.50       # Coherence penalty per conflict
MIN_COHERENCE_FOR_PROCEED = 0.70         # Minimum score to proceed
```

## Data flow

### Single trace verification

```
+-----------------+     +-----------------+
|  Alignment Card |     |    AP-Trace     |
|   (JSON/dict)   |     |   (JSON/dict)   |
+--------+--------+     +--------+--------+
         |                       |
         +-----------+-----------+
                     |
                     v
         +-----------------------+
         |     verify_trace()    |
         |  +-----------------+  |
         |  | 1. Card Match   |  |
         |  | 2. Expiration   |  |
         |  | 3. Autonomy     |  |
         |  | 4. Forbidden    |  |
         |  | 5. Escalation   |  |
         |  | 6. Values       |  |
         |  +-----------------+  |
         +-----------+-----------+
                     |
                     v
         +-----------------------+
         |  VerificationResult   |
         |  - verified: bool     |
         |  - violations: [...]  |
         |  - warnings: [...]    |
         +-----------------------+
```

### Multi-agent coherence check

```
+-----------------+     +-----------------+
|  Agent A Card   |     |  Agent B Card   |
|  (My Values)    |     |  (Their Values) |
+--------+--------+     +--------+--------+
         |                       |
         +-----------+-----------+
                     |
                     v
         +-----------------------+
         |   check_coherence()   |
         |  +-----------------+  |
         |  | 1. Extract vals |  |
         |  | 2. Find matches |  |
         |  | 3. Find conflicts|  |
         |  | 4. Compute score|  |
         |  +-----------------+  |
         +-----------+-----------+
                     |
                     v
         +-----------------------+
         |   CoherenceResult     |
         |  - compatible: bool   |
         |  - score: 0.0-1.0     |
         |  - conflicts: [...]   |
         |  - proceed: bool      |
         +-----------------------+
                     |
         +-----------+-----------+
         v                       v
    [proceed=true]         [proceed=false]
    Safe to delegate       Escalate to principals
```

### Drift detection over time

```
+-----------------+     +--------------------------------------+
|  Alignment Card |     |     Trace Sequence (chronological)   |
|  (Baseline)     |     |  [T1] -> [T2] -> [T3] -> [T4] -> [T5] |
+--------+--------+     +-----------------+--------------------+
         |                                |
         +----------------+---------------+
                          |
                          v
              +-----------------------+
              |    detect_drift()     |
              |  +-----------------+  |
              |  | For each trace: |  |
              |  |  - Extract feat |  |
              |  |  - Cosine sim   |  |
              |  |  - Track streak |  |
              |  +-----------------+  |
              +-----------+-----------+
                          |
              +-----------+-----------+
              v                       v
      [similarity >= 0.30]    [similarity < 0.30]
      Reset streak            Increment streak
                                     |
                              streak >= 3?
                                     |
                              +------+------+
                              v             v
                         [No alert]    [DriftAlert]
                                       - direction
                                       - indicators
                                       - trace_ids
```

## Extension points

### 1. Custom values

Define domain-specific values in `values.definitions`:

```json theme={null}
{
  "values": {
    "declared": ["principal_benefit", "sustainability"],
    "definitions": {
      "sustainability": {
        "name": "Environmental Sustainability",
        "description": "Prefer options minimizing environmental impact",
        "priority": 3
      }
    }
  }
}
```

### 2. Protocol extensions

Add protocol-specific data in `extensions`:

```json theme={null}
{
  "extensions": {
    "a2a": {
      "skills": ["search", "recommend"],
      "agent_card_url": "https://agent.example.com/.well-known/agent.json"
    },
    "mcp": {
      "tools": ["filesystem_read", "web_search"],
      "server_name": "my-tools"
    }
  }
}
```

### 3. Custom escalation triggers

Define complex conditions in `escalation_triggers`:

```json theme={null}
{
  "escalation_triggers": [
    {
      "condition": "action_type == \"purchase\"",
      "action": "escalate",
      "reason": "Purchases require approval"
    },
    {
      "condition": "amount > 100",
      "action": "escalate",
      "reason": "High-value transactions"
    },
    {
      "condition": "shares_personal_data",
      "action": "deny",
      "reason": "Never share PII"
    }
  ]
}
```

Supported condition syntax (SPEC Section 4.6):

* `field == "value"` -- String equality
* `field > N` -- Numeric comparison (`>`, `<`, `>=`, `<=`, `!=`)
* `field_name` -- Boolean check (truthy)

### 4. Verification customization

Override default thresholds:

```python theme={null}
# Custom drift detection thresholds
alerts = detect_drift(
    card,
    traces,
    similarity_threshold=0.25,  # More sensitive
    sustained_threshold=2,       # Faster alerting
)
```

### 5. Integration hooks

For A2A integration, extend the Agent Card:

```json theme={null}
{
  "name": "My Agent",
  "skills": [...],
  "alignment": {
    "$ref": "./alignment-card.json"
  }
}
```

For MCP integration, add alignment to tool manifests:

```json theme={null}
{
  "tools": [...],
  "resources": [
    {
      "uri": "alignment://card",
      "name": "Alignment Card",
      "mimeType": "application/json"
    }
  ]
}
```

## Implementation notes

### Python SDK

* **Location**: `src/aap/`
* **Models**: Pydantic v2 with strict validation
* **Type hints**: Full coverage, `py.typed` marker
* **Dependencies**: Only `pydantic>=2.0`

```bash theme={null}
pip install agent-alignment-protocol
```

### TypeScript SDK

* **Location**: `typescript/src/`
* **Output formats**: CJS, ESM, DTS
* **Types**: Full TypeScript types, no `any`
* **Dependencies**: None (zero runtime deps)

```bash theme={null}
npm install @mnemom/agent-alignment-protocol
```

### JSON schemas

* **Location**: `schemas/`
* **Format**: JSON Schema Draft 2020-12
* **Generated from**: Pydantic models via `model_json_schema()`

Schemas can be used for:

* Validation in any language (ajv, jsonschema, etc.)
* Code generation (quicktype, json-schema-to-typescript)
* Documentation (JSON Schema viewers)

### Browser (Playground)

* **Live**: [mnemom.github.io/aap/playground](https://mnemom.github.io/aap/playground/)
* **Runtime**: Pyodide (Python in WASM)
* **API**: `window.AAP.verifyTrace()`, `window.AAP.checkCoherence()`, `window.AAP.detectDrift()`
* **No server**: All verification runs client-side

## Security considerations

See [security](/protocols/aap/security) for the full threat model. Key points:

1. **AAP does not ensure alignment** -- It provides visibility, not guarantees
2. **AP-Traces are self-reported** -- Adversarial agents can lie
3. **Verification is point-in-time** -- Does not prevent future violations
4. **Thresholds are calibrated** -- But may not fit all domains

Defense in depth:

* Use AAP alongside behavioral monitoring
* Implement rate limiting and anomaly detection
* Maintain human oversight for high-stakes decisions
* Regularly audit AP-Trace storage for integrity

## See also

* [specification](/protocols/aap/specification) -- Full protocol specification
* [limitations](/protocols/aap/limitations) -- What AAP does NOT guarantee
* [calibration](/protocols/aap/calibration) -- Threshold derivation methodology
* [quickstart](/protocols/aap/quickstart) -- 5-minute integration guide
* [A2A integration](/protocols/aap/a2a-integration) -- A2A integration guide
* [MCP migration](/protocols/aap/mcp-migration) -- MCP integration guide


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.