Attesto

Developer surfaces

Gateway, MCP, OTel et n8n

Les SDK principaux d'Attesto couvrent l'intégration directe dans les applications. Gateway, MCP, OpenTelemetry et n8n couvrent les systèmes autour des applications : proxy de modèles, outils d'agents, traces d'observabilité et automatisation de workflows. Chaque surface doit émettre une vraie preuve Proofstream, respecter les timestamps source et garder les secrets hors des payloads, receipts, bundles, logs et code navigateur.

Scope

Cette page s'adresse aux développeurs et opérateurs techniques qui intègrent Attesto dans des AI gateways, agent hosts, telemetry pipelines et outils d'automatisation. Elle ne documente pas les opérations internes de staff et ne remplace pas les manuels SDK, API, connecteurs ou Local Vault. Utilisez-la pour choisir la bonne surface et comprendre quelle preuve chacune produit.

Quand utiliser chaque surface

SurfaceÀ utiliser quandProduitResponsable principal
Inference GatewayVous voulez capturer des appels de modèles compatibles OpenAI sans modifier chaque application.Commitments request/response, métadonnées de politique, evidence de routage modèle et receipts.Équipe plateforme ou AI engineering.
MCP serverDes agent hosts ont besoin d'outils déterministes pour journaliser des events, vérifier des receipts ou construire des bundles.Evidence de tool calls, stream events et résultats de vérification de receipts.Équipe agent platform ou developer tooling.
OpenTelemetry bridgeVous émettez déjà des spans et voulez transformer certaines traces en evidence Attesto.Span commitments, trace/span source references et service metadata receipts.Équipe observability ou plateforme.
n8n nodeL'automatisation de workflows exige des step receipts vérifiables et la vérification de webhooks signés.Workflow-step events, source references, receipt IDs et résultats de vérification.Équipe automation ou operations.

Inference Gateway

L'Attesto Inference Gateway est un proxy serveur pour les appels de modèles compatibles OpenAI. Les applications envoient les requêtes à la gateway ; la gateway les transmet au provider upstream configuré et écrit l'evidence Attesto avant de renvoyer la réponse du provider. Utilisez-la lorsque les équipes ne peuvent pas ajouter des appels SDK dans chaque application, ou lorsqu'une politique centrale et un routage modèle sont nécessaires. 

export ATTESTO_API_KEY="$ATTESTO_SYSTEM_KEY"
export OPENAI_BASE_URL=http://127.0.0.1:8765/v1

attesto-gateway --listen 127.0.0.1:8765 \
  --admin-listen 127.0.0.1:8766 \
  --attesto-base-url https://verify.attesto.eu \
  --upstream https://api.openai.com/v1 \
  --stream-id "$ATTESTO_STREAM_ID" \
  --capture commitments
curl -sS "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer ${PROVIDER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"Summarize this policy"}]}'

MCP server

Le serveur MCP d'Attesto expose un ensemble restreint d'outils Attesto déterministes aux agent hosts compatibles MCP. La surface d'outils actuelle est log_action, get_receipt, verify_receipt, get_stream_head et verify_completeness. Le serveur journalise des actions, récupère des receipts, vérifie des receipts offline, inspecte les stream heads et prouve qu'une plage de séquence est gap-free sans donner à l'agent des credentials backend larges. Le serveur MCP doit tourner côté serveur dans l'environnement runtime de l'agent. Il ne contient aucun modèle AI, aucun import d'AI vendor et aucune logique de décision cachée ; c'est un wrapper d'outils déterministe au-dessus du SDK Attesto. 

pip install attesto-mcp
{
  "mcpServers": {
    "attesto": {
      "command": "attesto-mcp",
      "args": ["--stdio"],
      "env": {
        "ATTESTO_BASE_URL": "https://verify.attesto.eu",
        "ATTESTO_API_KEY": "${ATTESTO_API_KEY}",
        "ATTESTO_STREAM_ID": "${ATTESTO_STREAM_ID}"
      }
    }
  }
}
attesto-mcp --stdio

OpenTelemetry bridge

L'OpenTelemetry bridge transforme des spans sélectionnés en events Attesto. Il est utile lorsque la source de vérité est déjà une pipeline de traces : spans de model gateway, d'évaluation de policy, de sync connecteur ou de gestion d'incident. Le bridge doit filtrer fortement ; n'envoyez pas chaque span par défaut. 

pip install attesto opentelemetry-sdk
import os
from attesto import AttestoClient
from attesto.otel import AttestoSpanProcessor
from opentelemetry.sdk.trace import TracerProvider

provider = TracerProvider()
provider.add_span_processor(
    AttestoSpanProcessor(
        client=AttestoClient(api_key=os.environ["ATTESTO_API_KEY"]),
        stream_id=os.environ["ATTESTO_STREAM_ID"],
    )
)

n8n node

Le node Attesto n8n est destiné aux automatisations de workflows qui exigent une step evidence vérifiable. Utilisez-le pour les workflows d'approbation, handoffs de connecteurs, triage d'incidents, policy checks et automatisations côté client où un auditeur doit pouvoir voir plus tard ce qui s'est passé et quand. 

npm install n8n-nodes-attesto

Evidence model

Les quatre surfaces doivent émettre l'evidence avec la même sémantique Proofstream que les SDKs. Une requête gateway, un MCP tool call, un span OTel ou une étape n8n n'est pas un cas spécial : c'est un source event avec source reference, timestamp, normalized commitment, receipt et inclusion optionnelle ultérieure dans des windows, checkpoints, witnesses et anchors.

ChampComportement requis
source_system_idIdentifier la gateway, l'agent host, le telemetry service ou l'instance n8n.
source_refClé d'idempotency stable comme request id, tool call id, trace/span id ou workflow execution id.
source_timeTimestamp source original avec timezone ou offset.
payload_commitmentEngager les métadonnées de payload normalisées sans stocker de secrets provider.
receiptRenvoyer ou stocker le receipt id afin que l'event puisse être vérifié plus tard.

Security boundaries

Operations

Traitez ces surfaces comme des intégrations de production. Elles ont besoin de health checks, retry policy, rate-limit handling, idempotency, validation du source time et états d'échec observables. Une surface peut être installée depuis un package registry, mais elle n'est production-ready pour un tenant que lorsqu'elle possède une vraie API key Attesto, un vrai stream et une canary receipt/verify réussie.

CheckRésultat attendu
Install smokeLe package s'installe depuis le registry officiel sans source maps ni source leaks.
Receipt canaryUn vrai event est journalisé et le receipt se vérifie.
Retry canaryUn source_ref répété produit un comportement replay/idempotent, pas un historique dupliqué.
Secret scanAucune tenant key, provider key, prompt secret, trace secret ou credential de workflow n'apparaît dans les logs ou bundles.

Failure modes

FailureSignificationRéponse
Attesto unavailableLa surface ne peut pas obtenir de receipt.Fail closed lorsque la politique exige l'evidence ; sinon marquer l'exécution comme missing evidence.
Provider unavailableLe service upstream model/tool/workflow a échoué.Journaliser des métadonnées d'échec sûres si la politique l'autorise ; ne pas inventer un success event.
Invalid source timeLe timestamp source est absent ou malformed.Rejeter ou normaliser selon la tenant policy et enregistrer séparément le receive time.
Secret detectedUn payload ou attribute semble contenir du secret material.Bloquer l'émission, rediger à la source et effectuer une rotation si la fuite est confirmée.

Rollout checklist