Recetas de implementación

Construya con Attesto sin adivinar.

Attesto se adopta mejor cuando primero se elige la superficie de evidencia: un evento directo por SDK, un stream Proofstream, un webhook entrante, un conector, un relay Local Vault o un flujo verifier-only. Esta página conecta esas opciones con pasos concretos.

Elija un camino

Receta: registrar un evento de producción

Use esto cuando su aplicación ya conoce la decisión o acción que debe convertirse en evidencia. Envíe solo desde código del servidor. Mantenga la system key en su gestor de secretos, preserve idempotency keys entre retries y registre source references estables que su equipo pueda rastrear.

pip install attesto

python - <<'PY'
import os
from datetime import UTC, datetime
from attesto import AttestoClient

attesto = AttestoClient(api_key=os.environ["ATTESTO_API_KEY"])
ack = attesto.log_event(
    type="ai.decision",
    status="verified",
    ts=datetime.now(UTC),
    payload={
        "decision": "manual_review",
        "score": 91,
        "policy_id": "policy-2026-01",
        "model": "risk-service-v4"
    },
)
print(ack.id)
PY

Receta: soportar Article 13 con una línea y generar el Article 12 report

Cuando decimos "Voldoe aan Artikel 13 met 1 regel code", queremos decir: añadir una línea de integración de Attesto que convierte un workflow de AI en evidencia receipt-backed y verifier-ready para transparencia e instrucciones de uso. El comando CLI determinista sigue siendo attesto report article12, porque el report conecta la traza técnica de logging con evidencia de logging estilo Article 12. El soporte Article 13 depende de cómo el cliente use esa evidencia en documentación, información para usuarios, oversight e interpretación legal. Attesto proporciona soporte de evidencia; no certifica por sí mismo el cumplimiento legal.

Use el decorador cuando controla el límite de la función, attestedFetch cuando controla el transporte HTTP en TypeScript, y el Inference Gateway cuando quiere un proxy neutral en lenguaje y framework para llamadas OpenAI-compatible.

from attesto import AttestoClient, AttestoV2Client, attest, article12
import os

capture = AttestoClient(api_key=os.environ["ATTESTO_API_KEY"])

@attest(capture, stream_id="str_...")
def decide(payload: dict) -> dict:
    return {"decision": "manual_review", "policy_id": "policy-2026-01"}

result = decide({"case_id": "case-2026-0001"})
operator = AttestoV2Client.with_bearer_token(os.environ["ATTESTO_TENANT_TOKEN"])
print(article12(operator, "str_..."))

La ruta de captura puede ejecutarse con una system API key. La ruta de report lee tenant stream events, así que genere el report final desde un contexto tenant/operator o pase un tenant token a la CLI.

import { AttestoV2Client, attestedFetch } from "@attesto/sdk";

const attesto = new AttestoV2Client({ apiKey: process.env.ATTESTO_API_KEY! });
const fetchWithEvidence = attestedFetch(attesto, { streamId: "str_...", strict: true });

attesto --token-env ATTESTO_TENANT_TOKEN \
  report article12 --stream str_... --output report.md

Receta: crear un stream Proofstream

Use Proofstream cuando el orden importa. Un stream normalmente se limita a tenant, sistema, caso de uso y policy. Cada evento recibe un sequence number y un receipt firmado. Luego windows, checkpoints, witnesses, anchors y bundles construyen sobre esa secuencia append-only.

from attesto import AttestoV2Client
from datetime import UTC, datetime
import os

with AttestoV2Client(api_key=os.environ["ATTESTO_API_KEY"]) as attesto:
    stream = attesto.create_stream(
        use_case="ai-decision-history",
        policy_id="policy-2026-01",
        metadata={"owner": "risk-platform", "environment": "production"},
    )
    receipt = attesto.log_event(
        stream_id=stream.stream_id,
        source_ref="case-2026-0001:decision-1",
        event_type="ai.decision",
        occurred_at=datetime.now(UTC),
        payload={"decision": "manual_review", "score": 91},
    )
    print(receipt.stream_event_id, receipt.seq_no)

Receta: verificar evidencia antes de confiar

La verificación debe formar parte del flujo receptor. Si su sistema recibe un Attesto receipt o bundle, verifíquelo antes de aceptarlo en un archivo de auditoría, data room, informe de assurance o paquete regulatorio.

curl -X POST https://verify.attesto.eu/v2/verify \
  -H "Content-Type: application/json" \
  --data-binary @attesto-bundle.json

attesto --json bundles verify \
  --file ./attesto-bundle.json > ./verification-report.json

Un informe fallido también es evidencia útil. Indica si el objeto estaba malformed, incompleto, cambiado, stale, sin witness quorum, con firma incorrecta, ligado a un anchor equivocado o con fork evidence.

Receta: recibir webhooks de Attesto

Los webhooks son para notificaciones. No reemplazan la verificación. Verifique la firma sobre el raw request body, deduplique el delivery ID, responda rápido y obtenga o verifique el objeto de evidencia referenciado en su propio worker.

import crypto from "node:crypto";

function verifyAttestoWebhook({ rawBody, timestamp, signature, secret }) {
  const message = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(message)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"));
}

Receta: usar conectores de forma segura

Los conectores traducen cambios de sistemas fuente a evidencia Attesto. Use signed webhook connectors para sistemas personalizados, conectores GitHub/GitLab para repository change references y S3/R2 commitments para object evidence. Cada conector necesita autenticación real, comportamiento de replay, diagnostics y revocation.

Receta: desplegar Local Vault en el edge del cliente

Local Vault es para entornos enterprise donde connector secrets, source attestations y outage spooling deben quedarse del lado del cliente. Hace relay outbound a Attesto y puede actuar opcionalmente como customer witness en una quorum policy.

pipx install attesto-local-vault

export ATTESTO_LOCAL_VAULT_SPOOL_DB=/var/lib/attesto/local-vault.sqlite3
export ATTESTO_LOCAL_VAULT_INSTALLATION_ID="$ATTESTO_LOCAL_VAULT_INSTALLATION_ID"
export ATTESTO_LOCAL_VAULT_RELAY_URL="https://verify.attesto.eu/v2/local-vault/installations/$ATTESTO_LOCAL_VAULT_INSTALLATION_ID/events"

attesto-local-vault drain-loop

• Guardar connector secrets cifrados localmente.
• Firmar source attestations antes del relay.
• Spool cuando la red saliente no esté disponible.
• Reproducir con idempotency estable cuando vuelva la conectividad.
• Exponer estado witness al tenant y al verifier bundle.

Receta: enrutar llamadas AI por Attesto Inference Gateway

Use el gateway cuando los equipos ya llaman APIs de proveedor OpenAI-compatible y quieren evidence sin reescribir cada aplicación. El gateway reenvía requests al proveedor configurado y registra commitments, receipt references y metadata segura. Raw prompts, completions, API keys y provider secrets permanecen en el proceso gateway y no se escriben en Attesto.

export ATTESTO_API_KEY="$ATTESTO_SYSTEM_KEY"
export ATTESTO_BASE_URL=https://verify.attesto.eu
export OPENAI_BASE_URL=http://localhost:8765/v1

attesto-gateway --listen 127.0.0.1:8765 \
  --admin-listen 127.0.0.1:8766 \
  --attesto-base-url "$ATTESTO_BASE_URL" \
  --upstream "$AI_PROVIDER_BASE_URL" \
  --stream-id "$ATTESTO_STREAM_ID" \
  --capture commitments

Use el modo commitments para production evidence. Use none solo cuando un deployment desactiva intencionalmente la captura de evidence para un entorno concreto. El gateway es fail-open por defecto con advertencias visibles para operadores y un dead-letter spool fsync; añade --strict cuando la política exige que la creación del receipt funcione antes de continuar al upstream. Monitoriza /healthz y /metrics en el admin listener, y ejecuta attesto-gateway replay-spool después de incidencias.

El gateway atestigua llamadas OpenAI-compatible /v1/chat/completions, /v1/completions, /v1/embeddings y /v1/responses como evidencia de model decision. Las rutas upstream desconocidas se proxifican y se registran como eventos genéricos de commitment HTTP-call, en lugar de descartarse silenciosamente.

Receta: exponer Attesto a agent tools mediante MCP

El servidor MCP de Attesto da a sistemas agentic un conjunto estrecho y determinista de herramientas: registrar una acción, obtener un receipt, verificar un receipt offline, inspeccionar un stream head y comprobar completeness. No es una superficie admin general y rechaza valores con aspecto de secreto antes de que se conviertan en payloads de evidence.

pip install attesto-mcp

{
  "mcpServers": {
    "attesto": {
      "command": "attesto-mcp",
      "env": {
        "ATTESTO_API_KEY": "${ATTESTO_SYSTEM_KEY}",
        "ATTESTO_BASE_URL": "https://verify.attesto.eu"
      }
    }
  }
}

export ATTESTO_BASE_URL=https://verify.attesto.eu
export ATTESTO_API_KEY="$ATTESTO_SYSTEM_KEY"

attesto-mcp --stdio

Mantenga las credenciales MCP en el secret store del agent runtime. No pase dashboard cookies, admin credentials, private keys, provider API keys ni raw customer secrets por argumentos de herramientas MCP.

Receta: añadir Attesto evidence a workflows n8n

Use el nodo Attesto n8n cuando un workflow step debe producir un evidence receipt. El action node registra typed compliance events, obtiene receipts y verifica receipts offline. El trigger node valida signed Attesto webhooks con timestamp tolerance antes de continuar el workflow.

npm install n8n-nodes-attesto

• Guarde las credenciales Attesto en n8n credentials, no en workflow JSON.
• Use workflow execution IDs estables como source references.
• Verifique incoming webhook signatures antes de ramificar según su contenido.
• Registre failure events para automation steps rechazados o incompletos.

Checklist de rollout a producción