Traces & Confidence Scoring

What is a trace?

A trace is a record of a single AI agent decision. Every time your agent responds to a user, calls a tool, or takes an action, you send a trace to Adjudon.

A trace contains three parts:

Field	Required	Description
inputContext	Yes	What the agent received — prompt, system prompt, context
outputDecision	Yes	What the agent did — response text, action taken, tool called
metadata	No	Optional context — model name, latency, user ID, session ID

Trace lifecycle

1. Ingested      → Received by POST /api/v1/traces
2. PII scrubbed  → Email, IBAN, credit card, SSN patterns removed
3. Confidence scored → 3-pillar triangulation (see below)
4. Policy evaluated → Rules checked against the trace
5. Stored        → Saved to MongoDB (Frankfurt)
6. Audit logged  → SHA-256 chain entry appended

If a webhook is configured, it fires asynchronously after step 5.

Confidence scoring

Adjudon assigns a confidence score (0.0–1.0) to every trace using 3-pillar triangulation:

Pillar 1 — Content analysis: Is the output coherent and relevant to the input? Does it answer the question asked? Are there signs of hallucination or off-topic responses?

Pillar 2 — Policy compliance: Does the output match any active policy rules? Policy matches reduce confidence and may directly trigger a flag or block.

Pillar 3 — Historical patterns: How does this trace compare to past decisions from this agent? Unusual deviations from baseline behavior reduce confidence.

The three pillars are combined into a single score. Thresholds are configurable per agent:

• Score ≥ threshold → approved
• Score < threshold → flagged (routed to Review Queue)
• Hard policy violation → blocked (regardless of score)

Trace statuses

Status	Meaning	Agent should...
approved	Confidence above threshold, no policy violations	Continue normally
flagged	Below threshold or soft policy match	Continue (but decision is under review)
blocked	Hard policy violation	Stop the action (if fail_mode="closed")
passthrough	Adjudon was unreachable	Continue normally — fail-open default

Schema versioning

Every trace includes a schemaVersion field (ISO date format). The current version is 2026-04-11.

Adjudon validates traces against version-specific rules. If you don't include a schemaVersion, Adjudon uses the latest version. To pin to a specific version, pass the X-Adjudon-Version header or the schemaVersion SDK parameter.

Older schema versions remain supported indefinitely — breaking changes never happen within a version.

Idempotency

To prevent duplicate traces (e.g. from retries), include an idempotency key:

result = client.trace(
    input_context={"prompt": "..."},
    output_decision={"action": "llm_response", "text": "..."},
    idempotency_key="request-id-123",
)

Or via HTTP header:

curl -X POST https://api.adjudon.com/api/v1/traces \
  -H "Idempotency-Key: request-id-123" \
  ...

Idempotency keys are scoped per organization. A duplicate key within 24 hours returns the cached response with a 409 status code. Your business logic should treat 409 as success.