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 checks:

Parent envelope exists and is not blocked
Child risk tier does not exceed policy limits given parent context
Chain depth within configured maximum

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 from previous unrelated runs

Troubleshooting

Issue	Fix
Trust chain violation block	Inspect parent envelope decision; fix upstream agent
`parent_envelope_id` not found	Parent not yet persisted; ensure parent validate completed
Feature unavailable	Confirm Enterprise tier via `agentrust whoami`

Trust Chain