Przepisy wdrożeniowe

Buduj z Attesto bez zgadywania.

Attesto najłatwiej wdrożyć, gdy najpierw wybierzesz powierzchnię dowodową: bezpośrednie zdarzenie SDK, stream Proofstream, przychodzący webhook, konektor, relay Local Vault albo workflow verifier-only. Ta strona mapuje te wybory na konkretne kroki implementacji.

Wybierz ścieżkę

Przepis: zarejestruj zdarzenie produkcyjne

Użyj tego, gdy aplikacja zna już decyzję lub akcję, która ma stać się evidence. Wysyłaj tylko z kodu server-side. Przechowuj system key w secret managerze, zachowuj idempotency keys między retry i loguj stabilne source references, które zespół może prześledzić.

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

Przepis: wspieraj Article 13 jedną linią i wygeneruj Article 12 report

Kiedy mówimy "Voldoe aan Artikel 13 met 1 regel code", oznacza to: dodaj jedną linię integracji Attesto, która zmienia workflow AI w evidence z receipt i verifier-ready materiał dla transparentności oraz instructions-for-use. Deterministyczne polecenie CLI pozostaje attesto report article12, ponieważ report wiąże techniczny logging trail z evidence w stylu Article 12. Wsparcie Article 13 zależy od tego, jak klient użyje tej evidence w dokumentacji, informacji dla użytkowników, oversight i interpretacji prawnej. Attesto zapewnia wsparcie dowodowe; nie certyfikuje samodzielnie zgodności prawnej.

Użyj dekoratora, gdy kontrolujesz granicę funkcji, attestedFetch, gdy kontrolujesz transport HTTP w TypeScript, oraz Inference Gateway, gdy potrzebujesz proxy neutralnego językowo i frameworkowo dla wywołań 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_..."))

Capture path może działać z system API key. Report path czyta tenant stream events, więc finalny report generuj z kontekstu tenant/operator albo przekaż tenant token do 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

Przepis: utwórz stream Proofstream

Użyj Proofstream, gdy kolejność ma znaczenie. Stream zwykle jest ograniczony do tenant, systemu, use case i policy. Każde zdarzenie otrzymuje sequence number oraz podpisany receipt. Późniejsze windows, checkpoints, witnesses, anchors i bundles budują na tej append-only sekwencji.

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)

Przepis: zweryfikuj evidence przed zaufaniem

Weryfikacja powinna być częścią workflow odbiorczego. Jeśli system otrzymuje Attesto receipt albo bundle, zweryfikuj go przed przyjęciem do pliku audytowego, data room, assurance report lub pakietu dla regulatora.

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

Raport niepowodzenia też jest użyteczną evidence. Pokazuje, czy obiekt był malformed, niekompletny, zmieniony, stale, bez witness quorum, z błędną signature, związany z niewłaściwym anchor albo zawierał fork evidence.

Przepis: odbieraj webhooks Attesto

Webhooks są do powiadomień. Nie zastępują weryfikacji. Zweryfikuj signature na raw request body, deduplikuj delivery ID, odpowiedz szybko, a potem pobierz lub zweryfikuj wskazany obiekt evidence w własnym workerze.

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

Przepis: bezpiecznie używaj konektorów

Connectors tłumaczą zmiany w systemach źródłowych na Attesto evidence. Używaj signed webhook connectors dla systemów własnych, konektorów GitHub/GitLab dla repository change references oraz S3/R2 commitments dla object evidence. Każdy connector musi mieć realne uwierzytelnienie, replay behavior, diagnostics i revocation.

Przepis: wdroż Local Vault przy krawędzi klienta

Local Vault jest dla środowisk enterprise, gdzie connector secrets, source attestations i outage spooling powinny pozostać po stronie klienta. Relayuje outbound do Attesto i opcjonalnie może działać jako customer witness w 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

• Przechowuj connector secrets lokalnie w formie zaszyfrowanej.
• Podpisuj source attestations przed relay.
• Spooluj, gdy sieć outbound jest niedostępna.
• Replay z trwałą idempotency, gdy łączność wróci.
• Udostępniaj witness status tenantowi i verifier bundle.

Przepis: kieruj wywołania AI przez Attesto Inference Gateway

Użyj gateway, gdy zespoły już wywołują APIs providerów OpenAI-compatible i chcą evidence bez przepisywania każdej aplikacji. Gateway przekazuje requests do skonfigurowanego providera i zapisuje commitments, receipt references oraz bezpieczną metadata. Raw prompts, completions, API keys i provider secrets zostają w procesie gateway i nie są zapisywane w 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

Używaj trybu commitments dla production evidence. Używaj none tylko wtedy, gdy deployment celowo wyłącza capture evidence dla konkretnego środowiska. Gateway domyślnie jest fail-open z ostrzeżeniami widocznymi dla operatora i fsynced dead-letter spool; dodaj --strict, gdy polityka wymaga utworzenia receipt przed kontynuacją upstream work. Monitoruj /healthz i /metrics na admin listener, i uruchamiaj attesto-gateway replay-spool po awariach.

Gateway attestation obejmuje OpenAI-compatible /v1/chat/completions, /v1/completions, /v1/embeddings i /v1/responses jako model-decision evidence. Nieznane upstream paths są proxied i zapisywane jako generyczne HTTP-call commitment events, zamiast być po cichu pomijane.

Przepis: udostępnij Attesto agent tools przez MCP

Attesto MCP server daje systemom agentic wąski, deterministyczny zestaw narzędzi: log action, get receipt, verify receipt offline, inspect stream head i check completeness. Nie jest to ogólna admin surface i odrzuca wartości wyglądające jak sekrety zanim staną się evidence payloads.

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

Trzymaj MCP credentials w secret store agent runtime. Nie przekazuj dashboard cookies, admin credentials, private keys, provider API keys ani raw customer secrets w argumentach narzędzi MCP.

Przepis: dodaj Attesto evidence do workflow n8n

Użyj Attesto n8n node, gdy workflow step powinien utworzyć evidence receipt. Action node loguje typed compliance events, pobiera receipts i weryfikuje receipts offline. Trigger node waliduje signed Attesto webhooks z timestamp tolerance zanim workflow pójdzie dalej.

npm install n8n-nodes-attesto

• Przechowuj Attesto credentials w n8n credentials, nie w workflow JSON.
• Używaj stabilnych workflow execution IDs jako source references.
• Weryfikuj incoming webhook signatures zanim rozgałęzisz logikę na podstawie ich treści.
• Zapisuj failure events dla odrzuconych lub niekompletnych automation steps.

Checklist rollout produkcyjnego