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

Estos inicios rápidos están disponibles en español (Español) y en francés (Français) — se han traducido seis páginas por idioma.

Instalación

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

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

--legacy-peer-deps es necesario en npm 7+ mientras @mnemom/agent-integrity-protocol 1.3.0 siga declarando una dependencia peer opcional sobre el paquete alignment-protocol 1.x; los dos SDK funcionan juntos en 2.0.0 / 1.3.0.

Definir una tarjeta de alineamiento

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

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',
  },
};

Los nombres de campos cambiaron en la forma de tarjeta unificada (AAP 2.0.0). aap_version ahora es card_version (anclado a una fecha); autonomy_envelope/AutonomyEnvelope ahora es autonomy/Autonomy; audit_commitment/AuditCommitment ahora es audit/Audit; autonomy_mode e integrity_mode son nuevos campos de primer nivel; principal.identifier es obligatorio siempre que principal.type no sea unspecified; y audit.queryable: true requiere audit.query_endpoint. Consulta la migración desde la forma de tarjeta heredada 0.5.0 para el mapeo completo.

La tarjeta de alineamiento es la base 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 significativa que tome tu agente debería producir una AP-Trace. La traza registra la acción tomada, las alternativas consideradas, el razonamiento aplicado, y si se evaluó la 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 compara action.name con bounded_actions, no action.type. Ambos campos sirven propósitos distintos: type es una categoría semántica; name es el identificador de operación específico que se verifica contra la lista bounded_actions de la tarjeta.

Verificar trazas contra 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 (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 pero 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 razonamiento del LLM por turno para detectar inyección de prompts, 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 no está disponible, las comprobaciones de integridad pasarán silenciosamente. Para despliegues en producción que manejan operaciones sensibles, define failure_policy: { mode: "fail_closed" } en tu configuración de AIP.

Un cliente se encarga de la extracción, la llamada al LLM y la contabilidad de puntos de control/ventanas por ti — pásale el cuerpo de respuesta crudo del proveedor, no una cadena de razonamiento pre-extraída. El card aquí es la forma de tarjeta mínima propia de AIP (card_id, values, autonomy_envelope) — un pequeño subconjunto de campos, mantenido separado del AlignmentCard de AAP completo que construiste en el Paso 1, ya que @mnemom/agent-alignment-protocol es solo una dependencia peer opcional para 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() ejecuta el pipeline completo en cada llamada: extraer el bloque de razonamiento del proveedor detectado, llamar al LLM de análisis, parsear el veredicto, actualizar la ventana deslizante y detectar la deriva. No hay una función de bajo nivel separada de “simplemente parsear esta respuesta de análisis” en la API pública — check() es el único punto de entrada.

Mapeo de veredicto a acción

Veredicto	Proceed	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

Monitoriza a tu agente en busca de 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 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 no puede garantizar AAP
Modelo de seguridad — Modelo de amenazas y superficies de ataque
Integración A2A — Añadir AAP a flujos de trabajo de agentes A2A
Migración MCP — Añadir rastreo de alineamiento a herramientas MCP

Inicio rápido

Integración SDK Directo

Integración SDK directa

Instalación

Mapeo de veredicto a acción

Rastreo automático con decoradores (Python)

Detección de deriva

Próximos pasos

​Integración SDK directa

​Instalación

​Mapeo de veredicto a acción

​Rastreo automático con decoradores (Python)

​Detección de deriva

​Próximos pasos

Integración SDK directa

Instalación

Mapeo de veredicto a acción

Rastreo automático con decoradores (Python)

Detección de deriva

Próximos pasos