> ## 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.

# Intégration SDK Direct

> Intégrez la vérification d'alignement, la vérification d'intégrité et la gouvernance des politiques directement dans votre application

# 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](/api-reference/policy-overview) et l'[API Reclassification](/api-reference/reclassification-overview) en complément des SDK.

<Note>
  Ces démarrages rapides sont disponibles en [espagnol (Español)](/es/quickstart/overview) et en [français (Français)](/fr/quickstart/overview) — six pages par langue ont été traduites.
</Note>

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install agent-alignment-protocol agent-integrity-proto
  ```

  ```bash TypeScript theme={null}
  npm install --legacy-peer-deps @mnemom/agent-alignment-protocol @mnemom/agent-integrity-protocol
  ```
</CodeGroup>

<Note>
  `--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.
</Note>

<Steps>
  <Step title="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.

    <CodeGroup>
      ```python Python theme={null}
      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()
      ```

      ```typescript TypeScript theme={null}
      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',
        },
      };
      ```
    </CodeGroup>

    <Note>
      **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](/protocols/aap/specification#410-migrating-from-the-legacy-050-card-shape) pour le mapping complet.
    </Note>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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.

    <CodeGroup>
      ```python Python theme={null}
      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()
      ```

      ```typescript TypeScript theme={null}
      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',
        },
      };
      ```
    </CodeGroup>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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.

    <CodeGroup>
      ```python Python theme={null}
      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
      ```

      ```typescript TypeScript theme={null}
      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}`);
      }
      ```
    </CodeGroup>

    <Note>
      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](/protocols/aap/calibration) pour savoir comment les seuils ont été dérivés.
    </Note>
  </Step>

  <Step title="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`.

    <Warning>
      **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.
    </Warning>

    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.

    <CodeGroup>
      ```python Python theme={null}
      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"
      ```

      ```typescript TypeScript theme={null}
      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"
      ```
    </CodeGroup>

    <Tip>
      `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.
    </Tip>

    ### 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` |
  </Step>

  <Step title="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.

    <CodeGroup>
      ```python Python theme={null}
      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'"]
      ```

      ```typescript TypeScript theme={null}
      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));
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

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

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

```python theme={null}
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 :

<CodeGroup>
  ```python Python theme={null}
  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")
  ```

  ```typescript TypeScript theme={null}
  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`);
  }
  ```
</CodeGroup>

## Prochaines étapes

* [Vue d'ensemble CLPI](/concepts/clpi) -- Couche de gouvernance : application des politiques, récupération de la confiance, ancrage on-chain
* [API Policy](/api-reference/policy-overview) -- Gestion programmatique des politiques pour les intégrations SDK
* [API Reclassification](/api-reference/reclassification-overview) -- Reclassification des violations et récupération du score de confiance
* [Spécification AAP](/protocols/aap/specification) -- Détails complets du protocole pour les implémenteurs
* [Spécification AIP](/protocols/aip/specification) -- Détails du protocole d'intégrité
* [Limitations](/protocols/aap/limitations) -- Ce qu'AAP peut et ne peut pas garantir
* [Modèle de sécurité](/protocols/aap/security) -- Modèle de menace et surfaces d'attaque
* [Intégration A2A](/protocols/aap/a2a-integration) -- Ajouter AAP aux flux de travail d'agents A2A
* [Migration MCP](/protocols/aap/mcp-migration) -- Ajouter le traçage d'alignement aux outils MCP


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