Struct AgentContext 

pub struct AgentContext {
    pub agent_id: AgentId,
    pub session_id: SessionId,
    pub pid: u32,
    pub started_at: Timestamp,
    pub metadata: BTreeMap<String, String>,
    pub governance_level: GovernanceLevel,
    pub parent_agent_id: Option<AgentId>,
    pub team_id: Option<String>,
    pub depth: u32,
    pub delegation_reason: Option<String>,
    pub spawned_by_tool: Option<String>,
    pub root_agent_id: Option<AgentId>,
}

Identity carrier for an agent execution.

AgentContext flows through every governance event in the system. It captures the stable agent identity, per-session identity, process ID, start time, any additional runtime metadata, and optional topology/lineage fields that describe the agent’s position in a delegation hierarchy.

Requires the alloc feature.

Fields

agent_id: AgentId

Stable identifier for the agent (UUID v4 bytes).

session_id: SessionId

Per-execution session identifier (UUID v4 bytes).

pid: u32

OS process ID of the agent process.

started_at: Timestamp

Nanoseconds since the Unix epoch when this context was created.

metadata: BTreeMap<String, String>

Extensible key-value metadata attached to this execution context.

Keys are owned String so the map is serde-compatible and accepts both string-literal keys and computed keys at runtime.

governance_level: GovernanceLevel

Governance level (L0–L3) carried for level-conditional policy rules.

Populated by the gateway from the agent’s AgentRecord (defined in aa-gateway) at the boundary between transport and the policy engine. Defaults to GovernanceLevel::L0Discover so old serialised contexts — and callers that have not yet been updated — deserialise or construct without churn.

parent_agent_id: Option<AgentId>

The agent that spawned this one; None for root agents.

team_id: Option<String>

Team this agent belongs to; None if no team is assigned.

depth: u32

Delegation depth — 0 for root agents, incremented by 1 per delegation level.

delegation_reason: Option<String>

Human-readable reason the parent delegated to this agent.

spawned_by_tool: Option<String>

Tool or framework that triggered the spawn (e.g. "langgraph.subgraph").

root_agent_id: Option<AgentId>

Root of the delegation chain — the top-level agent that ultimately spawned this one.

For root agents this equals Some(agent_id). For sub-agents it is set server-side to parent.root_agent_id.unwrap_or(parent.agent_id) so that any node in a delegation chain can resolve its root in O(1).

Implementations

impl AgentContext

pub fn now(agent_id: AgentId, session_id: SessionId, pid: u32) -> Self

Construct an AgentContext stamped at the current wall-clock time.

metadata is initialised empty; insert entries after construction.

pub fn builder() -> AgentContextBuilder

Return a fresh AgentContextBuilder for topology-aware construction.

Trait Implementations

impl Clone for AgentContext

fn clone(&self) -> AgentContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for AgentContext

fn eq(&self, other: &AgentContext) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for AgentContext