Struct LlmAgent 

pub struct LlmAgent { /* private fields */ }

An agent that uses an LLM (Large Language Model) to process messages.

The LlmAgent integrates with the Ceylon Mesh agent system and delegates message processing to an LLM. It supports:

• Configurable system prompts
• Model parameters (temperature, max tokens, etc.)
• Tool calling integration with existing ToolInvoker
• Multiple LLM providers (OpenAI, Anthropic, Ollama, etc.)
• Optional memory module integration

Examples

use runtime::llm::{LlmAgent, LLMConfig};

// Create agent with Ollama (local, no API key needed)
let agent = LlmAgent::builder("my_agent", "ollama::llama2")
    .with_system_prompt("You are a helpful assistant.")
    .build()
    .expect("Failed to create agent");

// Create agent with OpenAI
let agent = LlmAgent::builder("gpt_agent", "openai::gpt-4")
    .with_api_key(std::env::var("OPENAI_API_KEY").unwrap())
    .with_temperature(0.7)
    .build()
    .expect("Failed to create agent");

Implementations

impl LlmAgent

pub fn builder( name: impl Into<String>, model: impl Into<String>, ) -> LlmAgentBuilder

Create a builder for constructing an LlmAgent.

Arguments

• name - The name of the agent
• model - The model in “provider::model” format (e.g., “openai::gpt-4”, “ollama::llama2”)

Examples

use runtime::llm::LlmAgent;

let agent = LlmAgent::builder("my_agent", "ollama::llama2")
    .build()
    .expect("Failed to create agent");

Examples found in repository

examples/llm_multi_agent_mesh.rs (line 46)

    fn new(mesh: Arc<LocalMesh>) -> Result<Self> {
        let llm_agent = LlmAgent::builder("researcher", "ollama::gemma3:latest")
            .with_system_prompt(
                "You are a research assistant. When given a topic, provide detailed \
                 information and key facts about it. Be thorough but focused. \
                 Limit your response to 3-4 paragraphs.",
            )
            .with_temperature(0.7)
            .with_max_tokens(1024)
            .build()?;

        Ok(Self { llm_agent, mesh })
    }
}

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

    async fn on_start(&mut self, _ctx: &mut AgentContext) -> Result<()> {
        println!("[Researcher] Started and ready for research tasks.");
        Ok(())
    }

    async fn on_message(&mut self, msg: Message, ctx: &mut AgentContext) -> Result<()> {
        let topic = String::from_utf8_lossy(&msg.payload);
        println!("\n[Researcher] Received research request: {}", topic);

        // Use LLM to research the topic
        let research_prompt = format!(
            "Research the following topic and provide key information: {}",
            topic
        );

        match self
            .llm_agent
            .send_message_and_get_response(&research_prompt, ctx)
            .await
        {
            Ok(research_result) => {
                println!("[Researcher] Research complete. Sending to summarizer...");

                // Send research results to the summarizer
                let research_msg =
                    Message::new("research_result", research_result.into_bytes(), self.name());
                self.mesh.send(research_msg, "summarizer").await?;
            }
            Err(e) => {
                eprintln!("[Researcher] Error during research: {}", e);
                // Send error message to summarizer
                let error_msg = Message::new(
                    "error",
                    format!("Research failed: {}", e).into_bytes(),
                    self.name(),
                );
                self.mesh.send(error_msg, "summarizer").await?;
            }
        }

        Ok(())
    }
}

// --- Summarizer Agent Wrapper ---
// Wraps an LlmAgent to summarize research findings
struct SummarizerAgent {
    llm_agent: LlmAgent,
    completion_notify: Arc<Notify>,
}

impl SummarizerAgent {
    fn new(completion_notify: Arc<Notify>) -> Result<Self> {
        let llm_agent = LlmAgent::builder("summarizer", "ollama::gemma3:latest")
            .with_system_prompt(
                "You are a summarization expert. When given research content, \
                 create a clear and concise summary with bullet points highlighting \
                 the most important facts. Keep the summary to 5-7 bullet points.",
            )
            .with_temperature(0.5)
            .with_max_tokens(512)
            .build()?;

        Ok(Self {
            llm_agent,
            completion_notify,
        })
    }

examples/llm_ollama.rs (line 28)

async fn main() -> Result<()> {
    println!("=== Ceylon Runtime - LLM Ollama Example ===\n");

    // Create an LLM agent using Ollama with gemma3:latest model
    // No API key is required for Ollama (local inference)
    let mut agent = LlmAgent::builder("gemma_agent", "ollama::gemma3:latest")
        .with_system_prompt(
            "You are a helpful AI assistant. Be concise and informative in your responses.",
        )
        .with_temperature(0.7)
        .with_max_tokens(1024)
        .build()?;

    println!("✓ LLM Agent created successfully with Ollama gemma3:latest\n");

    // Create an agent context for the conversation
    let mut ctx = AgentContext::new("gemma_demo_mesh".to_string(), None);

    // Example 1: Simple greeting
    println!("--- Example 1: Simple Greeting ---");
    let prompt1 = "Hello! What are you capable of?";
    println!("User: {}", prompt1);

    match agent.send_message_and_get_response(prompt1, &mut ctx).await {
        Ok(response) => {
            println!("Assistant: {}\n", response);
        }
        Err(e) => {
            eprintln!("Error: {}\n", e);
            eprintln!("Make sure Ollama is running and gemma3:latest model is available.");
            eprintln!("Pull the model with: ollama pull gemma3:latest");
            return Err(e);
        }
    }

    // Example 2: Technical question
    println!("--- Example 2: Technical Question ---");
    let prompt2 = "Explain what an AI agent is in 2-3 sentences.";
    println!("User: {}", prompt2);

    match agent.send_message_and_get_response(prompt2, &mut ctx).await {
        Ok(response) => {
            println!("Assistant: {}\n", response);
        }
        Err(e) => {
            eprintln!("Error: {}\n", e);
            return Err(e);
        }
    }

    // Example 3: Creative task
    println!("--- Example 3: Creative Task ---");
    let prompt3 = "Write a haiku about programming.";
    println!("User: {}", prompt3);

    match agent.send_message_and_get_response(prompt3, &mut ctx).await {
        Ok(response) => {
            println!("Assistant: {}\n", response);
        }
        Err(e) => {
            eprintln!("Error: {}\n", e);
            return Err(e);
        }
    }

    println!("=== Example completed successfully! ===");
    Ok(())
}

pub fn new_with_config( name: impl Into<String>, config: LLMConfig, system_prompt: impl Into<String>, memory: Option<Arc<dyn Memory>>, ) -> Result<Self>

Create an LlmAgent with comprehensive LLMConfig

pub fn with_react(&mut self, config: ReActConfig)

Enable ReAct (Reason + Act) mode

pub async fn send_message_react( &mut self, message: impl Into<String>, ctx: &mut AgentContext, ) -> Result<ReActResult>

Send a message using ReAct reasoning mode

pub async fn send_message_and_get_response( &mut self, message: impl Into<String>, ctx: &mut AgentContext, ) -> Result<String>

Send a message and get the LLM’s response This is a convenience method for Python bindings and direct usage. It processes the message with the LLM and returns the response text.

Examples found in repository

examples/llm_multi_agent_mesh.rs (line 83)

    async fn on_message(&mut self, msg: Message, ctx: &mut AgentContext) -> Result<()> {
        let topic = String::from_utf8_lossy(&msg.payload);
        println!("\n[Researcher] Received research request: {}", topic);

        // Use LLM to research the topic
        let research_prompt = format!(
            "Research the following topic and provide key information: {}",
            topic
        );

        match self
            .llm_agent
            .send_message_and_get_response(&research_prompt, ctx)
            .await
        {
            Ok(research_result) => {
                println!("[Researcher] Research complete. Sending to summarizer...");

                // Send research results to the summarizer
                let research_msg =
                    Message::new("research_result", research_result.into_bytes(), self.name());
                self.mesh.send(research_msg, "summarizer").await?;
            }
            Err(e) => {
                eprintln!("[Researcher] Error during research: {}", e);
                // Send error message to summarizer
                let error_msg = Message::new(
                    "error",
                    format!("Research failed: {}", e).into_bytes(),
                    self.name(),
                );
                self.mesh.send(error_msg, "summarizer").await?;
            }
        }

        Ok(())
    }
}

// --- Summarizer Agent Wrapper ---
// Wraps an LlmAgent to summarize research findings
struct SummarizerAgent {
    llm_agent: LlmAgent,
    completion_notify: Arc<Notify>,
}

impl SummarizerAgent {
    fn new(completion_notify: Arc<Notify>) -> Result<Self> {
        let llm_agent = LlmAgent::builder("summarizer", "ollama::gemma3:latest")
            .with_system_prompt(
                "You are a summarization expert. When given research content, \
                 create a clear and concise summary with bullet points highlighting \
                 the most important facts. Keep the summary to 5-7 bullet points.",
            )
            .with_temperature(0.5)
            .with_max_tokens(512)
            .build()?;

        Ok(Self {
            llm_agent,
            completion_notify,
        })
    }
}

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

    async fn on_start(&mut self, _ctx: &mut AgentContext) -> Result<()> {
        println!("[Summarizer] Started and ready to summarize.");
        Ok(())
    }

    async fn on_message(&mut self, msg: Message, ctx: &mut AgentContext) -> Result<()> {
        let content = String::from_utf8_lossy(&msg.payload);
        println!("\n[Summarizer] Received content from {}", msg.sender);

        if msg.topic == "error" {
            println!("[Summarizer] Received error: {}", content);
            self.completion_notify.notify_one();
            return Ok(());
        }

        // Use LLM to summarize the research
        let summary_prompt = format!(
            "Please summarize the following research content into clear bullet points:\n\n{}",
            content
        );

        match self
            .llm_agent
            .send_message_and_get_response(&summary_prompt, ctx)
            .await
        {
            Ok(summary) => {
                println!("\n========================================");
                println!("           FINAL SUMMARY");
                println!("========================================\n");
                println!("{}", summary);
                println!("\n========================================\n");
            }
            Err(e) => {
                eprintln!("[Summarizer] Error during summarization: {}", e);
            }
        }

        // Signal completion
        self.completion_notify.notify_one();
        Ok(())
    }

examples/llm_ollama.rs (line 46)

async fn main() -> Result<()> {
    println!("=== Ceylon Runtime - LLM Ollama Example ===\n");

    // Create an LLM agent using Ollama with gemma3:latest model
    // No API key is required for Ollama (local inference)
    let mut agent = LlmAgent::builder("gemma_agent", "ollama::gemma3:latest")
        .with_system_prompt(
            "You are a helpful AI assistant. Be concise and informative in your responses.",
        )
        .with_temperature(0.7)
        .with_max_tokens(1024)
        .build()?;

    println!("✓ LLM Agent created successfully with Ollama gemma3:latest\n");

    // Create an agent context for the conversation
    let mut ctx = AgentContext::new("gemma_demo_mesh".to_string(), None);

    // Example 1: Simple greeting
    println!("--- Example 1: Simple Greeting ---");
    let prompt1 = "Hello! What are you capable of?";
    println!("User: {}", prompt1);

    match agent.send_message_and_get_response(prompt1, &mut ctx).await {
        Ok(response) => {
            println!("Assistant: {}\n", response);
        }
        Err(e) => {
            eprintln!("Error: {}\n", e);
            eprintln!("Make sure Ollama is running and gemma3:latest model is available.");
            eprintln!("Pull the model with: ollama pull gemma3:latest");
            return Err(e);
        }
    }

    // Example 2: Technical question
    println!("--- Example 2: Technical Question ---");
    let prompt2 = "Explain what an AI agent is in 2-3 sentences.";
    println!("User: {}", prompt2);

    match agent.send_message_and_get_response(prompt2, &mut ctx).await {
        Ok(response) => {
            println!("Assistant: {}\n", response);
        }
        Err(e) => {
            eprintln!("Error: {}\n", e);
            return Err(e);
        }
    }

    // Example 3: Creative task
    println!("--- Example 3: Creative Task ---");
    let prompt3 = "Write a haiku about programming.";
    println!("User: {}", prompt3);

    match agent.send_message_and_get_response(prompt3, &mut ctx).await {
        Ok(response) => {
            println!("Assistant: {}\n", response);
        }
        Err(e) => {
            eprintln!("Error: {}\n", e);
            return Err(e);
        }
    }

    println!("=== Example completed successfully! ===");
    Ok(())
}

pub fn last_response(&self) -> Option<String>

Get the last assistant response from conversation history

Trait Implementations

impl Agent for LlmAgent

fn name(&self) -> String

Returns the unique name of this agent.

fn on_message<'life0, 'life1, 'async_trait>( &'life0 mut self, msg: CeylonMessage, 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.

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.

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

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

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

Get mutable tool invoker for dynamic tool registration.

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.

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.