Saltar al contenido principal

​
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
1

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()
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.
2

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()
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.
3

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

Añadir puntos de control de integridad

La comprobación de integridad AIP analiza los bloques de pensamiento del LLM en tiempo real 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"

​
Correspondencia veredicto → acción

VeredictoContinuarAcción recomendada
clearSícontinue
review_neededSílog_and_continue
boundary_violationNopause_for_review o deny_and_escalate
5

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'"]

​
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.drift_direction}")
    print(f"  Similarity score: {alert.similarity_score}")
    print(f"  Sustained for {alert.sustained_traces} traces")

​
Próximos pasos