TrustLens overview

import { Aside } from “@astrojs/starlight/components”;

Alquimia TrustLens is an optional evaluation service that consumes signed context.persistence.v1 webhooks from alquimia-runtime and runs Gaussia benchmarks against agent conversations. It is configured through Alquimia Studio and exposes Prometheus metrics that Studio renders in the Agent Humanity view.

TrustLens is a secondary observability tool, not a core runtime component. You only need it when you want automated conversation quality evaluation and benchmark dashboards in Studio.

What TrustLens does

TrustLens receives runtime events, reconstructs conversation sessions, runs selected benchmarks in background workers, and persists jobs and results in PostgreSQL. Studio reads evaluation metrics from Prometheus.

Alquimia Runtime
      |
      | signed context.persistence.v1 webhook
      v
  TrustLens <---- Studio
      |          configuration API
      |
      +---- Vault
      |     model secrets
      v
  PostgreSQL
  config + jobs + results
      |
      v
  GET /metrics <---- Prometheus
                         |
                         v
                       Studio

Benchmarks

TrustLens runs single-agent Gaussia benchmarks. The default set is humanity, context, and conversational. Once a session reaches five interactions, bias and toxicity are added automatically unless explicitly disabled.

Benchmark	Description	Model dependency
humanity	Emotional characteristics in assistant responses.	None
context	Whether responses remain aware of conversation context.	Judge model
conversational	Memory, language, quality, quantity, relation, manner, and sensibleness.	Judge model
bias	Response disparities across protected attributes.	Guardian model
toxicity	Toxicity distribution and clustering indicators.	Local evaluation

Judge and guardian models are selected from Studio Model Connections. TrustLens resolves their Vault secret references at evaluation time.

Configuration endpoints

Method	Path	Purpose
GET	/config	Read TrustLens configuration for an agentspace and optional assistant.
PUT	/config	Save configuration and create, update, or pause the Runtime webhook.
POST	/config/disable	Disable TrustLens and pause the Runtime webhook.
POST	/webhooks/runtime	Accept and verify a signed Runtime event. Returns 202.
GET	/analytics/summary	Job counts and average benchmark scores.
GET	/analytics/evaluations	Paginated evaluation jobs and results.
GET	/metrics	Prometheus exposition endpoint.
GET	/health/readiness	Service readiness check.

Interactive OpenAPI documentation is available at /docs.

Key environment variables

Variable	Description
DATABASE_URL	PostgreSQL connection for configuration, jobs, and results.
TRUSTLENS_API_TOKEN	Bearer token used by Studio for the private configuration API.
TRUSTLENS_RUNTIME_BASE_URL	Runtime base URL for webhook subscription management.
TRUSTLENS_RUNTIME_API_TOKEN	Runtime API token for managing webhook subscriptions.
TRUSTLENS_WEBHOOK_URL	Private URL Runtime calls, e.g. http://trustlens.railway.internal:8080/webhooks/runtime.
TRUSTLENS_WEBHOOK_SIGNING_KEY	Shared 64-character hex HMAC key for webhook verification.
VAULT_ADDR / VAULT_TOKEN	Vault server and token for resolving model credentials.
OTEL_COLLECTOR_ENDPOINT*	Optional OTLP endpoints for metrics, traces, and logs.

Deployment notes

• TrustLens needs a private PostgreSQL service and access to the Runtime webhook API.
• Prometheus must scrape /metrics so Studio can display Agent Humanity charts.
• In Railway, deploy TrustLens as a private service and use /health/readiness as the health check path.

Next steps

• Observability concepts — how metrics, traces, and logs correlate across the platform.
• Studio overview — configuring TrustLens from the Studio UI.
• Runtime configuration reference — runtime webhook and telemetry settings.