Trust Reference

Fluent builder for composing TrustChain components. Produces a configured chain object ready to wrap an agent.

Constructor

Parameter	Type	Required	Description
agent_id	string	Yes	Unique identifier for the agent being protected
memory_backend	string	No	URI for memory store. Defaults to memory:// (in-process)

Methods

Method	Parameters	Returns	Description
with_attestation(**kwargs)	See NodeAttestor	self	Enable attestation with the given configuration
with_context_guard(**kwargs)	See ContextGuard	self	Enable context integrity checking
with_rag_trust(**kwargs)	See RAGTrustLayer	self	Enable RAG source validation
with_memory_guard(**kwargs)	See MemoryGuard	self	Enable memory integrity protection
with_hierarchy(**kwargs)	See AgentHierarchy	self	Enable agent hierarchy enforcement
build()	—	TrustChain	Build and return the configured chain
from_env(agent_id)	agent_id: string	TrustChainBuilder	Class method. Read all configuration from environment variables

The composed chain object returned by TrustChainBuilder.build(). Wraps an agent with all configured protection layers.

Methods

Method	Parameters	Returns	Description
run(agent, input)	agent: Any, input: str	Any	Run the agent through all TrustChain layers
export_audit()	—	AuditBundle	Export the complete audit trail for the most recent run
verify()	—	bool	Verify the integrity of the most recent run's chain

Signs each execution step with a cryptographic key. Produces an ordered chain of attestation records.

Constructor

Parameter	Type	Required	Description
agent_id	string	Yes	Agent identifier included in every record
signed	bool	No	Enable HMAC signing. Default: False
key_path	string	If signed=True	Path to PEM key or raw bytes key file
algorithm	string	No	Signing algorithm. Default: "HS256"

Methods

Method	Parameters	Returns	Description
attach(agent)	agent: Any	None	Instrument the agent to produce attestation records
export_chain()	—	list[AttestationRecord]	Return all records from the current session
verify_chain(records)	records: list[AttestationRecord]	bool	Verify signatures and ordering. Raises AttestationError on failure
attest(step, data)	step: str, data: dict	AttestationRecord	Manually attest a step. Used for custom integration points

Exceptions

Exception	Raised when
AttestationError	Chain verification fails — missing record, invalid signature, or ordering violation

A single signed record in the attestation chain.

Fields

Field	Type	Description
agent_id	string	Agent that produced this record
step	string	Step type: tool_call, llm_response, memory_read, context_snapshot
sequence	int	Monotonically increasing position in the chain
timestamp	string	ISO 8601 timestamp
data_hash	string	SHA-256 hash of the step's input/output data
signature	string | null	HMAC signature. Null if signed=False
prev_hash	string	Hash of the previous record — creates the chain linkage

Snapshots and verifies the agent's context window at specified execution points to detect context mutation.

Constructor

Parameter	Type	Required	Description
agent_id	string	Yes	Agent identifier
snapshot_on	list[string]	No	Events that trigger a snapshot. Default: ["tool_call", "llm_response"]
on_mutation	string	No	Action on detected mutation: "raise", "log", "alert". Default: "raise"

Methods

Method	Parameters	Returns	Description
wrap(agent)	agent: Any	Any	Wrap agent with context integrity checking
snapshot(context)	context: dict	ContextSnapshot	Manually take a snapshot of the given context dict
verify(snapshot, context)	snapshot: ContextSnapshot, context: dict	bool	Verify context matches snapshot. Raises ContextMutationError if not
integrity_log()	—	list[IntegrityRecord]	Return all snapshot/verify records from the current session

Exceptions

Exception	Raised when
ContextMutationError	Context does not match the most recent snapshot. Includes a diff of changed keys

Validates retrieved documents against a registry of trusted sources and known content hashes. Detects RAG poisoning attacks.

Constructor

Parameter	Type	Required	Description
agent_id	string	Yes	Agent identifier
on_untrusted	string	No	Action for untrusted documents: "raise", "quarantine", "log". Default: "raise"

Methods

Method	Parameters	Returns	Description
register_source(uri, trust_level)	uri: string, trust_level: string	None	Register a trusted source URI prefix. trust_level: "high", "medium", "low"
register_document_hash(uri, sha256)	uri: string, sha256: string	None	Register a known-good hash for a specific document
guard(fn)	fn: callable	callable	Decorator. Wraps a retrieval function with trust validation
validate(document, source_uri)	document: str, source_uri: str	TrustResult	Validate a single document against the registry
quarantine_log()	—	list[QuarantineRecord]	Return all quarantined documents from the current session

Exceptions

Exception	Raised when
RAGPoisoningError	Retrieved document comes from an unregistered source or fails hash verification

Protects agent persistent memory against poisoning via cryptographic snapshots and verified reads.

Constructor

Parameter	Type	Required	Description
agent_id	string	Yes	Agent identifier
backend	string	No	Storage backend URI. Supports memory://, redis://, sqlite:///. Default: memory://

Methods

Method	Parameters	Returns	Description
snapshot()	—	string	Take a snapshot of the current memory state. Returns a snapshot ID
verify(snapshot_id)	snapshot_id: string	bool	Verify current memory matches the given snapshot. Raises MemoryPoisoningError if not
read_safe(key)	key: string	Any	Read a memory entry after verifying it against the last snapshot
write(key, value)	key: string, value: Any	None	Write to memory. Logged and included in next snapshot
audit_log()	—	list[MemoryAuditEntry]	Return all memory operations from the current session

Exceptions

Exception	Raised when
MemoryPoisoningError	Memory does not match the snapshot — a write occurred between the snapshot and the verify call

Enforces who can instruct whom in a multi-agent system. Supports supervisor/worker relationships, veto rights, and quorum requirements.

Constructor

Parameter	Type	Required	Description
strict	bool	No	Raise on hierarchy violations. Default: False (log only)

Methods

Method	Parameters	Returns	Description
set_supervisor(agent_id, workers)	agent_id: string, workers: list[string]	None	Register an agent as supervisor of the given workers
grant_veto(agent_id, over)	agent_id: string, over: list[string]	None	Grant veto rights over the listed agents' decisions
require_quorum(agent, actions, approvers, threshold)	See parameters	None	Require quorum approval for specific actions
enforce(strict)	strict: bool	None	Set strict mode. When True, violations raise instead of logging
wrap(agent_id, agent)	agent_id: string, agent: Any	Any	Wrap an agent with hierarchy enforcement
check_permission(caller_id, callee_id)	caller_id: string, callee_id: string	bool	Check whether caller is permitted to instruct callee

require_quorum parameters

Parameter	Type	Description
agent	string	The agent whose actions require quorum
actions	list[string]	Tool/action names that require quorum
approvers	list[string]	Agent IDs whose approval counts toward quorum
threshold	int	Number of approvals required before action is permitted

Exceptions

Exception	Raised when
HierarchyViolationError	An agent receives instructions from a non-registered supervisor (strict mode only)
QuorumNotMetError	An action requiring quorum is attempted without sufficient approvals

Exports attestation records as portable signed claims verifiable by external runtimes, services, or auditors.

Constructor

Parameter	Type	Required	Description
issuer	string	Yes	Claim issuer identifier, e.g. "agentcop:production-agent"
public_key_url	string	No	URL where the public verification key can be fetched by external verifiers

Methods

Method	Parameters	Returns	Description
export_claims(records)	records: list[AttestationRecord]	ClaimBundle	Export records as a portable signed claim bundle
import_claims(json_str)	json_str: string	ClaimBundle	Class method. Parse and import an external claim bundle

A portable signed bundle of attestation claims, exportable as JSON for cross-runtime verification.

Methods

Method	Parameters	Returns	Description
to_json()	—	string	Serialize to a signed JSON string
verify()	—	bool	Verify the bundle's signature. Raises TrustInteropError if invalid
issuer	—	string	Claim issuer identifier
issued_at	—	string	ISO 8601 timestamp when the bundle was created
records	—	list[dict]	The attestation records included in the bundle

Exceptions

Exception	Raised when
TrustInteropError	Bundle signature is invalid, issuer is unrecognized, or the bundle has been tampered with

Variable	Default	Description
AGENTCOP_TRUST_SIGNED	false	Enable signed attestation
AGENTCOP_TRUST_KEY_PATH	—	Path to attestation signing key
AGENTCOP_TRUST_MEMORY_BACKEND	memory://	Memory guard storage backend URI
AGENTCOP_TRUST_RAG_STRICT	false	Raise on untrusted RAG sources instead of logging
AGENTCOP_TRUST_HIERARCHY_STRICT	false	Raise on hierarchy violations instead of logging
AGENTCOP_TRUST_ON_VIOLATION	log	Default action for all violations: raise, log, alert