> ## 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.
# Integración SDK Directo
> Integra la verificación de alineamiento, la comprobación de integridad y la gobernanza de políticas directamente en tu aplicación
# 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
```bash Python theme={null}
pip install agent-alignment-protocol agent-integrity-proto
```
```bash TypeScript theme={null}
npm install @mnemom/agent-alignment-protocol @mnemom/agent-integrity-protocol
```
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.
```python Python theme={null}
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()
```
```typescript TypeScript theme={null}
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.
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.
```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',
},
};
```
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.
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.
```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}`);
}
```
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.
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.
```python Python theme={null}
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"
```
```typescript TypeScript theme={null}
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` |
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.
```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));
}
```
## Rastreo automático con decoradores (Python)
El SDK de Python de AAP proporciona decoradores para la generación automática de trazas:
```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"],
)
```
## Detección de deriva
Monitorea tu agente para detectar deriva de comportamiento a lo largo del tiempo:
```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`);
}
```
## 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