Trait AgentHandleInterface 

pub trait AgentHandleInterface:
    Send
    + Sync
    + Debug
    + Clone
    + 'static {
    // Required methods
    fn reply_address(&self) -> MessageAddress;
    fn create_envelope(
        &self,
        recipient_address: Option<MessageAddress>,
    ) -> OutboundEnvelope;
    fn children(&self) -> DashMap<String, AgentHandle>;
    fn find_child(&self, id: &Ern) -> Option<AgentHandle>;
    fn tracker(&self) -> TaskTracker;
    fn id(&self) -> Ern;
    fn name(&self) -> String;
    fn clone_ref(&self) -> AgentHandle;
    fn stop(&self) -> impl Future<Output = Result<()>> + Send + Sync + '_;

    // Provided methods
    fn send(
        &self,
        message: impl ActonMessage,
    ) -> impl Future<Output = ()> + Send + Sync + '_
       where Self: Sync { ... }
    fn send_sync(
        &self,
        message: impl ActonMessage,
        recipient: &AgentHandle,
    ) -> Result<()>
       where Self: Sized { ... }
}

Defines the core asynchronous interface for interacting with an agent via its handle.

This trait specifies the fundamental operations that can be performed on an agent’s handle, such as sending messages, managing its lifecycle, accessing identity information, and navigating the supervision hierarchy. It is typically implemented by AgentHandle.

Implementors of this trait provide the concrete mechanisms for these operations.

Required Methods

fn reply_address(&self) -> MessageAddress

Returns the MessageAddress associated with this agent handle.

This address contains the agent’s unique ID (Ern) and the sender channel connected to its inbox, allowing others to send messages directly to it or use it as a return address.

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

Creates an OutboundEnvelope suitable for sending a message from this agent.

The envelope’s return_address is set to this agent’s address.

Arguments

• recipient_address: An optional MessageAddress for the intended recipient. If None, the envelope is created without a specific recipient.

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

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

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

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

Attempts to find a direct child agent supervised by this agent, identified by its Ern.

Arguments

• id: The unique Ern of the child agent to locate.

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 TaskTracker.

The tracker can be used to monitor the agent’s main task and potentially other associated asynchronous operations.

fn id(&self) -> Ern

Returns a clone of the agent’s unique identifier (Ern).

fn name(&self) -> String

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

fn clone_ref(&self) -> AgentHandle

Creates and returns a clone of this agent handle.

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

Initiates a graceful shutdown of the agent associated with this handle.

This method should send a termination signal (e.g., [SystemSignal::Terminate]) to the agent and wait for its main task and associated tasks (tracked by tracker) to complete.

Returns

A Future that resolves to Ok(()) upon successful termination, or an Err if sending the termination signal or waiting for completion fails.

Provided Methods

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.

This default implementation creates an envelope with no specific recipient (implying the message is sent to the agent represented by self) and uses the envelope’s send method.

Arguments

• message: The message payload to send. Must implement ActonMessage.

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

where Self: Sized,

Sends a message synchronously to a specified recipient agent.

Warning: This default implementation uses OutboundEnvelope::reply, which internally spawns a blocking task and creates a new Tokio runtime. This is generally discouraged and can lead to performance issues or deadlocks, especially if called from within an existing asynchronous context. Prefer using asynchronous methods like AgentHandleInterface::send or OutboundEnvelope::send where possible.

Arguments

• message: The message payload to send. Must implement ActonMessage.
• recipient: A reference to the AgentHandle of the recipient agent.

Returns

A Result indicating success or failure. Currently, it relies on the behavior of OutboundEnvelope::reply, which might not propagate all underlying errors.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl AgentHandleInterface for AgentHandle

Implements the core interface for interacting with an agent.