AgentTrust Docs

Overview

POST /v1/runtime/validate is the primary gateway endpoint. It runs the full governance pipeline and returns validation scores, risk tier, and governance decision.

Why It Matters

Every SDK integration ultimately calls this endpoint. Understanding the request/response schema enables custom integrations and debugging.

Prerequisites

Running gateway
Auth token (when enabled)

Step-by-Step Guide

Request

POST /v1/runtime/validate
Content-Type: application/json
X-AgentTrust-Token: at_team_your_key

{
  "agent_id": "payment-agent",
  "framework": "Custom",
  "version": "1.0.0",
  "parent_envelope_id": null,
  "request": {
    "user": "alice",
    "input": "Transfer $500 to Bob"
  },
  "execution": {
    "model": "gpt-4o",
    "latency_ms": 1200,
    "tokens_in": 150,
    "tokens_out": 80,
    "tool_calls": []
  },
  "output": {
    "status": "approved",
    "amount": 500,
    "recipient": "Bob"
  },
  "sdk_version": "0.0.1a1",
  "deployment_env": "production"
}

Response (200)

{
  "envelope_id": "env_abc123",
  "validation": {
    "score": 0.92,
    "checks": { "schema": "pass", "policy": "pass" }
  },
  "confidence": {
    "score": 0.88
  },
  "risk": {
    "tier": "low",
    "score": 0.15
  },
  "decision": {
    "outcome": "approve",
    "reasons": []
  },
  "latency_ms": 18,
  "governance_disclosure": "Output approved by policy engine."
}

Pipeline executed

Historical reliability lookup
ValidationEngine (6 checks)
ConfidenceEngine (7 signals)
RiskEngine (4 factors)
Trust chain check (if parent_envelope_id set)
DecisionEngine
Audit persist
Review queue (if escalate/request_evidence)
LLM judge enqueue (async, Enterprise)

SDK example

from agentrust_sdk import AgentTrustClient
with AgentTrustClient() as client:
    result = client.validate(
        agent_id="payment-agent",
        user="alice",
        input="Transfer $500",
        output={"status": "approved"},
    )

Error cases

Status	Cause
400	Invalid request body
401	Missing/invalid auth token
403	Tier does not allow requested capability
422	Schema validation failed on request
429	Rate limit exceeded
500	Internal gateway error

Examples

curl -X POST http://localhost:8000/v1/runtime/validate \
  -H "Content-Type: application/json" \
  -H "X-AgentTrust-Token: $AGENTRUST_KEY" \
  -d '{"agent_id":"test","framework":"REST","request":{"user":"u","input":"hi"},"execution":{},"output":{"ok":true}}'

Best Practices

Always send structured output as JSON object
Include tool_calls in execution for tool trust checks
Pass parent_envelope_id in multi-agent pipelines
Log envelope_id for audit correlation

Common Mistakes

Empty execution object when tools were used
Omitting framework (defaults affect analytics)
Expecting synchronous LLM judge results (async only)

Troubleshooting

Issue	Fix
Always `block`	Review policy pack and golden tests
Missing confidence/risk	Developer tier required
High latency	Check Redis; reduce golden test count

API: Validate