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

The SDK (via @harness, auto_instrument(), or AgentTrustClient) 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, the SDK performs in-process schema validation only — no HTTP call.

Full pipeline response:

result = client.validate(agent_id="faq-agent", user="bob", input="...", output={...})
print(result.validation.score)      # 0.0–1.0
print(result.confidence.score)      # 0.0–1.0
print(result.risk.tier)             # low | medium | high | critical
print(result.decision.outcome)      # approve | block | ...
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 tool_calls in execution metadata for tool trust checks
Truncate or redact PII in inputs before submission

Common Mistakes

Submitting unstructured string output instead of a dict (schema check fails)
Omitting framework field (defaults to Custom but affects 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	Async judge not yet complete; check back via audit API

How It Works