Multi-Agent setup

Configure multiple AI agents with Alignment Cards, verify value compatibility before coordination, and monitor fleet-wide alignment with Mnemom Gateway. When you operate more than one agent — a shopping assistant, a data analyst, an internal scheduler — each one needs its own alignment posture. And when those agents interact, their declared values need to be compatible. This guide walks through registering multiple agents, checking value coherence between them, monitoring the fleet, and configuring enforcement per agent.

Why multi-agent alignment matters

A single agent’s alignment is between it and its principal. Multi-agent alignment introduces a harder problem: inter-agent compatibility. Two agents can each be perfectly aligned with their respective principals while being fundamentally incompatible with each other. Consider:

Agent A declares minimal_data as a core value. Agent B requires comprehensive_analytics to function. If A delegates data collection to B, whose value wins?
Agent A commits to transparency and discloses all reasoning. Agent B treats its decision process as proprietary. Their definitions of good behavior conflict.
Agent A’s conflicts_with list includes a value that Agent B declares. No amount of runtime negotiation fixes a structural incompatibility.

AAP’s Value Coherence Handshake checks this before coordination begins. It compares Alignment Cards pairwise and returns a compatibility score, conflict list, and proceed/block recommendation — so you catch structural mismatches at configuration time, not at runtime.

Registering multiple agents

Each agent gets its own Alignment Card declaring its values, autonomy envelope, and audit commitment. There is no shared card for a fleet — alignment is per-agent. Here are two agents with different value sets and operational scopes:

from aap import AlignmentCard

shopping_agent = AlignmentCard(
    agent_id="did:web:shopping.agent.example.com",
    principal={"type": "human", "relationship": "delegated_authority"},
    values={
        "declared": ["principal_benefit", "transparency", "honesty"],
        "definitions": {
            "principal_benefit": "Recommendations optimize for the user's stated needs, not commission.",
            "transparency": "Disclose reasoning behind every product recommendation.",
        },
        "conflicts_with": ["deceptive_marketing"],
    },
    autonomy_envelope={
        "bounded_actions": ["search_products", "compare_prices", "recommend"],
        "forbidden_actions": ["purchase_without_confirmation", "store_payment_info"],
        "escalation_triggers": ["price_above_budget", "out_of_stock_substitution"],
    },
    audit_commitment={
        "retention_days": 90,
        "queryable": True,
        "tamper_evidence": "append_only",
        "trace_format": "ap-trace-v1",
    },
)

data_analyst = AlignmentCard(
    agent_id="did:web:analyst.agent.example.com",
    principal={"type": "human", "relationship": "advisory"},
    values={
        "declared": ["accuracy", "minimal_data", "transparency"],
        "definitions": {
            "accuracy": "Report findings exactly as computed, flag uncertainty explicitly.",
            "minimal_data": "Request only the data fields necessary for the analysis.",
        },
        "conflicts_with": ["data_hoarding", "selective_reporting"],
    },
    autonomy_envelope={
        "bounded_actions": ["query_database", "compute_statistics", "generate_report"],
        "forbidden_actions": ["export_raw_pii", "modify_source_data"],
        "escalation_triggers": ["anomaly_detected", "data_quality_below_threshold"],
    },
    audit_commitment={
        "retention_days": 90,
        "queryable": True,
        "tamper_evidence": "append_only",
        "trace_format": "ap-trace-v1",
    },
)

Each agent’s values.definitions field is optional but recommended. Definitions remove ambiguity when two agents declare the same value name but mean different things by it.

Value Coherence checks

Before two agents coordinate on a task, run a coherence check to verify their values are compatible. The check_coherence function compares both Alignment Cards and returns a structured result.

from aap import check_coherence

result = check_coherence(
    initiator_card=shopping_agent.to_dict(),
    responder_card=data_analyst.to_dict(),
    required_values=["transparency"],
)

print(f"Compatible: {result.compatible}")   # True
print(f"Score: {result.score}")             # 0.82
print(f"Matched: {result.matched}")         # ["transparency"]
print(f"Conflicts: {result.conflicts}")     # []

if result.compatible:
    print("Agents can coordinate on this task.")
else:
    print(f"Blocked: {result.conflicts}")

Understanding the result

The coherence result contains three key fields:

Field	Type	Description
`compatible`	boolean	Whether the agents can safely coordinate. `false` if any declared value conflicts with the other agent’s `conflicts_with` list.
`score`	float (0-1)	Numeric coherence score. Higher means more value overlap. Scores below 0.70 trigger a `proceed: false` recommendation.
`conflicts`	list	Specific value conflicts found — e.g., one agent declares a value the other explicitly opposes.

Coherence checks operate on declared values only. They verify that two agents’ claims are compatible, not that either agent actually acts on those values. Behavioral verification happens through AP-Traces and integrity checkpoints.

For the full protocol exchange and advanced options, see Value Coherence.

Fleet monitoring with the Mnemom Gateway

When you run multiple agents through the Mnemom gateway, each agent gets its own:

Trace history — Every AP-Trace and integrity checkpoint is stored per agent, queryable by agent ID.
Integrity scores — Rolling integrity ratio computed from recent checkpoints. A healthy agent stays above 0.90.
Drift alerts — Automated alerts when behavioral patterns shift away from the agent’s declared alignment.

The Mnemom dashboard shows fleet-wide status at a glance: which agents are healthy, which are drifting, and which have active violations.

Fleet Dashboard
────────────────────────────────────────────────────
Agent                     Integrity   Drift    Mode
────────────────────────────────────────────────────
shopping.agent            0.97        none     enforce
analyst.agent             0.94        none     enforce
staging.recommender       0.81        warning  observe
────────────────────────────────────────────────────

See Mnemom Gateway Overview for gateway setup and dashboard configuration.

Drift detection across agents

Each agent should be monitored for drift independently. Drift is the gradual divergence of an agent’s behavior from its declared alignment — it rarely appears as a single dramatic violation. More commonly, an agent that used to escalate 15% of decisions quietly drops to 5%, or stops applying a declared value in its traces. Use detect_drift per agent to compare recent traces against the agent’s baseline:

from aap import detect_drift

# Check each agent independently
for agent_id in ["shopping.agent", "analyst.agent"]:
    traces = fetch_traces(agent_id=agent_id, days=30)
    card = fetch_alignment_card(agent_id=agent_id)

    alerts = detect_drift(
        traces=traces,
        card=card,
        similarity_threshold=0.30,
        sustained_threshold=3,
    )

    if alerts:
        for alert in alerts:
            print(f"[{agent_id}] Drift detected: {alert.drift_direction}")
            print(f"  Similarity: {alert.similarity_score}")
            print(f"  Sustained traces: {alert.sustained_traces}")
    else:
        print(f"[{agent_id}] No drift detected.")

Drift alerts surface when an agent’s behavior diverges from its declared alignment over time — not from a single anomalous trace. The sustained_threshold parameter controls how many consecutive low-similarity traces are required before an alert fires, preventing false positives from one-off edge cases.

Run drift detection on a schedule (e.g., daily or after every N traces) rather than on every request. Drift is a trend, not a point-in-time check.

For the full drift detection algorithm, calibration thresholds, and alert structure, see Drift Detection.

Enforcement modes per agent

Each agent in your fleet can have its own enforcement mode, controlling how the gateway responds when violations are detected. The three modes are:

Mode	Behavior
observe	Detect and record violations, take no action. Default for new agents.
nudge	Inject feedback into the agent’s next request so it can self-correct.
enforce	Hard block (403) for non-streaming requests. Falls back to nudge for streaming.

Set enforcement mode per agent by updating the alignment card’s top-level integrity_mode / autonomy_mode fields. Per ADR-039, these are master switches on the alignment card; the legacy per-agent /enforcement endpoint was retired 2026-05-14. The pattern is the standard alignment-card read-modify-write flow — see Card Management. The simplest fleet-scale loop (CLI):

# Production agents → enforce
for agent in shopping.agent checkout.agent; do
  mnemom card edit --agent "$agent" --set integrity_mode=enforce --set autonomy_mode=enforce
done

# Staging agents → observe
for agent in staging.recommender staging.support; do
  mnemom card edit --agent "$agent" --set integrity_mode=observe --set autonomy_mode=observe
done

The programmatic SDK path mirrors the same shape — fetch the alignment card, update the master switches, PUT it back. See Card Management § Read-modify-write for the full request/response examples and idempotency-key handling. A common fleet pattern:

Production agents on enforce — violations are blocked before reaching end users.
Staging agents on observe — violations are recorded for review during testing without blocking development workflows.
New agents on nudge — the agent gets feedback and a chance to self-correct while you build confidence in its alignment.

For full details on each mode, see Enforcement Modes.

API-based registration

In addition to CLI-based setup, you can register and manage agents programmatically via the CRUD API. This is useful for automated fleet provisioning, CI/CD pipelines, and dynamic agent lifecycle management.

Method	Endpoint	Description
`POST`	`/v1/agents`	Register a new agent with name and hash proof
`GET`	`/v1/agents`	List all agents owned by the authenticated user
`PUT`	`/v1/agents/:id`	Update an agent’s name
`DELETE`	`/v1/agents/:id`	GDPR Art. 17 deletion — async cascade, returns `202 Accepted`; poll `GET /v1/agents/{id}/deletion-status` for progress

When registering an agent, you must provide a hash_proof — the SHA-256 hex digest of your API key combined with the agent name (SHA256(apiKey + '|' + agentName)). This proves ownership of the API key without transmitting it. See Agent Identity § Registration for the canonical formula, the auto-create vs programmatic paths, and the legacy claim/link flow.

# Register a new agent. A default alignment card is attached automatically.
# hash_proof is SHA256(apiKey + '|' + name) — full 64-char hex; the API
# truncates it to the 16-char agent_hash. Compute client-side; never
# transmit the raw API key.
curl -X POST https://api.mnemom.ai/v1/agents \
  -H "Authorization: Bearer $MNEMOM_JWT" \
  -H "content-type: application/json" \
  -d '{
    "name": "shopping-agent",
    "hash_proof": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
  }'

The response includes the agent_hash (the gateway-computed identity) and card_id (the default alignment card attached on registration). If an agent with the same hash already exists, the API returns 409 Conflict. To customize the card post-registration, publish a unified alignment card with PUT /v1/agents/{agent_id}/alignment-card — see the card management guide for the full flow. Policy (capability mappings + enforcement rules) is now embedded in the alignment card’s capabilities and enforcement sections; there is no separate policy_yaml field.

DELETE /v1/agents/:id is a GDPR Art. 17 deletion per ADR-021. The API responds 202 Accepted immediately with a deletion_request_id; the server then cascades through traces, checkpoints, drift alerts, reclassifications, and other agent-owned records asynchronously. Poll /v1/agents/{id}/deletion-status or subscribe to the deletion webhook to know when the cascade completes.

Next steps

AAP Quickstart

Create your first Alignment Card, generate a traced decision, and verify it in 5 minutes.

Enforcement Modes

Deep dive into observe, nudge, and enforce modes with streaming behavior and configuration options.

API Reference

Full API reference for agents, traces, coherence checks, drift detection, and enforcement.

Guides

Safe House

Multi-Agent Setup

Multi-Agent setup

Why multi-agent alignment matters

Registering multiple agents

Value Coherence checks

Understanding the result

Fleet monitoring with the Mnemom Gateway

Drift detection across agents

Enforcement modes per agent

API-based registration

Next steps

AAP Quickstart

Enforcement Modes

API Reference

Guides

Safe House

Documentation Index

​Multi-Agent setup

​Why multi-agent alignment matters

​Registering multiple agents

​Value Coherence checks

​Understanding the result

​Fleet monitoring with the Mnemom Gateway

​Drift detection across agents

​Enforcement modes per agent

​API-based registration

​Next steps

AAP Quickstart

Enforcement Modes

API Reference

Multi-Agent setup

Why multi-agent alignment matters

Registering multiple agents

Value Coherence checks

Understanding the result

Fleet monitoring with the Mnemom Gateway

Drift detection across agents

Enforcement modes per agent

API-based registration

Next steps