AgentTrust Docs

Overview

AgentTrustClient is the synchronous HTTP client for calling the AgentTrust gateway. Use it when you need full control over validation requests, access to complete response objects, or integration with non-decorator code paths.

Why It Matters

The direct client exposes the full validation pipeline response — confidence scores, risk tiers, decision reasons, and envelope IDs — for dashboards, logging pipelines, and conditional routing.

Prerequisites

pip install agentrust-sdk

Step-by-Step Guide

1. Basic validation

from agentrust_sdk import AgentTrustClient

with AgentTrustClient() as client:
    result = client.validate(
        agent_id="my-agent",
        user="alice",
        input="User query text",
        output={"answer": "Agent response"},
        framework="Custom",
    )
    print(result.decision.outcome)
    print(result.envelope_id)

2. Constructor options

client = AgentTrustClient(
    base_url="http://localhost:8000",  # or AGENTRUST_GATEWAY_URL
    api_key="at_team_...",              # or AGENTRUST_KEY
    timeout=10.0,
    failure_mode="open",                # open | closed | queue
)

3. Response fields

result.validation.score      # 0.0–1.0
result.validation.checks     # per-check results
result.confidence.score      # 0.0–1.0 (Developer+)
result.risk.tier             # low | medium | high | critical (Developer+)
result.risk.score            # numeric risk score
result.decision.outcome      # approve | block | ...
result.decision.reasons      # list of reason strings
result.envelope_id           # audit record ID
result.latency_ms            # gateway processing time

4. OSS mode (no API key)

Without an API key, the client performs in-process schema validation only — no HTTP call.

5. Tool calls metadata

from agentrust_sdk.models import ToolCall

result = client.validate(
    agent_id="tool-agent",
    user="bob",
    input="Search database",
    output={"rows": [...]},
    tool_calls=[
        ToolCall(name="sql_query", input={"query": "SELECT ..."}, output={"rows": 5}),
    ],
)

Examples

Conditional routing:

with AgentTrustClient() as client:
    result = client.validate(agent_id="router", user=u, input=i, output=o)
    if result.decision.outcome == "escalate":
        send_to_human_review(result.envelope_id)
    elif result.decision.outcome == "block":
        return error_response(result.decision.reasons)
    return success_response(o)

Best Practices

Use context manager (with AgentTrustClient()) for connection cleanup
Log envelope_id with every validation for audit correlation
Set failure_mode="closed" for compliance-critical paths
Include tool_calls when agents use tools (enables tool trust check)

Common Mistakes

Creating a new client per request (use context manager or singleton)
Ignoring failure_mode when gateway is down
Passing string output instead of dict (schema validation fails)

Troubleshooting

Error	Cause
`GatewayUnavailableError`	Gateway down + `failure_mode=closed`
`BlockedError`	Validation blocked in closed mode
`GatewayVersionError`	SDK/gateway version mismatch

Sync Client