Struct AgentContext 

pub struct AgentContext { /* private fields */ }

Event-scoped context that identifies a single flow across agents and carries auxiliary metadata.

A context is created per externally triggered event (user input, timer, webhook, etc.) so that agents connected through channels can recognize they are handling the same flow. It can carry auxiliary metadata useful for processing without altering the primary payload.

When a single datum fans out into multiple derived items (e.g., a map operation), frames track the branching lineage. Because mapping can nest, frames behave like a stack to preserve ancestry. Instances are cheap to clone and return new copies instead of mutating in place.

Implementations

impl AgentContext

pub fn new() -> Self

Creates a new context with a unique identifier and no state.

pub fn id(&self) -> usize

Returns the unique identifier for this context.

pub fn get_var(&self, key: &str) -> Option<&AgentValue>

Retrieves an immutable reference to a stored variable, if present.

pub fn with_var(&self, key: String, value: AgentValue) -> Self

Returns a new context with the provided variable inserted while keeping the current context unchanged.

impl AgentContext

pub fn frames(&self) -> Option<&Vector<Frame>>

Returns the current frame stack, if any frames have been pushed.

pub fn push_frame(&self, name: String, data: AgentValue) -> Self

Appends a new frame to the end of the stack and returns the updated context.

pub fn push_map_frame( &self, index: usize, len: usize, ) -> Result<Self, AgentError>

Pushes a map frame with index/length metadata after validating bounds.

pub fn current_map_frame(&self) -> Result<Option<(usize, usize)>, AgentError>

Returns the most recent map frame’s (index, length) if present at the top of the stack.

pub fn pop_map_frame(&self) -> Result<AgentContext, AgentError>

Removes the most recent map frame, erroring if the top frame is missing or not a map frame.

pub fn map_frame_indices(&self) -> Result<Vec<(usize, usize)>, AgentError>

Collects all map frame (index, length) tuples in order, validating each entry.

pub fn ctx_key(&self) -> Result<String, AgentError>

Returns a stable key combining the context id with all map frame indices, if present.

pub fn pop_frame(&self) -> (Option<Frame>, Self)

Removes the most recently pushed frame and returns it together with the updated context. If the stack is empty, None is returned alongside an unchanged context.

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 Default for AgentContext

fn default() -> AgentContext

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AgentContext

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentContext

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.