AgentTrust Docs

Overview

The trust chain links agent executions in multi-agent pipelines. Each child execution references its parent's envelope_id via parent_envelope_id. The gateway verifies provenance and can block outputs that violate trust chain policy.

Requires Enterprise tier.

Why It Matters

In multi-agent systems, a downstream agent's output is only as trustworthy as its upstream inputs. Trust chain enforcement provides auditable provenance across agent boundaries.

Prerequisites

Enterprise tier API key
Full edge gateway (not embedded)
How It Works

Step-by-Step Guide

1. First agent in pipeline

from agentrust_sdk import AgentTrustClient

with AgentTrustClient() as client:
    result = client.validate(
        agent_id="research-agent",
        user="alice",
        input="Analyze Q3 revenue",
        output={"summary": "Revenue up 12%"},
        framework="Custom",
    )
    parent_id = result.envelope_id

2. Downstream agent references parent

result2 = client.validate(
    agent_id="report-agent",
    user="alice",
    input="Generate executive summary",
    output={"report": "Q3 revenue increased 12%..."},
    framework="Custom",
    parent_envelope_id=parent_id,
)

3. Gateway verifies chain

The gateway walks from parent_envelope_id up through each stored ancestor and blocks on exactly two conditions:

Condition	Result
Chain depth reaches `MAX_CHAIN_DEPTH`	`block` — "Chain depth limit exceeded"
Any ancestor's decision is not exactly `approve`	`block` — "Ancestor agent(s) not approved: …"

Two things it deliberately does not do:

A missing parent does not block. If parent_envelope_id names an envelope that is not in the audit store, the walk logs a warning, stops, and yields an empty chain — which counts as approved. Passing a stale or invented parent ID silently disables the check rather than failing.
The child's own risk tier never blocks. It only feeds effective_risk_tier (the maximum tier across the child and every ancestor), which is reported for context.

Note "not exactly approve" is strict: an ancestor left at escalate, retry, request_evidence, or pending blocks the child just as a block would.

4. Pipeline decorator pattern

See examples/multi_agent_chain.py for a full pipeline example with @harness and explicit envelope ID passing.

Examples

Three-agent pipeline:

User → Planner Agent → Executor Agent → Reviewer Agent
         envelope_1       envelope_2         envelope_3
              └─parent────────┘    └─parent────┘

def run_pipeline(user, input):
    r1 = planner.validate(..., parent_envelope_id=None)
    r2 = executor.validate(..., parent_envelope_id=r1.envelope_id)
    r3 = reviewer.validate(..., parent_envelope_id=r2.envelope_id)
    return r3

Best Practices

Pass parent_envelope_id for every non-root agent in a pipeline
Block pipeline continuation if any intermediate step returns block
Store envelope IDs in workflow state (LangGraph, Temporal, etc.)
Verify chain integrity via GET /v1/audit/chain/verify

Common Mistakes

Omitting parent_envelope_id in multi-agent flows (chain not enforced)
Using embedded gateway (trust chain not available)
Reusing stale parent IDs — an unknown ID does not error, it just skips the check
Expecting a downstream escalate to pass: an ancestor must be exactly approve

Troubleshooting

Issue	Fix
Trust chain violation block	Inspect parent envelope decision; fix upstream agent
`parent_envelope_id` not found	The chain silently resolves as empty-and-approved. Verify the parent envelope exists via `GET /v1/audit/executions/{id}` — the gateway will not tell you.
Feature unavailable	Confirm Enterprise tier via `agentrust whoami`

Trust Chain