AgentTrust Docs

Overview

Every agent execution flows through a governance pipeline: the SDK captures the agent's input and output, sends an execution envelope to the gateway, and the gateway returns a decision that determines whether the output is approved, retried, escalated, or blocked.

Why It Matters

Understanding the pipeline helps you interpret validation results, configure policy packs, and debug unexpected block or escalate decisions.

Prerequisites

Introduction
An agent function or framework integration in place

Step-by-Step Guide

1. Agent executes

Your agent runs normally — calling an LLM, tools, or other agents.

2. SDK captures the envelope

@harness runs this twice — once as a pre-check before your function body executes, and once as a post-check after it returns. AgentTrustClient.validate() and auto_instrument() run it once, after the fact.

The SDK collects:

agent_id — unique agent identifier
request — user and input text
execution — model, tools, latency, token counts
output — structured agent response
framework — LangGraph, CrewAI, Custom, etc.
parent_envelope_id — for multi-agent trust chains (optional)

3. Gateway validates (fast path)

Request → ValidationEngine → ConfidenceEngine → RiskEngine → DecisionEngine → Response
                ↓                                      ↓
           Audit Store                            Review Queue (if needed)
                                                      ↓
                                              LLM Judge (async, Enterprise)

ValidationEngine runs 6+ deterministic checks in <20ms with zero LLM calls.

ConfidenceEngine computes a weighted score from 7 signals: schema, tool trust, policy, consistency, evidence, judge (if available), historical reliability.

RiskEngine applies 4 factors to produce a risk tier: low, medium, high, critical.

DecisionEngine maps validation + confidence + risk to a governance outcome.

4. SDK enforces the decision

Outcome	Default SDK behavior
`approve`	Return output to caller
`retry`	Return output; log retry recommendation
`request_evidence`	Return output; item added to review queue
`escalate`	Return output or raise based on config; review queue
`block`	Raise `BlockedError` (when `block_on_block=True`)

5. Audit record persisted

Every execution is stored in the append-only audit ledger with content hashes. Enterprise tier adds hash-chain integrity verification.

Examples

OSS mode (no gateway):

Without an API key, client.validate() performs in-process schema validation only — no HTTP call. Note this short-circuit applies to validate() only: @harness calls pre_check() and post_check(), which have no OSS branch and always issue HTTP requests. Point @harness at a reachable gateway (embed_gateway() is the easy one) even on OSS.

Full pipeline response:

All scores are on a 0–100 scale, and confidence lives inside validation — there is no top-level result.confidence.

result = client.validate(agent_id="faq-agent", user="bob", input="...", output={...})
print(result.validation.schema_score)       # 0–100
print(result.validation.final_confidence)   # 0–100 weighted confidence
print(result.validation.failures)           # list[str]
print(result.risk.tier)                     # low | medium | high | critical
print(result.risk.score)                    # 0–100
print(result.decision.outcome)              # approve | block | ...
print(result.decision.reason)               # str
print(result.envelope_id)                   # audit record ID

Best Practices

Set meaningful agent_id values — they drive reliability metrics and policy routing
Pass parent_envelope_id in multi-agent pipelines for trust chain enforcement
Include tools_called in execution metadata for tool-trust checks (the field is plural)
Truncate or redact PII in inputs before submission

Common Mistakes

Submitting unstructured string output instead of a dict (schema check fails)
Omitting framework (it defaults to REST, not Custom, which skews analytics)
Assuming retry outcome automatically re-runs the agent (SDK does not re-invoke)

Troubleshooting

Symptom	Likely cause
Low confidence despite good output	Missing tool trust metadata or grounding evidence
Unexpected `block`	Adversarial check failed or policy pack rule triggered
`pending` outcome	The decision engine was tier-gated off (OSS tier, or a key without `auto_decision`) — not an in-flight judge. Run `agentrust whoami`.

How It Works