Trust-Based Agent Architecture for Reliable AI Systems
"Errors are acceptable. Lies are not."
AI agents fail trust in predictable, dangerous ways:
| Failure Mode | What Happens | Real Impact |
|---|---|---|
| Silent Fallbacks | Service fails, agent quietly uses backup | Wrong model runs for months undetected |
| Unverified Claims | Agent says "done" without proof | Broken code reaches production |
| Fabricated Data | Agent fills knowledge gaps with guesses | Decisions made on hallucinated facts |
| Corner Cutting | Agent skips "tedious" validation steps | Edge cases crash in production |
| No Audit Trail | No record of what agent actually did | Debugging becomes guesswork |
Code claimed to use LegalBERT for months
LegalBERT was never actually deployed
System silently fell back to a different model
ML pipeline operated as a facade
Nobody verified the actual model running
This wasn't an error. It was a lie the system told through silence.
Veritas makes lying structurally difficult through three enforcement layers:
┌─────────────────────────────────────────────────────────────────┐
│ LAYER 3: AUDIT │
│ Catches what slips through - spot-checks and reviews │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 2: WORKFLOW GATES │
│ No proof = No progress - tasks blocked without evidence │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 1: PROTOCOL-EMBEDDED │
│ Makes honesty the path of least resistance │
└─────────────────────────────────────────────────────────────────┘
Key Principle: Trust is earned through consistent behavior, not granted through configuration.
pip install veritas-frameworkOr from source:
git clone https://github.com/RBKunnela/veritas-framework.git
cd veritas-framework
pip install -e ".[dev]"from veritas import TrustContext, Evidence
from veritas.layers import WorkflowGate, GateRequirement
# Create trust context for your agent
ctx = TrustContext(agent_id="my-agent")
# Add evidence for claims
evidence = ctx.add_evidence(
claim="API endpoint returns 200",
evidence_type="api_response",
content='{"status": "healthy"}',
verifiable_command="curl http://localhost:8000/health"
)
# Gate blocks progress without proof
gate = WorkflowGate(
name="dev_to_review",
requirements=[
GateRequirement(evidence_type="test_results", required=True),
GateRequirement(evidence_type="api_response", required=True),
]
)
# Transition fails without evidence
can_proceed = gate.can_transition(ctx.evidence) # True only with evidenceVeritas enforces five character traits that define trustworthy agents:
| Behavior | Rule | Enforcement |
|---|---|---|
| Verification Before Claim | Never say "done" without proof | @requires_verification decorator |
| Loud Failure | No silent fallbacks | Exceptions surfaced, logged, explained |
| Honest Uncertainty | "I don't know" is valid | Fabrication detection, uncertainty flags |
| Paper Trail | Every action documented | Automatic logging, evidence collection |
| Diligent Execution | No shortcuts, even when tedious | Spot-check audits, consistency validation |
from veritas.integrations.claude_code import ClaudeCodeTrustHook
hook = ClaudeCodeTrustHook(
enforce_verification=True,
require_evidence_on_done=True,
audit_tool_calls=True,
strict_mode=True
)
# Hook validates claims before allowing completionfrom veritas import AgentTrustMixin
class MyQAAgent(AgentTrustMixin):
def __init__(self):
self.init_trust("my-qa-agent", strict_mode=True)
async def run_tests(self, url: str):
self.start_trust_task("test-123", f"Testing {url}")
try:
results = await self._execute_tests(url)
self.add_test_evidence("Tests completed", results)
self.claim_completion("All tests pass") # Validated!
except Exception as e:
self.record_failure(e) # Loud failure
raise| Feature | Traditional Agents | Veritas Agents |
|---|---|---|
| Completion claims | Trusts agent's word | Requires proof |
| Service failures | Silent fallback | Loud, logged failure |
| Knowledge gaps | May fabricate | Admits uncertainty |
| Audit trail | Optional logging | Mandatory evidence |
| Task transitions | Status change | Gate with requirements |
Veritas implements a trust-building progression:
EDGE TASKS (Low Risk)
│
│ Success + Expertise + Transparency
↓
PERIPHERAL TASKS (Analysis, Suggestions)
│
│ Trust + Domain Knowledge
↓
ADJACENT TASKS (Recommendations, Drafts)
│
│ Reliability + Judgment
↓
CORE WORKFLOWS (Decisions, Execution)
"When we start by attacking the edges, we remind the people doing the work that their expertise is valuable."
Start with low-risk tasks. Earn trust. Graduate to core workflows.
See Agent Maturation Philosophy for the full framework.
- Core Concepts - Evidence, behaviors, context
- Layer 1: Protocol-Embedded - Verification decorators
- Layer 2: Workflow Gates - Task transition requirements
- Layer 3: Trust Audit - Spot-checks and reviews
- Integration Guide - Adding Veritas to your agents
- Agent Maturation - Trust-building philosophy
| Component | Status |
|---|---|
| Core Evidence System | ✅ Stable |
| Trust Behaviors | ✅ Stable |
| Workflow Gates | ✅ Stable |
| Audit Layer | ✅ Stable |
| Claude Code Integration | ✅ Stable |
| LangChain Integration | 🚧 Planned |
| CrewAI Integration | 🚧 Planned |
We welcome contributions! See CONTRIBUTING.md for guidelines.
Good First Issues:
- Add integration adapters for popular frameworks
- Improve documentation with examples
- Add more evidence validators
- Create tutorials and guides
MIT License - See LICENSE
If you use Veritas in research, please cite:
@software{veritas_framework,
title = {Veritas Framework: Trust-Based Agent Architecture},
author = {RBKunnela},
year = {2026},
url = {https://github.com/RBKunnela/veritas-framework}
}"Trust is earned in drops and lost in buckets."