Struct AgentHandle 

pub struct AgentHandle {
    pub parent: Option<Box<AgentHandle>>,
    pub broker: Box<Option<AgentHandle>>,
    /* private fields */
}

A clonable handle for interacting with an agent.

AgentHandle provides the primary mechanism for communicating with and managing an agent from outside its own execution context. It encapsulates the necessary information to send messages to the agent’s inbox (outbox), identify the agent (id), manage its lifecycle (stop), track its tasks (tracker), and navigate the supervision hierarchy (parent, children, supervise).

Handles can be cloned freely, allowing multiple parts of the system to hold references to the same agent. Sending messages through the handle is asynchronous.

Key functionalities are exposed through implemented traits:

• AgentHandleInterface: Core methods for interaction (sending messages, stopping, etc.).
• Broker: Methods for broadcasting messages via the system broker.
• Subscriber: Method for accessing the system broker handle.

Equality and hashing are based solely on the agent’s unique identifier (id).

Fields

parent: Option<Box<AgentHandle>>

Optional reference to the parent (supervisor) agent’s handle. None if this is a top-level agent. Boxed to manage AgentHandle size.

broker: Box<Option<AgentHandle>>

Optional reference to the system message broker’s handle. Boxed to manage AgentHandle size.

Implementations

impl AgentHandle

pub async fn supervise<State: Default + Send + Debug + 'static>( &self, child: ManagedAgent<Idle, State>, ) -> Result<AgentHandle>

Starts a child agent and registers it under this agent’s supervision.

This method takes a ManagedAgent configured in the Idle state, starts its execution by calling its start method, and then stores the resulting child AgentHandle in this parent handle’s children map.

Type Parameters

• State: The user-defined state type of the child agent. Must implement Default, Send, Debug, and be 'static.

Arguments

• child: The ManagedAgent<Idle, State> instance representing the child agent to be started and supervised.

Returns

A Result containing:

• Ok(AgentHandle): The handle of the successfully started and registered child agent.
• Err(anyhow::Error): If starting the child agent fails.

Trait Implementations

impl AgentHandleInterface for AgentHandle

Implements the core interface for interacting with an agent.

fn reply_address(&self) -> MessageAddress

Returns the MessageAddress for this agent, used for sending replies.

fn create_envelope( &self, recipient_address: Option<MessageAddress>, ) -> OutboundEnvelope

Creates an OutboundEnvelope for sending a message from this agent.

Arguments

• recipient_address: An optional MessageAddress specifying the recipient. If None, the envelope is created without a specific recipient (e.g., for broadcasting or when the recipient is set later).

Returns

An OutboundEnvelope with the return_address set to this agent’s address.

fn children(&self) -> DashMap<String, AgentHandle>

Returns a clone of the internal map containing handles to the agent’s direct children.

Provides a snapshot of the currently supervised children. Modifications to the returned map will not affect the agent’s actual children list.

fn find_child(&self, ern: &Ern) -> Option<AgentHandle>

Searches for a direct child agent by its unique identifier (Ern).

Arguments

• ern: The Ern of the child agent to find.

Returns

• Some(AgentHandle): If a direct child with the matching Ern is found.
• None: If no direct child with the specified Ern exists.

fn tracker(&self) -> TaskTracker

Returns a clone of the agent’s task tracker.

The tracker can be used to monitor the agent’s main task.

fn id(&self) -> Ern

Returns a clone of the agent’s unique Entity Resource Name (Ern).

fn name(&self) -> String

Returns the agent’s root name (the first part of its Ern) as a String.

fn clone_ref(&self) -> AgentHandle

Returns a clone of this AgentHandle.

fn stop(&self) -> impl Future<Output = Result<()>> + Send + Sync + '_

Sends a [SystemSignal::Terminate] message to the agent and waits for its task to complete.

This initiates a graceful shutdown of the agent. It sends the Terminate signal to the agent’s inbox and then waits on the agent’s TaskTracker until the main task (and potentially associated tasks) have finished execution.

The agent’s wake loop is responsible for handling the Terminate signal, potentially running before_stop and after_stop hooks, and stopping child agents.

Returns

An anyhow::Result<()> indicating success or failure. Failure typically occurs if sending the Terminate signal to the agent’s inbox fails (e.g., if the channel is already closed).

fn send( &self, message: impl ActonMessage, ) -> impl Future<Output = ()> + Send + Sync + '_

where Self: Sync,

Sends a message asynchronously to this agent handle’s associated agent.

fn send_sync( &self, message: impl ActonMessage, recipient: &AgentHandle, ) -> Result<()>

where Self: Sized,

Sends a message synchronously to a specified recipient agent.

impl Broker for AgentHandle

Implements the Broker trait, allowing broadcasting via the associated broker.

fn broadcast( &self, message: impl ActonMessage, ) -> impl Future<Output = ()> + Send + Sync + '_

Sends a message to the associated system broker for broadcasting.

This method wraps the provided message in a BrokerRequest and sends it to the broker handle stored within this AgentHandle. If no broker handle is configured, an error is logged.

Arguments

• message: The message payload (must implement ActonMessage) to be broadcast.

fn broadcast_sync(&self, message: impl ActonMessage) -> Result<()>

where Self: AgentHandleInterface + Sized,

Synchronously sends a message to the broker for broadcasting.

impl Clone for AgentHandle

fn clone(&self) -> AgentHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentHandle

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

Formats the value using the given formatter.

impl Default for AgentHandle

fn default() -> Self

Creates a default, placeholder AgentHandle.

This handle is typically initialized with a default Ern, a closed channel, and no parent, broker, or children. It’s primarily used as a starting point before being properly configured when a ManagedAgent is created.

impl Hash for AgentHandle

Implements hashing based on the agent’s unique ID (Ern).

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for AgentHandle

Implements equality comparison based on the agent’s unique ID (Ern).

fn eq(&self, other: &Self) -> 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 Subscriber for AgentHandle

Implements the Subscriber trait, allowing access to the broker.

fn get_broker(&self) -> Option<AgentHandle>

Returns a clone of the optional broker handle associated with this agent.

Returns None if the agent was not configured with a broker reference.

impl Eq for AgentHandle

Derives Eq based on the PartialEq implementation.