Integración SDK directa

Usa los SDK de AAP y AIP para añadir verificación de alineamiento y comprobación de integridad directamente al código de tu aplicación. Esto te da control total sobre cuándo se generan las trazas, cómo se ejecutan las comprobaciones de integridad y qué sucede ante las violaciones. Para las funciones de gobernanza (aplicación de políticas, reclasificación de violaciones, recuperación de confianza), usa la API Policy y la API Reclassification junto con los SDK.

Instalación

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

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

Definir una tarjeta de alineamiento

Una tarjeta de alineamiento declara la identidad de tu agente, sus valores, sus límites de autonomía y sus compromisos de auditoría. Cada traza y comprobación de integridad se verifica frente a esta tarjeta.

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 tarjeta de alineamiento es el fundamento de ambos protocolos. Defínela una vez y úsala para la verificación AAP, la comprobación de integridad AIP y las comprobaciones de coherencia de valores.

Generar AP-Traces a partir de las acciones del agente

Cada decisión importante que tome tu agente debe producir una AP-Trace. La traza registra la acción tomada, las alternativas consideradas, el razonamiento aplicado y si se evaluó una escalada.

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 verificación comprueba action.name contra bounded_actions, no action.type. Ambos campos tienen propósitos distintos: type es una categoría semántica; name es el identificador de operación específico que se compara con la lista bounded_actions de la tarjeta.

Verificar las trazas frente a la tarjeta

La verificación comprueba si el comportamiento del agente (registrado en la traza) es coherente con su alineamiento declarado (la tarjeta). Devuelve comprobaciones estructurales, una puntuación de similitud y cualquier violación o advertencia.

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}`);
}

El similarity_score (de 0.0 a 1.0) mide cuán semánticamente similar es el comportamiento de la traza al alineamiento declarado. Una traza puede pasar todas las comprobaciones estructurales y aun así recibir una advertencia low_behavioral_similarity si la puntuación cae por debajo de 0.50. Consulta la calibración para saber cómo se derivaron los umbrales.

Añadir puntos de control de integridad

La comprobación de integridad AIP analiza los bloques de pensamiento del LLM por turno para detectar inyección de prompt, deriva de valores y manipulación. Cada comprobación produce un veredicto: clear, review_needed o boundary_violation.

AIP usa por defecto el modo fail-open. Si el LLM de análisis es inaccesible, las comprobaciones de integridad pasarán silenciosamente. Para los despliegues en producción que manejan operaciones sensibles, define failure_policy: { mode: "fail_closed" } en tu configuración 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"

Correspondencia veredicto → acción

Veredicto	Continuar	Acción recomendada
`clear`	Sí	`continue`
`review_needed`	Sí	`log_and_continue`
`boundary_violation`	No	`pause_for_review` o `deny_and_escalate`

Comprobar la coherencia de valores

Antes de que tu agente colabore con otro agente, verifica que sus valores sean compatibles. La comprobación de coherencia compara los valores declarados y detecta conflictos.

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));
}

Rastreo automático con decoradores (Python)

El SDK de Python de AAP proporciona decoradores para la generación automática de trazas:

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"],
    )

Detección de deriva

Monitorea tu agente para detectar deriva de comportamiento a lo largo del tiempo:

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`);
}

Próximos pasos

Descripción general de CLPI — Capa de gobernanza: aplicación de políticas, recuperación de confianza, anclaje on-chain
API Policy — Gestión programática de políticas para integraciones SDK
API Reclassification — Reclasificación de violaciones y recuperación de la puntuación de confianza
Especificación AAP — Detalles completos del protocolo para implementadores
Especificación AIP — Detalles del protocolo de integridad
Limitaciones — Qué puede y qué no puede garantizar AAP
Modelo de seguridad — Modelo de amenaza y superficies de ataque
Integración A2A — Añadir AAP a los flujos de trabajo de agentes A2A
Migración MCP — Añadir rastreo de alineamiento a las herramientas MCP

Inicio rápido

Integración SDK Directo

Integración SDK directa

Instalación

Correspondencia veredicto → acción

Rastreo automático con decoradores (Python)

Detección de deriva

Próximos pasos

​Integración SDK directa

​Instalación

​Correspondencia veredicto → acción

​Rastreo automático con decoradores (Python)

​Detección de deriva

​Próximos pasos

Integración SDK directa

Instalación

Correspondencia veredicto → acción

Rastreo automático con decoradores (Python)

Detección de deriva

Próximos pasos