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)

It is tools_called, not tool_calls; prompt_tokens / completion_tokens, not tokens_in / tokens_out. execution.model is required — sending "execution": {} returns 422. framework must be one of the enum values (LangChain, LangGraph, CrewAI, OpenAI Agents, Claude Agents, MCP, Custom, REST), and agent_id must match ^[\w\-\.]+$. output is capped at 100 KB.

Response (200)

Every score is on a 0–100 scale.

{
  "envelope_id": "3f8c1e2a-9b7d-4c5e-8a1f-2d6b4e9c0a13",
  "validation": {
    "schema_score": 100.0,
    "evidence_score": 88.0,
    "tool_trust_score": 100.0,
    "consistency_score": 95.0,
    "policy_score": 90.0,
    "judge_score": null,
    "historical_reliability": 92.4,
    "safety_score": 100.0,
    "contradiction_score": 0.0,
    "final_confidence": 93.6,
    "failures": []
  },
  "risk": {
    "tier": "low",
    "score": 18.0,
    "reason": "All deterministic checks passed; no high-value action detected.",
    "action_severity": 3.0,
    "business_impact": 4.0,
    "confidence_gap": 1.0,
    "policy_sensitivity": 2.0
  },
  "decision": {
    "outcome": "approve",
    "reason": "Confidence 93.6 above threshold at low risk.",
    "policy_version": "2.0",
    "score_version": "1.0",
    "reviewer_id": null,
    "review_deadline": null,
    "judge_latency_ms": null
  },
  "latency_ms": 18.4,
  "trust_chain": null,
  "governance_disclosure": "This output was evaluated by AgentTrust AI Governance System …",
  "confidence_rationale": "schema 100.0 · evidence 88.0 · tool-trust 100.0 …"
}

decision.reason is a single string, not a list. judge_score stays null until the LLM judge runs — synchronously for high / critical risk, asynchronously otherwise.

/validate is the single-shot endpoint. The @harness decorator instead uses the two-phase pair, which can stop a call before it executes:

Method	Path	Phase
POST	`/v1/runtime/pre-check`	"Can we call this?" — deterministic only, before execution
POST	`/v1/runtime/post-check`	"Is this output safe to release?" — after execution
POST	`/v1/runtime/validate`	Both at once, after execution

Pre-check request (ProposedAction — note there is no output, because none exists yet):

{
  "agent_id": "payment-agent",
  "framework": "REST",
  "action": "transfer_funds",
  "params": {"amount": 500, "recipient": "Bob"},
  "user": "alice",
  "input": "Transfer $500 to Bob",
  "model": "gpt-4o"
}

PreCheckResponse has the same shape as /validate minus trust_chain and confidence_rationale — do not parse a pre-check response as a full ValidateResponse. Two hard gates bypass the weighted decision engine entirely and return block outright: an active kill switch, and a tool-trust score below 100 (an undeclared tool, or one called outside its declared scope or limit).

Post-check request — links back to the pre-check envelope:

{
  "pre_check_envelope_id": "3f8c1e2a-9b7d-4c5e-8a1f-2d6b4e9c0a13",
  "execution": {"model": "gpt-4o", "tools_called": [], "latency_ms": 1200, "tokens": 230},
  "output": {"status": "approved", "amount": 500},
  "sdk_version": "0.0.1a1"
}

Post-check is idempotent: posting twice for the same pre-check returns the first result rather than inserting a duplicate audit row. An unknown pre_check_envelope_id returns 404. The ledger stays append-only — post-check inserts a new row linked by parent_envelope_id and never mutates the pre-check row.

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
402	Tier does not include this feature (entitlement guard)
413	Request body over `AGENTRUST_MAX_BODY_BYTES` (default 5 MB)
426	SDK too old — raises `GatewayVersionError` client-side
500	Internal gateway error

Examples

execution.model is required — omit it and the gateway answers 422.

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": {"model": "gpt-4o", "latency_ms": 120, "tokens": 40},
        "output": {"ok": true}
      }'

Best Practices

Always send structured output as JSON object
Include tools_called (and matching tool_results) in execution for tool-trust checks
Pass parent_envelope_id in multi-agent pipelines
Log envelope_id for audit correlation

Common Mistakes

Sending "execution": {} — model is required, so this returns 422
Omitting framework — it defaults to REST, which skews per-framework analytics
Expecting a synchronous LLM judge on every call — it is synchronous only for high / critical risk

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