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.

Ces démarrages rapides sont disponibles en espagnol (Español) et en français (Français) — six pages par langue ont été traduites.

Installation

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

npm install --legacy-peer-deps @mnemom/agent-alignment-protocol @mnemom/agent-integrity-protocol

--legacy-peer-deps est nécessaire sur npm 7+ tant que @mnemom/agent-integrity-protocol 1.3.0 déclare encore une dépendance peer optionnelle sur le package alignment-protocol 1.x ; les deux SDK fonctionnent ensemble en 2.0.0 / 1.3.0.

Définir une carte d'alignement

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

from aap import AlignmentCard, Principal, Values, Autonomy, Audit

card = AlignmentCard(
    card_version="unified/2026-04-26",
    card_id="ac-my-agent-001",
    agent_id="my-agent",
    issued_at="2026-01-31T12:00:00Z",
    autonomy_mode="observe",
    integrity_mode="observe",

    principal=Principal(
        type="human",
        identifier="did:web:user.example.com",
        relationship="delegated_authority",
    ),

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

    autonomy=Autonomy(
        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=Audit(
        trace_format="ap-trace-v1",
        retention_days=90,
        queryable=True,
        query_endpoint="https://my-agent.example.com/api/v1/traces",
    ),
)

card_dict = card.model_dump()

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

const card: AlignmentCard = {
  card_version: 'unified/2026-04-26',
  card_id: 'ac-my-agent-001',
  agent_id: 'my-agent',
  issued_at: '2026-01-31T12:00:00Z',
  autonomy_mode: 'observe',
  integrity_mode: 'observe',

  principal: {
    type: 'human',
    identifier: 'did:web:user.example.com',
    relationship: 'delegated_authority',
  },

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

  autonomy: {
    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: {
    trace_format: 'ap-trace-v1',
    retention_days: 90,
    queryable: true,
    query_endpoint: 'https://my-agent.example.com/api/v1/traces',
  },
};

Les noms de champs ont changé dans la forme de carte unifiée (AAP 2.0.0). aap_version est maintenant card_version (ancré à une date) ; autonomy_envelope/AutonomyEnvelope est maintenant autonomy/Autonomy ; audit_commitment/AuditCommitment est maintenant audit/Audit ; autonomy_mode et integrity_mode sont de nouveaux champs de premier niveau ; principal.identifier est requis dès que principal.type n’est pas unspecified ; et audit.queryable: true nécessite audit.query_endpoint. Consultez la migration depuis l’ancienne forme de carte 0.5.0 pour le mapping complet.

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 significative prise par votre agent devrait produire une AP-Trace. La trace enregistre l’action effectuée, les alternatives envisagées, le raisonnement appliqué, et si l’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 à bounded_actions, pas action.type. Les deux champs servent des objectifs 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 retourne des vérifications structurelles, un score de similarité, et 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 (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 mais recevoir tout de même un avertissement low_behavioral_similarity si le score descend sous 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 de valeurs et la manipulation. Chaque vérification produit un verdict : clear, review_needed, ou boundary_violation.

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

Un client se charge de l’extraction, de l’appel LLM et de la comptabilité des points de contrôle/fenêtres pour vous — passez-lui le corps de réponse brut du fournisseur, pas une chaîne de réflexion pré-extraite. Le card ici est la forme de carte minimale propre à AIP (card_id, values, autonomy_envelope) — un petit sous-ensemble de champs, gardé séparé de l’AlignmentCard AAP complète que vous avez construite à l’étape 1, puisque @mnemom/agent-alignment-protocol n’est qu’une dépendance peer optionnelle pour AIP.

from aip import create_client
from aip.schemas.config import (
    AIPConfig, AnalysisLLMConfig, WindowConfig,
    AlignmentCard as AIPCard, AlignmentCardValue, AutonomyEnvelope,
)

client = create_client(AIPConfig(
    card=AIPCard(
        card_id="ac-my-agent-001",
        values=[AlignmentCardValue(name="principal_benefit", priority=1)],
        autonomy_envelope=AutonomyEnvelope(
            bounded_actions=["search", "compare", "recommend", "add_to_cart"],
        ),
    ),
    analysis_llm=AnalysisLLMConfig(
        model="claude-haiku-4-5-20251001",
        base_url="https://api.anthropic.com",
        api_key="your-anthropic-api-key",
        max_tokens=1024,
    ),
    window=WindowConfig(),
    agent_id="my-agent",
))

# response_body is the raw JSON text of the provider response your agent
# just received (the one carrying the thinking block to be analyzed).
signal = await client.check(response_body)

print(f"Verdict: {signal.checkpoint.verdict}")   # "clear"
print(f"Concerns: {signal.checkpoint.concerns}") # []
print(f"Proceed: {signal.proceed}")              # True
print(f"Action: {signal.recommended_action}")    # "continue"

import { createClient } from '@mnemom/agent-integrity-protocol';

const client = createClient({
  card: {
    card_id: 'ac-my-agent-001',
    values: [{ name: 'principal_benefit', priority: 1 }],
    autonomy_envelope: {
      bounded_actions: ['search', 'compare', 'recommend', 'add_to_cart'],
    },
  },
  analysis_llm: {
    model: 'claude-haiku-4-5-20251001',
    base_url: 'https://api.anthropic.com',
    api_key: 'your-anthropic-api-key',
    max_tokens: 1024,
  },
  window: {},
  agent_id: 'my-agent',
});

// responseBody is the raw JSON text of the provider response your agent
// just received (the one carrying the thinking block to be analyzed).
const signal = await client.check(responseBody);

console.log(`Verdict: ${signal.checkpoint.verdict}`);   // "clear"
console.log(`Concerns: ${signal.checkpoint.concerns}`); // []
console.log(`Proceed: ${signal.proceed}`);              // true
console.log(`Action: ${signal.recommended_action}`);    // "continue"

client.check() exécute le pipeline complet à chaque appel : extraire le bloc de réflexion pour le fournisseur détecté, appeler le LLM d’analyse, parser le verdict, mettre à jour la fenêtre glissante, et détecter la dérive. Il n’existe pas de fonction bas niveau séparée « parser simplement cette réponse d’analyse » dans l’API publique — check() est l’unique point d’entrée.

Mapping verdict vers action

Verdict	Proceed	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 une 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 qu’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

Démarrage rapide

Intégration SDK Direct

Intégration SDK directe

Installation

Mapping verdict vers action

Traçage automatique avec décorateurs (Python)

Détection de dérive

Prochaines étapes

​Intégration SDK directe

​Installation

​Mapping verdict vers action

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

​Détection de dérive

​Prochaines étapes

Intégration SDK directe

Installation

Mapping verdict vers action

Traçage automatique avec décorateurs (Python)

Détection de dérive

Prochaines étapes