Trait Agent 

pub trait Agent: Send + Sync {
    // Required method
    fn name(&self) -> String;

    // Provided methods
    fn on_start<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        _ctx: &'life1 mut AgentContext,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn on_message<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        _msg: Message,
        _ctx: &'life1 mut AgentContext,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn on_generic_message<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        msg: GenericMessage,
        _ctx: &'life1 mut AgentContext,
    ) -> Pin<Box<dyn Future<Output = Result<GenericResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn on_stop<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        _ctx: &'life1 mut AgentContext,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn tool_invoker(&self) -> Option<&ToolInvoker> { ... }
    fn tool_invoker_mut(&mut self) -> Option<&mut ToolInvoker> { ... }
}

The core trait that defines an autonomous agent.

Agents are the primary unit of computation in Ceylon. Each agent:

• Has a unique name for identification and message routing
• Receives lifecycle callbacks (on_start, on_stop)
• Processes messages via on_message or on_generic_message
• Optionally exposes tools via tool_invoker

Implementing an Agent

use ceylon_core::{Agent, AgentContext, Message};
use ceylon_core::error::Result;
use async_trait::async_trait;

struct CounterAgent {
    count: u32,
}

#[async_trait]
impl Agent for CounterAgent {
    fn name(&self) -> String {
        "counter".to_string()
    }

    async fn on_start(&mut self, _ctx: &mut AgentContext) -> Result<()> {
        println!("Counter starting with count: {}", self.count);
        Ok(())
    }

    async fn on_message(&mut self, msg: Message, ctx: &mut AgentContext) -> Result<()> {
        self.count += 1;
        if let Some(id) = msg.correlation_id() {
            ctx.report_result(&id, format!("Count: {}", self.count));
        }
        Ok(())
    }
}

Required Methods

fn name(&self) -> String

Returns the unique name of this agent.

This name is used for message routing and identification within a mesh.

Provided Methods

fn on_start<'life0, 'life1, 'async_trait>( &'life0 mut self, _ctx: &'life1 mut AgentContext, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called when the agent starts.

Use this for initialization logic. The mesh is running but other agents may not have started yet.

fn on_message<'life0, 'life1, 'async_trait>( &'life0 mut self, _msg: Message, _ctx: &'life1 mut AgentContext, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called when a binary message is received.

Arguments

• msg - The received message with binary payload
• ctx - The agent context for mesh interaction

fn on_generic_message<'life0, 'life1, 'async_trait>( &'life0 mut self, msg: GenericMessage, _ctx: &'life1 mut AgentContext, ) -> Pin<Box<dyn Future<Output = Result<GenericResponse>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Handle a generic string message and return a response.

Default implementation echoes the content back.

fn on_stop<'life0, 'life1, 'async_trait>( &'life0 mut self, _ctx: &'life1 mut AgentContext, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called when the agent is stopping.

Use this for cleanup logic.

fn tool_invoker(&self) -> Option<&ToolInvoker>

Get the tool invoker for this agent (if it has actions).

Return Some if this agent exposes tools that can be called by LLMs.

fn tool_invoker_mut(&mut self) -> Option<&mut ToolInvoker>

Get mutable tool invoker for dynamic tool registration.

Implementors