Intégration SDK directe

Utilisez les SDK AAP et AIP pour ajouter la vérification d’alignement et la vérification d’intégrité directement à votre code applicatif. Cela vous donne un contrôle total sur le moment où les traces sont générées, la manière dont les vérifications d’intégrité s’exécutent et ce qui se passe en cas de violations. Pour les fonctionnalités de gouvernance (application des politiques, reclassification des violations, récupération de la confiance), utilisez l’API Policy et l’API Reclassification en complément des SDK.

Installation

pip install agent-alignment-protocol agent-integrity-proto

npm install @mnemom/agent-alignment-protocol @mnemom/agent-integrity-protocol

Définir une carte d'alignement

Une carte d’alignement déclare l’identité de votre agent, ses valeurs, ses limites d’autonomie et ses engagements d’audit. Chaque trace et chaque vérification d’intégrité est vérifiée par rapport à cette carte.

from aap import AlignmentCard, Principal, Values, AutonomyEnvelope, AuditCommitment

card = AlignmentCard(
    aap_version="1.0.0",
    card_id="ac-my-agent-001",
    agent_id="my-agent",
    issued_at="2026-01-31T12:00:00Z",

    principal=Principal(
        type="human",
        relationship="delegated_authority",
    ),

    values=Values(
        declared=["principal_benefit", "transparency", "minimal_data"],
        conflicts_with=["deceptive_marketing", "hidden_fees"],
    ),

    autonomy_envelope=AutonomyEnvelope(
        bounded_actions=["search", "compare", "recommend", "add_to_cart"],
        escalation_triggers=[
            {"condition": "action_type == \"purchase\"", "action": "escalate",
             "reason": "Purchases require approval"},
            {"condition": "purchase_value > 100", "action": "escalate",
             "reason": "Exceeds spending limit"},
        ],
        forbidden_actions=["share_credentials", "subscribe_to_services"],
    ),

    audit_commitment=AuditCommitment(
        trace_format="ap-trace-v1",
        retention_days=90,
        queryable=True,
    ),
)

card_dict = card.model_dump()

import type { AlignmentCard } from '@mnemom/agent-alignment-protocol';

const card: AlignmentCard = {
  aap_version: '1.0.0',
  card_id: 'ac-my-agent-001',
  agent_id: 'my-agent',
  issued_at: '2026-01-31T12:00:00Z',

  principal: {
    type: 'human',
    relationship: 'delegated_authority',
  },

  values: {
    declared: ['principal_benefit', 'transparency', 'minimal_data'],
    conflicts_with: ['deceptive_marketing', 'hidden_fees'],
  },

  autonomy_envelope: {
    bounded_actions: ['search', 'compare', 'recommend', 'add_to_cart'],
    escalation_triggers: [
      { condition: 'action_type == "purchase"', action: 'escalate',
        reason: 'Purchases require approval' },
      { condition: 'purchase_value > 100', action: 'escalate',
        reason: 'Exceeds spending limit' },
    ],
    forbidden_actions: ['share_credentials', 'subscribe_to_services'],
  },

  audit_commitment: {
    trace_format: 'ap-trace-v1',
    retention_days: 90,
    queryable: true,
  },
};

La carte d’alignement est le fondement des deux protocoles. Définissez-la une fois et utilisez-la pour la vérification AAP, la vérification d’intégrité AIP et les vérifications de cohérence des valeurs.

Générer des AP-Traces à partir des actions de l'agent

Chaque décision importante prise par votre agent doit produire une AP-Trace. La trace enregistre l’action effectuée, les alternatives envisagées, le raisonnement appliqué et si une escalade a été évaluée.

from aap import APTrace, Action, Decision, Alternative, Escalation
from datetime import datetime
import uuid

trace = APTrace(
    trace_id=f"tr-{uuid.uuid4().hex[:12]}",
    agent_id="my-agent",
    card_id="ac-my-agent-001",
    timestamp=datetime.utcnow().isoformat() + "Z",

    action=Action(
        type="recommend",
        name="recommend",
        category="bounded",
    ),

    decision=Decision(
        alternatives_considered=[
            Alternative(option_id="prod-A", description="Widget Pro",
                       score=0.9, scoring_factors={"relevance": 0.95, "value": 0.85}),
            Alternative(option_id="prod-B", description="Widget Basic",
                       score=0.7, scoring_factors={"relevance": 0.80, "value": 0.60}),
            Alternative(option_id="prod-C", description="Sponsored Widget",
                       score=0.5, scoring_factors={"relevance": 0.50, "value": 0.40},
                       flags=["sponsored_content"]),
        ],
        selected="prod-A",
        selection_reasoning="Highest preference match. Sponsored options deprioritized per principal_benefit value.",
        values_applied=["principal_benefit", "transparency"],
        confidence=0.9,
    ),

    escalation=Escalation(
        evaluated=True,
        triggers_checked=[
            {"trigger": "action_type == \"purchase\"", "matched": False},
        ],
        required=False,
        reason="Recommendation only, no purchase action",
    ),
)

trace_dict = trace.model_dump()

import type { APTrace } from '@mnemom/agent-alignment-protocol';

const trace: APTrace = {
  trace_id: `tr-${crypto.randomUUID().slice(0, 12)}`,
  agent_id: 'my-agent',
  card_id: 'ac-my-agent-001',
  timestamp: new Date().toISOString(),

  action: {
    type: 'recommend',
    name: 'recommend',
    category: 'bounded',
  },

  decision: {
    alternatives_considered: [
      { option_id: 'prod-A', description: 'Widget Pro',
        score: 0.9, scoring_factors: { relevance: 0.95, value: 0.85 } },
      { option_id: 'prod-B', description: 'Widget Basic',
        score: 0.7, scoring_factors: { relevance: 0.80, value: 0.60 } },
      { option_id: 'prod-C', description: 'Sponsored Widget',
        score: 0.5, scoring_factors: { relevance: 0.50, value: 0.40 },
        flags: ['sponsored_content'] },
    ],
    selected: 'prod-A',
    selection_reasoning:
      'Highest preference match. Sponsored options deprioritized per principal_benefit value.',
    values_applied: ['principal_benefit', 'transparency'],
    confidence: 0.9,
  },

  escalation: {
    evaluated: true,
    triggers_checked: [
      { trigger: 'action_type == "purchase"', matched: false },
    ],
    required: false,
    reason: 'Recommendation only, no purchase action',
  },
};

La vérification compare action.name avec bounded_actions, et non action.type. Ces deux champs ont des rôles différents : type est une catégorie sémantique ; name est l’identifiant d’opération spécifique vérifié par rapport à la liste bounded_actions de la carte.

Vérifier les traces par rapport à la carte

La vérification contrôle si le comportement de l’agent (enregistré dans la trace) est cohérent avec son alignement déclaré (la carte). Elle renvoie des vérifications structurelles, un score de similarité, ainsi que toute violation ou avertissement.

from aap import verify_trace

result = verify_trace(trace_dict, card_dict)

print(f"Verified: {result.verified}")
print(f"Similarity: {result.similarity_score:.2f}")

if not result.verified:
    for violation in result.violations:
        print(f"VIOLATION [{violation.severity}]: {violation.type}")
        print(f"  {violation.description}")

for warning in result.warnings:
    print(f"WARNING: {warning.type}")
    print(f"  {warning.description}")

# Example output for a compliant trace:
# Verified: True
# Similarity: 0.82

# Example output for a violation:
# Verified: False
# Similarity: 0.15
# VIOLATION [HIGH]: unbounded_action
#   Action 'delete_account' not in bounded_actions

import { verifyTrace } from '@mnemom/agent-alignment-protocol';

const result = verifyTrace(trace, card);

console.log(`Verified: ${result.verified}`);
console.log(`Similarity: ${result.similarity_score.toFixed(2)}`);

if (!result.verified) {
  for (const violation of result.violations) {
    console.log(`VIOLATION [${violation.severity}]: ${violation.type}`);
    console.log(`  ${violation.description}`);
  }
}

for (const warning of result.warnings) {
  console.log(`WARNING: ${warning.type}`);
  console.log(`  ${warning.description}`);
}

Le similarity_score (de 0.0 à 1.0) mesure à quel point le comportement de la trace est sémantiquement similaire à l’alignement déclaré. Une trace peut passer toutes les vérifications structurelles tout en recevant un avertissement low_behavioral_similarity si le score tombe en dessous de 0.50. Consultez la calibration pour savoir comment les seuils ont été dérivés.

Ajouter des points de contrôle d'intégrité

La vérification d’intégrité AIP analyse les blocs de réflexion du LLM à chaque tour pour détecter l’injection de prompt, la dérive des valeurs et la manipulation. Chaque vérification produit un verdict : clear, review_needed ou boundary_violation.

AIP utilise par défaut le mode fail-open. Si le LLM d’analyse est inaccessible, les vérifications d’intégrité passeront silencieusement. Pour les déploiements en production gérant des opérations sensibles, définissez failure_policy: { mode: "fail_closed" } dans votre configuration AIP.

from aip import check_integrity, build_signal

checkpoint = check_integrity(
    thinking_block="The user wants product recommendations. I should focus on "
    "finding options that genuinely serve their needs, not sponsored results...",
    card=card_dict,
    config={
        "agent_id": "my-agent",
        "analysis_llm": {
            "model": "claude-haiku-4-5-20251001",
            "base_url": "https://api.anthropic.com",
            "api_key": "your-anthropic-api-key",
            "max_tokens": 1024,
        },
    },
)

print(f"Verdict: {checkpoint.verdict}")       # "clear"
print(f"Concerns: {checkpoint.concerns}")     # []

# Build signal for your host system
signal = build_signal(checkpoint, window_state)
print(f"Proceed: {signal.proceed}")           # True
print(f"Action: {signal.recommended_action}") # "continue"

import { checkIntegrity, buildSignal } from '@mnemom/agent-integrity-protocol';

const checkpoint = await checkIntegrity({
  thinkingBlock:
    'The user wants product recommendations. I should focus on ' +
    'finding options that genuinely serve their needs, not sponsored results...',
  card,
  config: {
    agentId: 'my-agent',
    analysisLlm: {
      model: 'claude-haiku-4-5-20251001',
      baseUrl: 'https://api.anthropic.com',
      apiKey: 'your-anthropic-api-key',
      maxTokens: 1024,
    },
  },
});

console.log(`Verdict: ${checkpoint.verdict}`);     // "clear"
console.log(`Concerns: ${checkpoint.concerns}`);   // []

const signal = buildSignal(checkpoint, windowState);
console.log(`Proceed: ${signal.proceed}`);         // true
console.log(`Action: ${signal.recommended_action}`); // "continue"

Correspondance verdict → action

Verdict	Continuer	Action recommandée
`clear`	Oui	`continue`
`review_needed`	Oui	`log_and_continue`
`boundary_violation`	Non	`pause_for_review` ou `deny_and_escalate`

Vérifier la cohérence des valeurs

Avant que votre agent ne collabore avec un autre agent, vérifiez que leurs valeurs sont compatibles. La vérification de cohérence compare les valeurs déclarées et détecte les conflits.

from aap import check_coherence

their_card = {
    "card_id": "ac-vendor-agent",
    "values": {
        "declared": ["customer_satisfaction", "transparency", "upselling"],
        "conflicts_with": ["price_comparison"],
    },
    # ... other fields
}

result = check_coherence(card_dict, their_card)

print(f"Compatible: {result.compatible}")
print(f"Coherence score: {result.score}")
print(f"Matched values: {result.value_alignment.matched}")
print(f"Conflicts: {[c.description for c in result.value_alignment.conflicts]}")

if result.proceed:
    coordinate_with_agent(their_card)
else:
    if result.proposed_resolution:
        print(f"Suggested resolution: {result.proposed_resolution}")
    escalate_to_principal(result.value_alignment.conflicts)

# Example output:
# Compatible: False
# Coherence score: 0.4
# Matched values: ['transparency']
# Conflicts: ["Responder's 'upselling' may conflict with initiator's 'principal_benefit'"]

import { checkCoherence } from '@mnemom/agent-alignment-protocol';

const theirCard = {
  card_id: 'ac-vendor-agent',
  values: {
    declared: ['customer_satisfaction', 'transparency', 'upselling'],
    conflicts_with: ['price_comparison'],
  },
  // ... other fields
};

const result = checkCoherence(card, theirCard);

console.log(`Compatible: ${result.compatible}`);
console.log(`Coherence score: ${result.score}`);
console.log(`Matched values: ${result.value_alignment.matched}`);

if (!result.proceed) {
  console.log('Conflicts:', result.value_alignment.conflicts
    .map(c => c.description));
}

Traçage automatique avec décorateurs (Python)

Le SDK Python AAP fournit des décorateurs pour la génération automatique de traces :

from aap import trace_decision, TracedResult

@trace_decision(card_path="alignment-card.json")
def recommend_product(query: str) -> TracedResult:
    """Return TracedResult for detailed decision metadata."""
    products = find_products(query)
    best = products[0]

    return TracedResult(
        result=best,
        alternatives=[
            {"option_id": p["id"], "score": p["score"]}
            for p in products[:3]
        ],
        reasoning=f"Selected {best['name']} with highest score",
        values_applied=["principal_benefit", "transparency"],
        confidence=best["score"],
    )

Détection de dérive

Surveillez votre agent pour détecter toute dérive comportementale au fil du temps :

from aap import detect_drift

traces = [trace1, trace2, trace3, ...]  # List of trace dicts

alerts = detect_drift(traces=traces, card=card_dict)

for alert in alerts:
    print(f"DRIFT DETECTED for agent {alert.agent_id}")
    print(f"  Direction: {alert.analysis.drift_direction}")
    print(f"  Similarity score: {alert.analysis.similarity_score}")
    print(f"  Sustained for {alert.analysis.sustained_traces} traces")

import { detectDrift } from '@mnemom/agent-alignment-protocol';

const alerts = detectDrift(card, traces);

for (const alert of alerts) {
  console.log(`DRIFT DETECTED for agent ${alert.agent_id}`);
  console.log(`  Direction: ${alert.analysis.drift_direction}`);
  console.log(`  Similarity: ${alert.analysis.similarity_score}`);
  console.log(`  Sustained for ${alert.analysis.sustained_traces} traces`);
}

Prochaines étapes

Vue d’ensemble CLPI — Couche de gouvernance : application des politiques, récupération de la confiance, ancrage on-chain
API Policy — Gestion programmatique des politiques pour les intégrations SDK
API Reclassification — Reclassification des violations et récupération du score de confiance
Spécification AAP — Détails complets du protocole pour les implémenteurs
Spécification AIP — Détails du protocole d’intégrité
Limitations — Ce que AAP peut et ne peut pas garantir
Modèle de sécurité — Modèle de menace et surfaces d’attaque
Intégration A2A — Ajouter AAP aux flux de travail d’agents A2A
Migration MCP — Ajouter le traçage d’alignement aux outils MCP

​Intégration SDK directe

​Installation

​Correspondance verdict → action

​Traçage automatique avec décorateurs (Python)

​Détection de dérive

​Prochaines étapes

Intégration SDK directe

Installation

Correspondance verdict → action

Traçage automatique avec décorateurs (Python)

Détection de dérive

Prochaines étapes