AgentTrust Docs

Overview

The @harness decorator (alias: validate) wraps agent functions to automatically send input/output to the gateway after each execution. It supports sync and async functions, configurable block behavior, and transparent pass-through when AGENTRUST_ENABLED=false.

Why It Matters

@harness is the most explicit and auditable integration pattern — ideal for new agent functions where governance boundaries should be visible in code.

Prerequisites

pip install "agentrust-sdk[embedded,retry]"

Step-by-Step Guide

1. Basic usage

from agentrust_sdk import harness

@harness
def my_agent(user: str, input: str) -> dict:
    return {"answer": call_llm(input)}

result = my_agent(user="alice", input="Hello")

2. Async support

@harness
async def async_agent(user: str, input: str) -> dict:
    return {"answer": await call_llm_async(input)}

3. Configure agent metadata

@harness(agent_id="payment-agent", framework="Custom")
def payment_agent(user, input):
    return process_payment(input)

4. Block behavior

from agentrust_sdk.decorator import BlockedError

@harness(block_on_block=True, block_on_escalate=True)
def high_stakes_agent(user, input):
    return {"action": "execute"}

try:
    high_stakes_agent("alice", "run")
except BlockedError as e:
    handle_block(e)

5. Access validation result

@harness(return_validation=True)
def agent_with_metadata(user, input):
    return {"ok": True}

output, validation = agent_with_metadata("alice", "test")
print(validation.decision.outcome)

Examples

FastAPI route handler:

from fastapi import FastAPI
from agentrust_sdk import harness, embed_gateway

app = FastAPI()

@app.on_event("startup")
def startup():
    embed_gateway()

@app.post("/agent")
@harness(agent_id="api-agent", framework="REST")
def run_agent(user: str, input: str):
    return {"result": process(input)}

Best Practices

Set explicit agent_id for production agents
Use block_on_block=True for financial, healthcare, or data-access agents
Combine with embed_gateway() in dev; remote gateway in production
Return structured dicts (not raw strings) for schema validation

Common Mistakes

Decorating non-agent utility functions (adds unnecessary latency)
Not handling BlockedError in user-facing code paths
Returning non-JSON-serializable objects as output

Troubleshooting

Issue	Fix
Decorator is no-op	Check `AGENTRUST_ENABLED=false`
Every call blocked	Review policy pack; inspect validation reasons
TypeError on async	Ensure using `@harness` on `async def` (supported)

Harness Decorator