Struct ForestOfAgents 

pub struct ForestOfAgents { /* private fields */ }

The main Forest of Agents structure that manages multiple agents.

Implementations

impl ForestOfAgents

pub fn new() -> Self

Creates a new empty Forest of Agents.

pub fn with_max_iterations(max_iterations: usize) -> Self

Creates a new Forest of Agents with the specified max iterations.

pub fn add_agent(&mut self, id: AgentId, agent: Agent) -> Result<()>

Adds an agent to the forest.

Arguments

• id - Unique identifier for the agent
• agent - The agent to add

Returns

Returns an error if an agent with the same ID already exists.

pub fn remove_agent(&mut self, id: &AgentId) -> Option<Agent>

Removes an agent from the forest.

Arguments

• id - The ID of the agent to remove

Returns

Returns the removed agent if it existed.

pub fn get_agent(&self, id: &AgentId) -> Option<&Agent>

Gets a reference to an agent by ID.

Examples found in repository

examples/send_message_tool_demo.rs (line 144)

async fn main() -> helios_engine::Result<()> {
    println!("📨 Helios Engine - SendMessageTool Demo");
    println!("=======================================\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;
    println!("✓ Loaded configuration from config.toml");

    // Create a simple forest with two agents
    let mut forest = ForestBuilder::new()
        .config(config)
        .agent(
            "alice".to_string(),
            Agent::builder("alice")
                .system_prompt("You are Alice, a helpful communication assistant."),
        )
        .agent(
            "bob".to_string(),
            Agent::builder("bob")
                .system_prompt("You are Bob, a friendly colleague who responds to messages."),
        )
        .max_iterations(3)
        .build()
        .await?;

    println!("✓ Created Forest with 2 agents: Alice and Bob");
    println!();

    // Demonstrate SendMessageTool direct messaging
    println!("📤 Testing SendMessageTool - Direct Message:");
    println!("---------------------------------------------");

    // Create the tool for Alice
    let message_queue = Arc::new(RwLock::new(Vec::new()));
    let shared_context = Arc::new(RwLock::new(helios_engine::SharedContext::new()));

    let send_tool = SendMessageTool::new(
        "alice".to_string(),
        Arc::clone(&message_queue),
        Arc::clone(&shared_context),
    );

    // Test 1: Send a direct message from Alice to Bob
    println!("1. Alice sends a direct message to Bob...");

    let direct_message_args = serde_json::json!({
        "to": "bob",
        "message": "Hi Bob! How are you doing today?"
    });

    let result = send_tool.execute(direct_message_args).await?;
    println!("   Tool result: {}", result.output);
    println!("   Success: {}", result.success);

    // Check the message queue
    {
        let queue = message_queue.read().await;
        println!("   Messages in queue: {}", queue.len());
        if let Some(msg) = queue.first() {
            println!("   Message details:");
            println!("     From: {}", msg.from);
            println!("     To: {:?}", msg.to);
            println!("     Content: {}", msg.content);
        }
    }

    // Check shared context
    {
        let context = shared_context.read().await;
        let messages = context.get_recent_messages(10);
        println!("   Messages in shared context: {}", messages.len());
    }

    println!();

    // Test 2: Send a broadcast message
    println!("2. Alice broadcasts a message to everyone...");

    let broadcast_message_args = serde_json::json!({
        "message": "Hello everyone! This is a broadcast message from Alice."
    });

    let result2 = send_tool.execute(broadcast_message_args).await?;
    println!("   Tool result: {}", result2.output);
    println!("   Success: {}", result2.success);

    // Check the message queue after broadcast
    {
        let queue = message_queue.read().await;
        println!("   Messages in queue: {}", queue.len());
        if let Some(msg) = queue.last() {
            println!("   Latest message details:");
            println!("     From: {}", msg.from);
            println!("     To: {:?}", msg.to);
            println!("     Content: {}", msg.content);
        }
    }

    println!();

    // Demonstrate integration with Forest messaging system
    println!("🌲 Testing Forest Integration:");
    println!("------------------------------");

    // Clear our test queues and use the forest's messaging system
    {
        let mut queue = message_queue.write().await;
        queue.clear();
    }

    println!("3. Using Forest's messaging system...");

    // Send message through the forest
    forest
        .send_message(
            &"alice".to_string(),
            Some(&"bob".to_string()),
            "Hello Bob via Forest messaging!".to_string(),
        )
        .await?;

    // Process messages
    forest.process_messages().await?;

    // Check if Bob received the message
    if let Some(bob) = forest.get_agent(&"bob".to_string()) {
        let messages = bob.chat_session().messages.clone();
        println!("   Bob's message count: {}", messages.len());
        if let Some(last_msg) = messages.last() {
            println!("   Bob received: {}", last_msg.content);
        }
    }

    println!();

    // Test broadcast through forest
    println!("4. Forest broadcast message...");

    forest
        .send_message(
            &"alice".to_string(),
            None, // Broadcast
            "Forest broadcast: Meeting at 3 PM!".to_string(),
        )
        .await?;

    forest.process_messages().await?;

    // Check all agents received the broadcast
    for agent_id in ["alice", "bob"] {
        if let Some(agent) = forest.get_agent(&agent_id.to_string()) {
            let messages = agent.chat_session().messages.clone();
            if let Some(last_msg) = messages.last() {
                if last_msg.content.contains("broadcast") || last_msg.content.contains("Meeting") {
                    println!("   {} received broadcast: {}", agent_id, last_msg.content);
                }
            }
        }
    }

    println!();
    println!("✅ SendMessageTool demo completed successfully!");
    println!();
    println!("Key features tested:");
    println!("  • Direct messaging between agents");
    println!("  • Broadcast messaging to all agents");
    println!("  • Message queue management");
    println!("  • Shared context integration");
    println!("  • Forest messaging system integration");

    Ok(())
}

examples/forest_of_agents.rs (line 180)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Forest of Agents Demo (with Real-Time Streaming)");
    println!("====================================================================\n");
    println!("💡 Note: All agent responses stream in real-time, token by token!\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized agents
    // Using the improved syntax to add multiple agents at once!
    let mut forest = ForestBuilder::new()
        .config(config)
        .agents(vec![
            // Coordinator agent - manages the team and delegates tasks
            (
                "coordinator".to_string(),
                Agent::builder("coordinator")
                    .system_prompt(
                        "You are a project coordinator. For simple tasks that you can handle yourself, \
                        complete them directly and provide a complete response. For complex tasks that \
                        require specialized expertise, you can delegate using the 'delegate_task' tool \
                        to agents like 'researcher', 'writer', 'editor', and 'qa'.\n\n\
                        When you delegate a task, WAIT for the response and then synthesize the results. \
                        Always provide a final, complete answer to the user's request."
                    )
                    .max_iterations(10)
            ),
            // Research agent - gathers and analyzes information
            (
                "researcher".to_string(),
                Agent::builder("researcher")
                    .system_prompt(
                        "You are a research specialist who excels at gathering information, \
                        analyzing data, and providing insights. You work closely with the coordinator \
                        and writer to ensure all work is based on accurate information. Use \
                        communication tools to share your findings and request clarification when needed."
                    )
                    .max_iterations(10)
            ),
            // Writer agent - creates content and documentation
            (
                "writer".to_string(),
                Agent::builder("writer")
                    .system_prompt(
                        "You are a skilled writer who creates clear, well-structured content and \
                        documentation. When you receive a task, complete it fully and provide the \
                        final written content. You can use communication tools to request information \
                        from the researcher if needed."
                    )
                    .max_iterations(10)
            ),
            // Editor agent - reviews and improves content
            (
                "editor".to_string(),
                Agent::builder("editor")
                    .system_prompt(
                        "You are an editor who reviews content for quality, clarity, and consistency. \
                        When you receive content to review, provide constructive feedback and an \
                        improved version."
                    )
                    .max_iterations(10)
            ),
            // Quality Assurance agent - validates the final output
            (
                "qa".to_string(),
                Agent::builder("qa")
                    .system_prompt(
                        "You are a quality assurance specialist who validates that all requirements \
                        are met and the output is accurate and complete. When you receive content to \
                        review, verify it meets all requirements and provide your assessment."
                    )
                    .max_iterations(10)
            ),
        ])
        .max_iterations(15)
        .build()
        .await?;

    println!("✅ Created Forest of Agents with 5 specialized agents:");
    println!("  • 🎯 Coordinator: Manages projects and delegates tasks");
    println!("  • 🔬 Researcher: Gathers and analyzes information");
    println!("  • ✍️  Writer: Creates content and documentation");
    println!("  • 📝 Editor: Reviews and improves content quality");
    println!("  • ✅ QA: Validates requirements and final output");
    println!();

    // Demonstrate collaborative task execution with streaming
    println!("🎯 TASK: Create a brief guide on sustainable gardening");
    println!("{}", "=".repeat(70));
    println!();

    println!("🎬 Starting collaborative task execution...");
    println!("   (Watch the responses stream in real-time!)\n");

    // Simpler task for demonstration - DISABLED TOOLS FOR TESTING
    let task = "Create a brief guide (2-3 paragraphs) on sustainable gardening. \
                Include key benefits and one practical technique.";

    println!("📋 Task Description:");
    println!("   {}\n", task);

    println!("{}", "─".repeat(70));
    println!("🤖 COORDINATOR (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    let _result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "editor".to_string(),
                "qa".to_string(),
            ],
        )
        .await?;

    println!();
    println!("{}", "─".repeat(70));
    println!();
    println!("✨ Collaborative task completed!");
    println!();

    // Demonstrate direct agent communication with streaming
    println!("💬 Testing direct agent-to-agent communication with streaming:");
    println!("{}", "─".repeat(70));
    println!();

    let mut forest_clone = forest;

    // Test a simple chat to show streaming
    println!("📤 Sending task to Writer agent...");
    println!("🤖 WRITER (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    if let Some(writer) = forest_clone.get_agent_mut(&"writer".to_string()) {
        let _response = writer
            .chat("Write one short paragraph about composting.")
            .await?;
        println!();
    }

    println!();
    println!("{}", "─".repeat(70));
    println!();

    // Send a direct message between agents
    println!("📤 Coordinator → Researcher: Direct message");
    forest_clone
        .send_message(
            &"coordinator".to_string(),
            Some(&"researcher".to_string()),
            "Great job on the research! The information was very helpful.".to_string(),
        )
        .await?;

    forest_clone.process_messages().await?;

    if let Some(researcher) = forest_clone.get_agent(&"researcher".to_string()) {
        let messages = researcher.chat_session().messages.clone();
        if let Some(last_msg) = messages.last() {
            println!("📥 Researcher received: \"{}\"", last_msg.content);
        }
    }
    println!();

    // Demonstrate shared context
    println!("🧠 Shared Context Demo:");
    println!("{}", "─".repeat(70));
    forest_clone
        .set_shared_context(
            "project_status".to_string(),
            serde_json::json!({
                "name": "Sustainable Gardening Guide",
                "status": "completed",
                "contributors": ["coordinator", "researcher", "writer"],
                "completion_date": "2025-11-03"
            }),
        )
        .await;

    let context = forest_clone.get_shared_context().await;
    if let Some(status) = context.get("project_status") {
        println!("📊 Shared project status:");
        println!("{}", serde_json::to_string_pretty(&status).unwrap());
    }
    println!();

    println!("{}", "=".repeat(70));
    println!("✅ Forest of Agents Demo Completed Successfully!");
    println!("{}", "=".repeat(70));
    println!();
    println!("🎉 Key Features Demonstrated:");
    println!("  ✓ Real-time streaming responses from all agents");
    println!("  ✓ Multi-agent collaboration on tasks");
    println!("  ✓ Inter-agent communication (direct messages)");
    println!("  ✓ Task delegation and coordination");
    println!("  ✓ Shared context and memory");
    println!("  ✓ Specialized agent roles working together");
    println!();
    println!("💡 Notice how all responses streamed token-by-token in real-time!");
    println!("   This provides immediate feedback and better user experience.");

    Ok(())
}

pub fn get_agent_mut(&mut self, id: &AgentId) -> Option<&mut Agent>

Gets a mutable reference to an agent by ID.

Examples found in repository

examples/forest_of_agents.rs (line 157)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Forest of Agents Demo (with Real-Time Streaming)");
    println!("====================================================================\n");
    println!("💡 Note: All agent responses stream in real-time, token by token!\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized agents
    // Using the improved syntax to add multiple agents at once!
    let mut forest = ForestBuilder::new()
        .config(config)
        .agents(vec![
            // Coordinator agent - manages the team and delegates tasks
            (
                "coordinator".to_string(),
                Agent::builder("coordinator")
                    .system_prompt(
                        "You are a project coordinator. For simple tasks that you can handle yourself, \
                        complete them directly and provide a complete response. For complex tasks that \
                        require specialized expertise, you can delegate using the 'delegate_task' tool \
                        to agents like 'researcher', 'writer', 'editor', and 'qa'.\n\n\
                        When you delegate a task, WAIT for the response and then synthesize the results. \
                        Always provide a final, complete answer to the user's request."
                    )
                    .max_iterations(10)
            ),
            // Research agent - gathers and analyzes information
            (
                "researcher".to_string(),
                Agent::builder("researcher")
                    .system_prompt(
                        "You are a research specialist who excels at gathering information, \
                        analyzing data, and providing insights. You work closely with the coordinator \
                        and writer to ensure all work is based on accurate information. Use \
                        communication tools to share your findings and request clarification when needed."
                    )
                    .max_iterations(10)
            ),
            // Writer agent - creates content and documentation
            (
                "writer".to_string(),
                Agent::builder("writer")
                    .system_prompt(
                        "You are a skilled writer who creates clear, well-structured content and \
                        documentation. When you receive a task, complete it fully and provide the \
                        final written content. You can use communication tools to request information \
                        from the researcher if needed."
                    )
                    .max_iterations(10)
            ),
            // Editor agent - reviews and improves content
            (
                "editor".to_string(),
                Agent::builder("editor")
                    .system_prompt(
                        "You are an editor who reviews content for quality, clarity, and consistency. \
                        When you receive content to review, provide constructive feedback and an \
                        improved version."
                    )
                    .max_iterations(10)
            ),
            // Quality Assurance agent - validates the final output
            (
                "qa".to_string(),
                Agent::builder("qa")
                    .system_prompt(
                        "You are a quality assurance specialist who validates that all requirements \
                        are met and the output is accurate and complete. When you receive content to \
                        review, verify it meets all requirements and provide your assessment."
                    )
                    .max_iterations(10)
            ),
        ])
        .max_iterations(15)
        .build()
        .await?;

    println!("✅ Created Forest of Agents with 5 specialized agents:");
    println!("  • 🎯 Coordinator: Manages projects and delegates tasks");
    println!("  • 🔬 Researcher: Gathers and analyzes information");
    println!("  • ✍️  Writer: Creates content and documentation");
    println!("  • 📝 Editor: Reviews and improves content quality");
    println!("  • ✅ QA: Validates requirements and final output");
    println!();

    // Demonstrate collaborative task execution with streaming
    println!("🎯 TASK: Create a brief guide on sustainable gardening");
    println!("{}", "=".repeat(70));
    println!();

    println!("🎬 Starting collaborative task execution...");
    println!("   (Watch the responses stream in real-time!)\n");

    // Simpler task for demonstration - DISABLED TOOLS FOR TESTING
    let task = "Create a brief guide (2-3 paragraphs) on sustainable gardening. \
                Include key benefits and one practical technique.";

    println!("📋 Task Description:");
    println!("   {}\n", task);

    println!("{}", "─".repeat(70));
    println!("🤖 COORDINATOR (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    let _result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "editor".to_string(),
                "qa".to_string(),
            ],
        )
        .await?;

    println!();
    println!("{}", "─".repeat(70));
    println!();
    println!("✨ Collaborative task completed!");
    println!();

    // Demonstrate direct agent communication with streaming
    println!("💬 Testing direct agent-to-agent communication with streaming:");
    println!("{}", "─".repeat(70));
    println!();

    let mut forest_clone = forest;

    // Test a simple chat to show streaming
    println!("📤 Sending task to Writer agent...");
    println!("🤖 WRITER (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    if let Some(writer) = forest_clone.get_agent_mut(&"writer".to_string()) {
        let _response = writer
            .chat("Write one short paragraph about composting.")
            .await?;
        println!();
    }

    println!();
    println!("{}", "─".repeat(70));
    println!();

    // Send a direct message between agents
    println!("📤 Coordinator → Researcher: Direct message");
    forest_clone
        .send_message(
            &"coordinator".to_string(),
            Some(&"researcher".to_string()),
            "Great job on the research! The information was very helpful.".to_string(),
        )
        .await?;

    forest_clone.process_messages().await?;

    if let Some(researcher) = forest_clone.get_agent(&"researcher".to_string()) {
        let messages = researcher.chat_session().messages.clone();
        if let Some(last_msg) = messages.last() {
            println!("📥 Researcher received: \"{}\"", last_msg.content);
        }
    }
    println!();

    // Demonstrate shared context
    println!("🧠 Shared Context Demo:");
    println!("{}", "─".repeat(70));
    forest_clone
        .set_shared_context(
            "project_status".to_string(),
            serde_json::json!({
                "name": "Sustainable Gardening Guide",
                "status": "completed",
                "contributors": ["coordinator", "researcher", "writer"],
                "completion_date": "2025-11-03"
            }),
        )
        .await;

    let context = forest_clone.get_shared_context().await;
    if let Some(status) = context.get("project_status") {
        println!("📊 Shared project status:");
        println!("{}", serde_json::to_string_pretty(&status).unwrap());
    }
    println!();

    println!("{}", "=".repeat(70));
    println!("✅ Forest of Agents Demo Completed Successfully!");
    println!("{}", "=".repeat(70));
    println!();
    println!("🎉 Key Features Demonstrated:");
    println!("  ✓ Real-time streaming responses from all agents");
    println!("  ✓ Multi-agent collaboration on tasks");
    println!("  ✓ Inter-agent communication (direct messages)");
    println!("  ✓ Task delegation and coordination");
    println!("  ✓ Shared context and memory");
    println!("  ✓ Specialized agent roles working together");
    println!();
    println!("💡 Notice how all responses streamed token-by-token in real-time!");
    println!("   This provides immediate feedback and better user experience.");

    Ok(())
}

pub fn list_agents(&self) -> Vec<AgentId>

Lists all agent IDs in the forest.

pub async fn send_message( &self, from: &AgentId, to: Option<&AgentId>, content: String, ) -> Result<()>

Sends a message from one agent to another.

Arguments

• from - ID of the sending agent
• to - ID of the receiving agent (None for broadcast)
• content - Message content

Returns

Returns an error if the sender doesn’t exist.

Examples found in repository

examples/send_message_tool_demo.rs (lines 133-137)

async fn main() -> helios_engine::Result<()> {
    println!("📨 Helios Engine - SendMessageTool Demo");
    println!("=======================================\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;
    println!("✓ Loaded configuration from config.toml");

    // Create a simple forest with two agents
    let mut forest = ForestBuilder::new()
        .config(config)
        .agent(
            "alice".to_string(),
            Agent::builder("alice")
                .system_prompt("You are Alice, a helpful communication assistant."),
        )
        .agent(
            "bob".to_string(),
            Agent::builder("bob")
                .system_prompt("You are Bob, a friendly colleague who responds to messages."),
        )
        .max_iterations(3)
        .build()
        .await?;

    println!("✓ Created Forest with 2 agents: Alice and Bob");
    println!();

    // Demonstrate SendMessageTool direct messaging
    println!("📤 Testing SendMessageTool - Direct Message:");
    println!("---------------------------------------------");

    // Create the tool for Alice
    let message_queue = Arc::new(RwLock::new(Vec::new()));
    let shared_context = Arc::new(RwLock::new(helios_engine::SharedContext::new()));

    let send_tool = SendMessageTool::new(
        "alice".to_string(),
        Arc::clone(&message_queue),
        Arc::clone(&shared_context),
    );

    // Test 1: Send a direct message from Alice to Bob
    println!("1. Alice sends a direct message to Bob...");

    let direct_message_args = serde_json::json!({
        "to": "bob",
        "message": "Hi Bob! How are you doing today?"
    });

    let result = send_tool.execute(direct_message_args).await?;
    println!("   Tool result: {}", result.output);
    println!("   Success: {}", result.success);

    // Check the message queue
    {
        let queue = message_queue.read().await;
        println!("   Messages in queue: {}", queue.len());
        if let Some(msg) = queue.first() {
            println!("   Message details:");
            println!("     From: {}", msg.from);
            println!("     To: {:?}", msg.to);
            println!("     Content: {}", msg.content);
        }
    }

    // Check shared context
    {
        let context = shared_context.read().await;
        let messages = context.get_recent_messages(10);
        println!("   Messages in shared context: {}", messages.len());
    }

    println!();

    // Test 2: Send a broadcast message
    println!("2. Alice broadcasts a message to everyone...");

    let broadcast_message_args = serde_json::json!({
        "message": "Hello everyone! This is a broadcast message from Alice."
    });

    let result2 = send_tool.execute(broadcast_message_args).await?;
    println!("   Tool result: {}", result2.output);
    println!("   Success: {}", result2.success);

    // Check the message queue after broadcast
    {
        let queue = message_queue.read().await;
        println!("   Messages in queue: {}", queue.len());
        if let Some(msg) = queue.last() {
            println!("   Latest message details:");
            println!("     From: {}", msg.from);
            println!("     To: {:?}", msg.to);
            println!("     Content: {}", msg.content);
        }
    }

    println!();

    // Demonstrate integration with Forest messaging system
    println!("🌲 Testing Forest Integration:");
    println!("------------------------------");

    // Clear our test queues and use the forest's messaging system
    {
        let mut queue = message_queue.write().await;
        queue.clear();
    }

    println!("3. Using Forest's messaging system...");

    // Send message through the forest
    forest
        .send_message(
            &"alice".to_string(),
            Some(&"bob".to_string()),
            "Hello Bob via Forest messaging!".to_string(),
        )
        .await?;

    // Process messages
    forest.process_messages().await?;

    // Check if Bob received the message
    if let Some(bob) = forest.get_agent(&"bob".to_string()) {
        let messages = bob.chat_session().messages.clone();
        println!("   Bob's message count: {}", messages.len());
        if let Some(last_msg) = messages.last() {
            println!("   Bob received: {}", last_msg.content);
        }
    }

    println!();

    // Test broadcast through forest
    println!("4. Forest broadcast message...");

    forest
        .send_message(
            &"alice".to_string(),
            None, // Broadcast
            "Forest broadcast: Meeting at 3 PM!".to_string(),
        )
        .await?;

    forest.process_messages().await?;

    // Check all agents received the broadcast
    for agent_id in ["alice", "bob"] {
        if let Some(agent) = forest.get_agent(&agent_id.to_string()) {
            let messages = agent.chat_session().messages.clone();
            if let Some(last_msg) = messages.last() {
                if last_msg.content.contains("broadcast") || last_msg.content.contains("Meeting") {
                    println!("   {} received broadcast: {}", agent_id, last_msg.content);
                }
            }
        }
    }

    println!();
    println!("✅ SendMessageTool demo completed successfully!");
    println!();
    println!("Key features tested:");
    println!("  • Direct messaging between agents");
    println!("  • Broadcast messaging to all agents");
    println!("  • Message queue management");
    println!("  • Shared context integration");
    println!("  • Forest messaging system integration");

    Ok(())
}

examples/forest_of_agents.rs (lines 171-175)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Forest of Agents Demo (with Real-Time Streaming)");
    println!("====================================================================\n");
    println!("💡 Note: All agent responses stream in real-time, token by token!\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized agents
    // Using the improved syntax to add multiple agents at once!
    let mut forest = ForestBuilder::new()
        .config(config)
        .agents(vec![
            // Coordinator agent - manages the team and delegates tasks
            (
                "coordinator".to_string(),
                Agent::builder("coordinator")
                    .system_prompt(
                        "You are a project coordinator. For simple tasks that you can handle yourself, \
                        complete them directly and provide a complete response. For complex tasks that \
                        require specialized expertise, you can delegate using the 'delegate_task' tool \
                        to agents like 'researcher', 'writer', 'editor', and 'qa'.\n\n\
                        When you delegate a task, WAIT for the response and then synthesize the results. \
                        Always provide a final, complete answer to the user's request."
                    )
                    .max_iterations(10)
            ),
            // Research agent - gathers and analyzes information
            (
                "researcher".to_string(),
                Agent::builder("researcher")
                    .system_prompt(
                        "You are a research specialist who excels at gathering information, \
                        analyzing data, and providing insights. You work closely with the coordinator \
                        and writer to ensure all work is based on accurate information. Use \
                        communication tools to share your findings and request clarification when needed."
                    )
                    .max_iterations(10)
            ),
            // Writer agent - creates content and documentation
            (
                "writer".to_string(),
                Agent::builder("writer")
                    .system_prompt(
                        "You are a skilled writer who creates clear, well-structured content and \
                        documentation. When you receive a task, complete it fully and provide the \
                        final written content. You can use communication tools to request information \
                        from the researcher if needed."
                    )
                    .max_iterations(10)
            ),
            // Editor agent - reviews and improves content
            (
                "editor".to_string(),
                Agent::builder("editor")
                    .system_prompt(
                        "You are an editor who reviews content for quality, clarity, and consistency. \
                        When you receive content to review, provide constructive feedback and an \
                        improved version."
                    )
                    .max_iterations(10)
            ),
            // Quality Assurance agent - validates the final output
            (
                "qa".to_string(),
                Agent::builder("qa")
                    .system_prompt(
                        "You are a quality assurance specialist who validates that all requirements \
                        are met and the output is accurate and complete. When you receive content to \
                        review, verify it meets all requirements and provide your assessment."
                    )
                    .max_iterations(10)
            ),
        ])
        .max_iterations(15)
        .build()
        .await?;

    println!("✅ Created Forest of Agents with 5 specialized agents:");
    println!("  • 🎯 Coordinator: Manages projects and delegates tasks");
    println!("  • 🔬 Researcher: Gathers and analyzes information");
    println!("  • ✍️  Writer: Creates content and documentation");
    println!("  • 📝 Editor: Reviews and improves content quality");
    println!("  • ✅ QA: Validates requirements and final output");
    println!();

    // Demonstrate collaborative task execution with streaming
    println!("🎯 TASK: Create a brief guide on sustainable gardening");
    println!("{}", "=".repeat(70));
    println!();

    println!("🎬 Starting collaborative task execution...");
    println!("   (Watch the responses stream in real-time!)\n");

    // Simpler task for demonstration - DISABLED TOOLS FOR TESTING
    let task = "Create a brief guide (2-3 paragraphs) on sustainable gardening. \
                Include key benefits and one practical technique.";

    println!("📋 Task Description:");
    println!("   {}\n", task);

    println!("{}", "─".repeat(70));
    println!("🤖 COORDINATOR (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    let _result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "editor".to_string(),
                "qa".to_string(),
            ],
        )
        .await?;

    println!();
    println!("{}", "─".repeat(70));
    println!();
    println!("✨ Collaborative task completed!");
    println!();

    // Demonstrate direct agent communication with streaming
    println!("💬 Testing direct agent-to-agent communication with streaming:");
    println!("{}", "─".repeat(70));
    println!();

    let mut forest_clone = forest;

    // Test a simple chat to show streaming
    println!("📤 Sending task to Writer agent...");
    println!("🤖 WRITER (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    if let Some(writer) = forest_clone.get_agent_mut(&"writer".to_string()) {
        let _response = writer
            .chat("Write one short paragraph about composting.")
            .await?;
        println!();
    }

    println!();
    println!("{}", "─".repeat(70));
    println!();

    // Send a direct message between agents
    println!("📤 Coordinator → Researcher: Direct message");
    forest_clone
        .send_message(
            &"coordinator".to_string(),
            Some(&"researcher".to_string()),
            "Great job on the research! The information was very helpful.".to_string(),
        )
        .await?;

    forest_clone.process_messages().await?;

    if let Some(researcher) = forest_clone.get_agent(&"researcher".to_string()) {
        let messages = researcher.chat_session().messages.clone();
        if let Some(last_msg) = messages.last() {
            println!("📥 Researcher received: \"{}\"", last_msg.content);
        }
    }
    println!();

    // Demonstrate shared context
    println!("🧠 Shared Context Demo:");
    println!("{}", "─".repeat(70));
    forest_clone
        .set_shared_context(
            "project_status".to_string(),
            serde_json::json!({
                "name": "Sustainable Gardening Guide",
                "status": "completed",
                "contributors": ["coordinator", "researcher", "writer"],
                "completion_date": "2025-11-03"
            }),
        )
        .await;

    let context = forest_clone.get_shared_context().await;
    if let Some(status) = context.get("project_status") {
        println!("📊 Shared project status:");
        println!("{}", serde_json::to_string_pretty(&status).unwrap());
    }
    println!();

    println!("{}", "=".repeat(70));
    println!("✅ Forest of Agents Demo Completed Successfully!");
    println!("{}", "=".repeat(70));
    println!();
    println!("🎉 Key Features Demonstrated:");
    println!("  ✓ Real-time streaming responses from all agents");
    println!("  ✓ Multi-agent collaboration on tasks");
    println!("  ✓ Inter-agent communication (direct messages)");
    println!("  ✓ Task delegation and coordination");
    println!("  ✓ Shared context and memory");
    println!("  ✓ Specialized agent roles working together");
    println!();
    println!("💡 Notice how all responses streamed token-by-token in real-time!");
    println!("   This provides immediate feedback and better user experience.");

    Ok(())
}

pub async fn process_messages(&mut self) -> Result<()>

Processes pending messages in the queue.

Examples found in repository

examples/send_message_tool_demo.rs (line 141)

async fn main() -> helios_engine::Result<()> {
    println!("📨 Helios Engine - SendMessageTool Demo");
    println!("=======================================\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;
    println!("✓ Loaded configuration from config.toml");

    // Create a simple forest with two agents
    let mut forest = ForestBuilder::new()
        .config(config)
        .agent(
            "alice".to_string(),
            Agent::builder("alice")
                .system_prompt("You are Alice, a helpful communication assistant."),
        )
        .agent(
            "bob".to_string(),
            Agent::builder("bob")
                .system_prompt("You are Bob, a friendly colleague who responds to messages."),
        )
        .max_iterations(3)
        .build()
        .await?;

    println!("✓ Created Forest with 2 agents: Alice and Bob");
    println!();

    // Demonstrate SendMessageTool direct messaging
    println!("📤 Testing SendMessageTool - Direct Message:");
    println!("---------------------------------------------");

    // Create the tool for Alice
    let message_queue = Arc::new(RwLock::new(Vec::new()));
    let shared_context = Arc::new(RwLock::new(helios_engine::SharedContext::new()));

    let send_tool = SendMessageTool::new(
        "alice".to_string(),
        Arc::clone(&message_queue),
        Arc::clone(&shared_context),
    );

    // Test 1: Send a direct message from Alice to Bob
    println!("1. Alice sends a direct message to Bob...");

    let direct_message_args = serde_json::json!({
        "to": "bob",
        "message": "Hi Bob! How are you doing today?"
    });

    let result = send_tool.execute(direct_message_args).await?;
    println!("   Tool result: {}", result.output);
    println!("   Success: {}", result.success);

    // Check the message queue
    {
        let queue = message_queue.read().await;
        println!("   Messages in queue: {}", queue.len());
        if let Some(msg) = queue.first() {
            println!("   Message details:");
            println!("     From: {}", msg.from);
            println!("     To: {:?}", msg.to);
            println!("     Content: {}", msg.content);
        }
    }

    // Check shared context
    {
        let context = shared_context.read().await;
        let messages = context.get_recent_messages(10);
        println!("   Messages in shared context: {}", messages.len());
    }

    println!();

    // Test 2: Send a broadcast message
    println!("2. Alice broadcasts a message to everyone...");

    let broadcast_message_args = serde_json::json!({
        "message": "Hello everyone! This is a broadcast message from Alice."
    });

    let result2 = send_tool.execute(broadcast_message_args).await?;
    println!("   Tool result: {}", result2.output);
    println!("   Success: {}", result2.success);

    // Check the message queue after broadcast
    {
        let queue = message_queue.read().await;
        println!("   Messages in queue: {}", queue.len());
        if let Some(msg) = queue.last() {
            println!("   Latest message details:");
            println!("     From: {}", msg.from);
            println!("     To: {:?}", msg.to);
            println!("     Content: {}", msg.content);
        }
    }

    println!();

    // Demonstrate integration with Forest messaging system
    println!("🌲 Testing Forest Integration:");
    println!("------------------------------");

    // Clear our test queues and use the forest's messaging system
    {
        let mut queue = message_queue.write().await;
        queue.clear();
    }

    println!("3. Using Forest's messaging system...");

    // Send message through the forest
    forest
        .send_message(
            &"alice".to_string(),
            Some(&"bob".to_string()),
            "Hello Bob via Forest messaging!".to_string(),
        )
        .await?;

    // Process messages
    forest.process_messages().await?;

    // Check if Bob received the message
    if let Some(bob) = forest.get_agent(&"bob".to_string()) {
        let messages = bob.chat_session().messages.clone();
        println!("   Bob's message count: {}", messages.len());
        if let Some(last_msg) = messages.last() {
            println!("   Bob received: {}", last_msg.content);
        }
    }

    println!();

    // Test broadcast through forest
    println!("4. Forest broadcast message...");

    forest
        .send_message(
            &"alice".to_string(),
            None, // Broadcast
            "Forest broadcast: Meeting at 3 PM!".to_string(),
        )
        .await?;

    forest.process_messages().await?;

    // Check all agents received the broadcast
    for agent_id in ["alice", "bob"] {
        if let Some(agent) = forest.get_agent(&agent_id.to_string()) {
            let messages = agent.chat_session().messages.clone();
            if let Some(last_msg) = messages.last() {
                if last_msg.content.contains("broadcast") || last_msg.content.contains("Meeting") {
                    println!("   {} received broadcast: {}", agent_id, last_msg.content);
                }
            }
        }
    }

    println!();
    println!("✅ SendMessageTool demo completed successfully!");
    println!();
    println!("Key features tested:");
    println!("  • Direct messaging between agents");
    println!("  • Broadcast messaging to all agents");
    println!("  • Message queue management");
    println!("  • Shared context integration");
    println!("  • Forest messaging system integration");

    Ok(())
}

examples/forest_of_agents.rs (line 178)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Forest of Agents Demo (with Real-Time Streaming)");
    println!("====================================================================\n");
    println!("💡 Note: All agent responses stream in real-time, token by token!\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized agents
    // Using the improved syntax to add multiple agents at once!
    let mut forest = ForestBuilder::new()
        .config(config)
        .agents(vec![
            // Coordinator agent - manages the team and delegates tasks
            (
                "coordinator".to_string(),
                Agent::builder("coordinator")
                    .system_prompt(
                        "You are a project coordinator. For simple tasks that you can handle yourself, \
                        complete them directly and provide a complete response. For complex tasks that \
                        require specialized expertise, you can delegate using the 'delegate_task' tool \
                        to agents like 'researcher', 'writer', 'editor', and 'qa'.\n\n\
                        When you delegate a task, WAIT for the response and then synthesize the results. \
                        Always provide a final, complete answer to the user's request."
                    )
                    .max_iterations(10)
            ),
            // Research agent - gathers and analyzes information
            (
                "researcher".to_string(),
                Agent::builder("researcher")
                    .system_prompt(
                        "You are a research specialist who excels at gathering information, \
                        analyzing data, and providing insights. You work closely with the coordinator \
                        and writer to ensure all work is based on accurate information. Use \
                        communication tools to share your findings and request clarification when needed."
                    )
                    .max_iterations(10)
            ),
            // Writer agent - creates content and documentation
            (
                "writer".to_string(),
                Agent::builder("writer")
                    .system_prompt(
                        "You are a skilled writer who creates clear, well-structured content and \
                        documentation. When you receive a task, complete it fully and provide the \
                        final written content. You can use communication tools to request information \
                        from the researcher if needed."
                    )
                    .max_iterations(10)
            ),
            // Editor agent - reviews and improves content
            (
                "editor".to_string(),
                Agent::builder("editor")
                    .system_prompt(
                        "You are an editor who reviews content for quality, clarity, and consistency. \
                        When you receive content to review, provide constructive feedback and an \
                        improved version."
                    )
                    .max_iterations(10)
            ),
            // Quality Assurance agent - validates the final output
            (
                "qa".to_string(),
                Agent::builder("qa")
                    .system_prompt(
                        "You are a quality assurance specialist who validates that all requirements \
                        are met and the output is accurate and complete. When you receive content to \
                        review, verify it meets all requirements and provide your assessment."
                    )
                    .max_iterations(10)
            ),
        ])
        .max_iterations(15)
        .build()
        .await?;

    println!("✅ Created Forest of Agents with 5 specialized agents:");
    println!("  • 🎯 Coordinator: Manages projects and delegates tasks");
    println!("  • 🔬 Researcher: Gathers and analyzes information");
    println!("  • ✍️  Writer: Creates content and documentation");
    println!("  • 📝 Editor: Reviews and improves content quality");
    println!("  • ✅ QA: Validates requirements and final output");
    println!();

    // Demonstrate collaborative task execution with streaming
    println!("🎯 TASK: Create a brief guide on sustainable gardening");
    println!("{}", "=".repeat(70));
    println!();

    println!("🎬 Starting collaborative task execution...");
    println!("   (Watch the responses stream in real-time!)\n");

    // Simpler task for demonstration - DISABLED TOOLS FOR TESTING
    let task = "Create a brief guide (2-3 paragraphs) on sustainable gardening. \
                Include key benefits and one practical technique.";

    println!("📋 Task Description:");
    println!("   {}\n", task);

    println!("{}", "─".repeat(70));
    println!("🤖 COORDINATOR (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    let _result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "editor".to_string(),
                "qa".to_string(),
            ],
        )
        .await?;

    println!();
    println!("{}", "─".repeat(70));
    println!();
    println!("✨ Collaborative task completed!");
    println!();

    // Demonstrate direct agent communication with streaming
    println!("💬 Testing direct agent-to-agent communication with streaming:");
    println!("{}", "─".repeat(70));
    println!();

    let mut forest_clone = forest;

    // Test a simple chat to show streaming
    println!("📤 Sending task to Writer agent...");
    println!("🤖 WRITER (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    if let Some(writer) = forest_clone.get_agent_mut(&"writer".to_string()) {
        let _response = writer
            .chat("Write one short paragraph about composting.")
            .await?;
        println!();
    }

    println!();
    println!("{}", "─".repeat(70));
    println!();

    // Send a direct message between agents
    println!("📤 Coordinator → Researcher: Direct message");
    forest_clone
        .send_message(
            &"coordinator".to_string(),
            Some(&"researcher".to_string()),
            "Great job on the research! The information was very helpful.".to_string(),
        )
        .await?;

    forest_clone.process_messages().await?;

    if let Some(researcher) = forest_clone.get_agent(&"researcher".to_string()) {
        let messages = researcher.chat_session().messages.clone();
        if let Some(last_msg) = messages.last() {
            println!("📥 Researcher received: \"{}\"", last_msg.content);
        }
    }
    println!();

    // Demonstrate shared context
    println!("🧠 Shared Context Demo:");
    println!("{}", "─".repeat(70));
    forest_clone
        .set_shared_context(
            "project_status".to_string(),
            serde_json::json!({
                "name": "Sustainable Gardening Guide",
                "status": "completed",
                "contributors": ["coordinator", "researcher", "writer"],
                "completion_date": "2025-11-03"
            }),
        )
        .await;

    let context = forest_clone.get_shared_context().await;
    if let Some(status) = context.get("project_status") {
        println!("📊 Shared project status:");
        println!("{}", serde_json::to_string_pretty(&status).unwrap());
    }
    println!();

    println!("{}", "=".repeat(70));
    println!("✅ Forest of Agents Demo Completed Successfully!");
    println!("{}", "=".repeat(70));
    println!();
    println!("🎉 Key Features Demonstrated:");
    println!("  ✓ Real-time streaming responses from all agents");
    println!("  ✓ Multi-agent collaboration on tasks");
    println!("  ✓ Inter-agent communication (direct messages)");
    println!("  ✓ Task delegation and coordination");
    println!("  ✓ Shared context and memory");
    println!("  ✓ Specialized agent roles working together");
    println!();
    println!("💡 Notice how all responses streamed token-by-token in real-time!");
    println!("   This provides immediate feedback and better user experience.");

    Ok(())
}

pub async fn execute_collaborative_task( &mut self, initiator: &AgentId, task_description: String, involved_agents: Vec<AgentId>, ) -> Result<String>

Executes a collaborative task across multiple agents with planning.

Arguments

• initiator - ID of the coordinator agent (must create the plan)
• task_description - Description of the overall task
• involved_agents - IDs of agents available for task execution

Returns

Returns the final result from the collaborative process.

Examples found in repository

examples/forest_simple_demo.rs (lines 58-62)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Forest of Agents - Simple Demo\n");

    let config = Config::from_file("config.toml")?;

    // Create a simpler forest with just 3 agents
    let mut forest = ForestBuilder::new()
        .config(config)
        .agent(
            "coordinator".to_string(),
            Agent::builder("coordinator")
                .system_prompt(
                    "You are a project coordinator. Your ONLY job is to create plans, not execute tasks.\n\
                    When given a task, IMMEDIATELY use the create_plan tool with this format:\n\
                    - objective: the overall goal\n\
                    - tasks: JSON array with structure [{\"id\":\"task_1\",\"description\":\"...\",\"assigned_to\":\"worker1\",\"dependencies\":[]}]\n\n\
                    Keep plans simple with 2-3 tasks max. Do NOT try to complete the task yourself."
                )
                .max_iterations(15)
        )
        .agent(
            "worker1".to_string(),
            Agent::builder("worker1")
                .system_prompt(
                    "You are a helpful worker. Complete the task assigned to you and use the \
                    update_task_memory tool to save your results. Be brief and direct."
                )
                .max_iterations(8)
        )
        .agent(
            "worker2".to_string(),
            Agent::builder("worker2")
                .system_prompt(
                    "You are a helpful worker. Complete the task assigned to you and use the \
                    update_task_memory tool to save your results. Be brief and direct."
                )
                .max_iterations(8)
        )
        .max_iterations(20)
        .build()
        .await?;

    println!("✅ Forest created with 3 agents\n");

    // Simple task
    let task = "List 3 benefits of exercise. Keep it brief.";
    println!("📋 Task: {}\n", task);

    let result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec!["worker1".to_string(), "worker2".to_string()],
        )
        .await?;

    println!("\n{}\n", "=".repeat(60));
    println!("✨ RESULT:\n{}\n", result);
    println!("{}\n", "=".repeat(60));

    // Show task breakdown
    let context = forest.get_shared_context().await;
    if let Some(plan) = context.get_plan() {
        println!("📊 Plan Summary:");
        let (completed, total) = plan.get_progress();
        println!("  Completed: {}/{} tasks\n", completed, total);

        for task in plan.tasks_in_order() {
            let status = match task.status {
                helios_engine::forest::TaskStatus::Completed => "✅",
                helios_engine::forest::TaskStatus::InProgress => "🔄",
                helios_engine::forest::TaskStatus::Pending => "⏳",
                helios_engine::forest::TaskStatus::Failed => "❌",
            };
            println!("  {} [{}] {}", status, task.assigned_to, task.description);
        }
    } else {
        println!("📊 No plan was created (coordinator handled directly)");
    }

    println!("\n✅ Demo completed!");

    Ok(())
}

examples/forest_of_agents.rs (lines 126-135)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Forest of Agents Demo (with Real-Time Streaming)");
    println!("====================================================================\n");
    println!("💡 Note: All agent responses stream in real-time, token by token!\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized agents
    // Using the improved syntax to add multiple agents at once!
    let mut forest = ForestBuilder::new()
        .config(config)
        .agents(vec![
            // Coordinator agent - manages the team and delegates tasks
            (
                "coordinator".to_string(),
                Agent::builder("coordinator")
                    .system_prompt(
                        "You are a project coordinator. For simple tasks that you can handle yourself, \
                        complete them directly and provide a complete response. For complex tasks that \
                        require specialized expertise, you can delegate using the 'delegate_task' tool \
                        to agents like 'researcher', 'writer', 'editor', and 'qa'.\n\n\
                        When you delegate a task, WAIT for the response and then synthesize the results. \
                        Always provide a final, complete answer to the user's request."
                    )
                    .max_iterations(10)
            ),
            // Research agent - gathers and analyzes information
            (
                "researcher".to_string(),
                Agent::builder("researcher")
                    .system_prompt(
                        "You are a research specialist who excels at gathering information, \
                        analyzing data, and providing insights. You work closely with the coordinator \
                        and writer to ensure all work is based on accurate information. Use \
                        communication tools to share your findings and request clarification when needed."
                    )
                    .max_iterations(10)
            ),
            // Writer agent - creates content and documentation
            (
                "writer".to_string(),
                Agent::builder("writer")
                    .system_prompt(
                        "You are a skilled writer who creates clear, well-structured content and \
                        documentation. When you receive a task, complete it fully and provide the \
                        final written content. You can use communication tools to request information \
                        from the researcher if needed."
                    )
                    .max_iterations(10)
            ),
            // Editor agent - reviews and improves content
            (
                "editor".to_string(),
                Agent::builder("editor")
                    .system_prompt(
                        "You are an editor who reviews content for quality, clarity, and consistency. \
                        When you receive content to review, provide constructive feedback and an \
                        improved version."
                    )
                    .max_iterations(10)
            ),
            // Quality Assurance agent - validates the final output
            (
                "qa".to_string(),
                Agent::builder("qa")
                    .system_prompt(
                        "You are a quality assurance specialist who validates that all requirements \
                        are met and the output is accurate and complete. When you receive content to \
                        review, verify it meets all requirements and provide your assessment."
                    )
                    .max_iterations(10)
            ),
        ])
        .max_iterations(15)
        .build()
        .await?;

    println!("✅ Created Forest of Agents with 5 specialized agents:");
    println!("  • 🎯 Coordinator: Manages projects and delegates tasks");
    println!("  • 🔬 Researcher: Gathers and analyzes information");
    println!("  • ✍️  Writer: Creates content and documentation");
    println!("  • 📝 Editor: Reviews and improves content quality");
    println!("  • ✅ QA: Validates requirements and final output");
    println!();

    // Demonstrate collaborative task execution with streaming
    println!("🎯 TASK: Create a brief guide on sustainable gardening");
    println!("{}", "=".repeat(70));
    println!();

    println!("🎬 Starting collaborative task execution...");
    println!("   (Watch the responses stream in real-time!)\n");

    // Simpler task for demonstration - DISABLED TOOLS FOR TESTING
    let task = "Create a brief guide (2-3 paragraphs) on sustainable gardening. \
                Include key benefits and one practical technique.";

    println!("📋 Task Description:");
    println!("   {}\n", task);

    println!("{}", "─".repeat(70));
    println!("🤖 COORDINATOR (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    let _result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "editor".to_string(),
                "qa".to_string(),
            ],
        )
        .await?;

    println!();
    println!("{}", "─".repeat(70));
    println!();
    println!("✨ Collaborative task completed!");
    println!();

    // Demonstrate direct agent communication with streaming
    println!("💬 Testing direct agent-to-agent communication with streaming:");
    println!("{}", "─".repeat(70));
    println!();

    let mut forest_clone = forest;

    // Test a simple chat to show streaming
    println!("📤 Sending task to Writer agent...");
    println!("🤖 WRITER (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    if let Some(writer) = forest_clone.get_agent_mut(&"writer".to_string()) {
        let _response = writer
            .chat("Write one short paragraph about composting.")
            .await?;
        println!();
    }

    println!();
    println!("{}", "─".repeat(70));
    println!();

    // Send a direct message between agents
    println!("📤 Coordinator → Researcher: Direct message");
    forest_clone
        .send_message(
            &"coordinator".to_string(),
            Some(&"researcher".to_string()),
            "Great job on the research! The information was very helpful.".to_string(),
        )
        .await?;

    forest_clone.process_messages().await?;

    if let Some(researcher) = forest_clone.get_agent(&"researcher".to_string()) {
        let messages = researcher.chat_session().messages.clone();
        if let Some(last_msg) = messages.last() {
            println!("📥 Researcher received: \"{}\"", last_msg.content);
        }
    }
    println!();

    // Demonstrate shared context
    println!("🧠 Shared Context Demo:");
    println!("{}", "─".repeat(70));
    forest_clone
        .set_shared_context(
            "project_status".to_string(),
            serde_json::json!({
                "name": "Sustainable Gardening Guide",
                "status": "completed",
                "contributors": ["coordinator", "researcher", "writer"],
                "completion_date": "2025-11-03"
            }),
        )
        .await;

    let context = forest_clone.get_shared_context().await;
    if let Some(status) = context.get("project_status") {
        println!("📊 Shared project status:");
        println!("{}", serde_json::to_string_pretty(&status).unwrap());
    }
    println!();

    println!("{}", "=".repeat(70));
    println!("✅ Forest of Agents Demo Completed Successfully!");
    println!("{}", "=".repeat(70));
    println!();
    println!("🎉 Key Features Demonstrated:");
    println!("  ✓ Real-time streaming responses from all agents");
    println!("  ✓ Multi-agent collaboration on tasks");
    println!("  ✓ Inter-agent communication (direct messages)");
    println!("  ✓ Task delegation and coordination");
    println!("  ✓ Shared context and memory");
    println!("  ✓ Specialized agent roles working together");
    println!();
    println!("💡 Notice how all responses streamed token-by-token in real-time!");
    println!("   This provides immediate feedback and better user experience.");

    Ok(())
}

examples/forest_with_coordinator.rs (lines 142-151)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Forest of Agents with Coordinator-Based Planning\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized roles
    let mut forest = ForestBuilder::new()
        .config(config)
        // Coordinator agent - creates plans and manages the team
        .agent(
            "coordinator".to_string(),
            Agent::builder("coordinator")
                .system_prompt(
                    "You are an expert project coordinator and task planner. Your role is to:\n\
                    1. Analyze complex tasks and break them into manageable subtasks\n\
                    2. Create detailed plans using the 'create_plan' tool\n\
                    3. Assign tasks to the most appropriate team members based on their expertise\n\
                    4. Define task dependencies to ensure proper execution order\n\
                    5. Synthesize final results from all team members\n\n\
                    Available team members:\n\
                    - researcher: Gathers information, conducts analysis, finds data\n\
                    - writer: Creates content, documentation, and written materials\n\
                    - analyst: Analyzes data, identifies patterns, provides insights\n\
                    - reviewer: Reviews work quality, provides feedback, ensures standards\n\n\
                    When creating a plan, think carefully about:\n\
                    - What information is needed first (research/data gathering)\n\
                    - What depends on what (task dependencies)\n\
                    - Who is best suited for each task\n\
                    - How to ensure quality (review steps)\n\n\
                    Always use the create_plan tool to structure the work.",
                )
                .max_iterations(20),
        )
        // Research agent - gathers information and data
        .agent(
            "researcher".to_string(),
            Agent::builder("researcher")
                .system_prompt(
                    "You are a research specialist who excels at:\n\
                    - Gathering comprehensive information on topics\n\
                    - Identifying key facts, statistics, and sources\n\
                    - Analyzing information for relevance and accuracy\n\
                    - Providing well-organized research findings\n\n\
                    When completing a task:\n\
                    1. Review the shared memory to see what other agents have done\n\
                    2. Conduct thorough research on your assigned topic\n\
                    3. Use 'update_task_memory' tool to save your findings\n\
                    4. Include key data points that other agents might need\n\n\
                    Be thorough but concise in your responses.",
                )
                .max_iterations(10),
        )
        // Writer agent - creates content
        .agent(
            "writer".to_string(),
            Agent::builder("writer")
                .system_prompt(
                    "You are a skilled content writer who excels at:\n\
                    - Creating clear, engaging, and well-structured content\n\
                    - Adapting tone and style to the audience\n\
                    - Incorporating research and data into narratives\n\
                    - Writing comprehensive yet accessible material\n\n\
                    When completing a task:\n\
                    1. Review the shared memory for research and data from other agents\n\
                    2. Create well-structured content based on the requirements\n\
                    3. Use 'update_task_memory' tool to save your written content\n\
                    4. Ensure your content is complete and ready for review\n\n\
                    Write clearly and professionally.",
                )
                .max_iterations(10),
        )
        // Analyst agent - analyzes data and provides insights
        .agent(
            "analyst".to_string(),
            Agent::builder("analyst")
                .system_prompt(
                    "You are a data analyst who excels at:\n\
                    - Analyzing information and identifying patterns\n\
                    - Drawing insights from data and research\n\
                    - Providing actionable recommendations\n\
                    - Summarizing complex information clearly\n\n\
                    When completing a task:\n\
                    1. Review the shared memory for available data and research\n\
                    2. Analyze the information thoroughly\n\
                    3. Use 'update_task_memory' tool to save your analysis and insights\n\
                    4. Provide clear, actionable conclusions\n\n\
                    Be analytical and data-driven in your responses.",
                )
                .max_iterations(10),
        )
        // Reviewer agent - ensures quality
        .agent(
            "reviewer".to_string(),
            Agent::builder("reviewer")
                .system_prompt(
                    "You are a quality reviewer who excels at:\n\
                    - Reviewing content for accuracy and completeness\n\
                    - Identifying areas for improvement\n\
                    - Ensuring consistency and quality standards\n\
                    - Providing constructive feedback\n\n\
                    When completing a task:\n\
                    1. Review the shared memory to see all completed work\n\
                    2. Evaluate the quality, accuracy, and completeness\n\
                    3. Use 'update_task_memory' tool to save your review and any improvements\n\
                    4. Provide clear assessment and final approval\n\n\
                    Be thorough and constructive in your reviews.",
                )
                .max_iterations(15),
        )
        .max_iterations(30)
        .build()
        .await?;

    println!("✅ Forest created with 5 specialized agents\n");

    let task1 = "Create a comprehensive guide about the benefits of renewable energy. \
                 Include research-backed information, clear explanations, data analysis, \
                 and ensure it's well-reviewed for quality.";

    println!("📋 Task: {}\n", task1);

    let result1 = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task1.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "analyst".to_string(),
                "reviewer".to_string(),
            ],
        )
        .await?;

    println!("\n{}\n", "=".repeat(70));
    println!("✨ FINAL RESULT:\n{}\n", result1);
    println!("{}\n", "=".repeat(70));

    // Show the shared memory state
    println!("📊 SHARED MEMORY STATE:");
    let context = forest.get_shared_context().await;

    if let Some(plan) = context.get_plan() {
        println!("\n📋 Task Plan Summary:");
        println!("  Objective: {}", plan.objective);
        println!("  Total Tasks: {}", plan.tasks.len());
        println!(
            "  Completed: {}/{}",
            plan.get_progress().0,
            plan.get_progress().1
        );
        println!("\n  Task Breakdown:");
        for task in plan.tasks_in_order() {
            let status_icon = match task.status {
                helios_engine::forest::TaskStatus::Completed => "✅",
                helios_engine::forest::TaskStatus::InProgress => "🔄",
                helios_engine::forest::TaskStatus::Pending => "⏳",
                helios_engine::forest::TaskStatus::Failed => "❌",
            };
            println!(
                "    {} [{}] {} - {}",
                status_icon, task.assigned_to, task.id, task.description
            );
            if let Some(result) = &task.result {
                let preview = if result.len() > 100 {
                    format!("{}...", &result[..100])
                } else {
                    result.clone()
                };
                println!("       Result: {}", preview);
            }
        }
    }

    println!("\n  Shared Data Keys:");
    for key in context.data.keys() {
        if !key.starts_with("current_")
            && !key.starts_with("involved_")
            && !key.starts_with("task_status")
        {
            println!("    • {}", key);
        }
    }

    println!("\n✅ Demo completed successfully!");

    Ok(())
}

pub async fn get_shared_context(&self) -> SharedContext

Gets the shared context.

Examples found in repository

examples/forest_simple_demo.rs (line 70)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Forest of Agents - Simple Demo\n");

    let config = Config::from_file("config.toml")?;

    // Create a simpler forest with just 3 agents
    let mut forest = ForestBuilder::new()
        .config(config)
        .agent(
            "coordinator".to_string(),
            Agent::builder("coordinator")
                .system_prompt(
                    "You are a project coordinator. Your ONLY job is to create plans, not execute tasks.\n\
                    When given a task, IMMEDIATELY use the create_plan tool with this format:\n\
                    - objective: the overall goal\n\
                    - tasks: JSON array with structure [{\"id\":\"task_1\",\"description\":\"...\",\"assigned_to\":\"worker1\",\"dependencies\":[]}]\n\n\
                    Keep plans simple with 2-3 tasks max. Do NOT try to complete the task yourself."
                )
                .max_iterations(15)
        )
        .agent(
            "worker1".to_string(),
            Agent::builder("worker1")
                .system_prompt(
                    "You are a helpful worker. Complete the task assigned to you and use the \
                    update_task_memory tool to save your results. Be brief and direct."
                )
                .max_iterations(8)
        )
        .agent(
            "worker2".to_string(),
            Agent::builder("worker2")
                .system_prompt(
                    "You are a helpful worker. Complete the task assigned to you and use the \
                    update_task_memory tool to save your results. Be brief and direct."
                )
                .max_iterations(8)
        )
        .max_iterations(20)
        .build()
        .await?;

    println!("✅ Forest created with 3 agents\n");

    // Simple task
    let task = "List 3 benefits of exercise. Keep it brief.";
    println!("📋 Task: {}\n", task);

    let result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec!["worker1".to_string(), "worker2".to_string()],
        )
        .await?;

    println!("\n{}\n", "=".repeat(60));
    println!("✨ RESULT:\n{}\n", result);
    println!("{}\n", "=".repeat(60));

    // Show task breakdown
    let context = forest.get_shared_context().await;
    if let Some(plan) = context.get_plan() {
        println!("📊 Plan Summary:");
        let (completed, total) = plan.get_progress();
        println!("  Completed: {}/{} tasks\n", completed, total);

        for task in plan.tasks_in_order() {
            let status = match task.status {
                helios_engine::forest::TaskStatus::Completed => "✅",
                helios_engine::forest::TaskStatus::InProgress => "🔄",
                helios_engine::forest::TaskStatus::Pending => "⏳",
                helios_engine::forest::TaskStatus::Failed => "❌",
            };
            println!("  {} [{}] {}", status, task.assigned_to, task.description);
        }
    } else {
        println!("📊 No plan was created (coordinator handled directly)");
    }

    println!("\n✅ Demo completed!");

    Ok(())
}

examples/forest_of_agents.rs (line 203)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Forest of Agents Demo (with Real-Time Streaming)");
    println!("====================================================================\n");
    println!("💡 Note: All agent responses stream in real-time, token by token!\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized agents
    // Using the improved syntax to add multiple agents at once!
    let mut forest = ForestBuilder::new()
        .config(config)
        .agents(vec![
            // Coordinator agent - manages the team and delegates tasks
            (
                "coordinator".to_string(),
                Agent::builder("coordinator")
                    .system_prompt(
                        "You are a project coordinator. For simple tasks that you can handle yourself, \
                        complete them directly and provide a complete response. For complex tasks that \
                        require specialized expertise, you can delegate using the 'delegate_task' tool \
                        to agents like 'researcher', 'writer', 'editor', and 'qa'.\n\n\
                        When you delegate a task, WAIT for the response and then synthesize the results. \
                        Always provide a final, complete answer to the user's request."
                    )
                    .max_iterations(10)
            ),
            // Research agent - gathers and analyzes information
            (
                "researcher".to_string(),
                Agent::builder("researcher")
                    .system_prompt(
                        "You are a research specialist who excels at gathering information, \
                        analyzing data, and providing insights. You work closely with the coordinator \
                        and writer to ensure all work is based on accurate information. Use \
                        communication tools to share your findings and request clarification when needed."
                    )
                    .max_iterations(10)
            ),
            // Writer agent - creates content and documentation
            (
                "writer".to_string(),
                Agent::builder("writer")
                    .system_prompt(
                        "You are a skilled writer who creates clear, well-structured content and \
                        documentation. When you receive a task, complete it fully and provide the \
                        final written content. You can use communication tools to request information \
                        from the researcher if needed."
                    )
                    .max_iterations(10)
            ),
            // Editor agent - reviews and improves content
            (
                "editor".to_string(),
                Agent::builder("editor")
                    .system_prompt(
                        "You are an editor who reviews content for quality, clarity, and consistency. \
                        When you receive content to review, provide constructive feedback and an \
                        improved version."
                    )
                    .max_iterations(10)
            ),
            // Quality Assurance agent - validates the final output
            (
                "qa".to_string(),
                Agent::builder("qa")
                    .system_prompt(
                        "You are a quality assurance specialist who validates that all requirements \
                        are met and the output is accurate and complete. When you receive content to \
                        review, verify it meets all requirements and provide your assessment."
                    )
                    .max_iterations(10)
            ),
        ])
        .max_iterations(15)
        .build()
        .await?;

    println!("✅ Created Forest of Agents with 5 specialized agents:");
    println!("  • 🎯 Coordinator: Manages projects and delegates tasks");
    println!("  • 🔬 Researcher: Gathers and analyzes information");
    println!("  • ✍️  Writer: Creates content and documentation");
    println!("  • 📝 Editor: Reviews and improves content quality");
    println!("  • ✅ QA: Validates requirements and final output");
    println!();

    // Demonstrate collaborative task execution with streaming
    println!("🎯 TASK: Create a brief guide on sustainable gardening");
    println!("{}", "=".repeat(70));
    println!();

    println!("🎬 Starting collaborative task execution...");
    println!("   (Watch the responses stream in real-time!)\n");

    // Simpler task for demonstration - DISABLED TOOLS FOR TESTING
    let task = "Create a brief guide (2-3 paragraphs) on sustainable gardening. \
                Include key benefits and one practical technique.";

    println!("📋 Task Description:");
    println!("   {}\n", task);

    println!("{}", "─".repeat(70));
    println!("🤖 COORDINATOR (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    let _result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "editor".to_string(),
                "qa".to_string(),
            ],
        )
        .await?;

    println!();
    println!("{}", "─".repeat(70));
    println!();
    println!("✨ Collaborative task completed!");
    println!();

    // Demonstrate direct agent communication with streaming
    println!("💬 Testing direct agent-to-agent communication with streaming:");
    println!("{}", "─".repeat(70));
    println!();

    let mut forest_clone = forest;

    // Test a simple chat to show streaming
    println!("📤 Sending task to Writer agent...");
    println!("🤖 WRITER (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    if let Some(writer) = forest_clone.get_agent_mut(&"writer".to_string()) {
        let _response = writer
            .chat("Write one short paragraph about composting.")
            .await?;
        println!();
    }

    println!();
    println!("{}", "─".repeat(70));
    println!();

    // Send a direct message between agents
    println!("📤 Coordinator → Researcher: Direct message");
    forest_clone
        .send_message(
            &"coordinator".to_string(),
            Some(&"researcher".to_string()),
            "Great job on the research! The information was very helpful.".to_string(),
        )
        .await?;

    forest_clone.process_messages().await?;

    if let Some(researcher) = forest_clone.get_agent(&"researcher".to_string()) {
        let messages = researcher.chat_session().messages.clone();
        if let Some(last_msg) = messages.last() {
            println!("📥 Researcher received: \"{}\"", last_msg.content);
        }
    }
    println!();

    // Demonstrate shared context
    println!("🧠 Shared Context Demo:");
    println!("{}", "─".repeat(70));
    forest_clone
        .set_shared_context(
            "project_status".to_string(),
            serde_json::json!({
                "name": "Sustainable Gardening Guide",
                "status": "completed",
                "contributors": ["coordinator", "researcher", "writer"],
                "completion_date": "2025-11-03"
            }),
        )
        .await;

    let context = forest_clone.get_shared_context().await;
    if let Some(status) = context.get("project_status") {
        println!("📊 Shared project status:");
        println!("{}", serde_json::to_string_pretty(&status).unwrap());
    }
    println!();

    println!("{}", "=".repeat(70));
    println!("✅ Forest of Agents Demo Completed Successfully!");
    println!("{}", "=".repeat(70));
    println!();
    println!("🎉 Key Features Demonstrated:");
    println!("  ✓ Real-time streaming responses from all agents");
    println!("  ✓ Multi-agent collaboration on tasks");
    println!("  ✓ Inter-agent communication (direct messages)");
    println!("  ✓ Task delegation and coordination");
    println!("  ✓ Shared context and memory");
    println!("  ✓ Specialized agent roles working together");
    println!();
    println!("💡 Notice how all responses streamed token-by-token in real-time!");
    println!("   This provides immediate feedback and better user experience.");

    Ok(())
}

examples/forest_with_coordinator.rs (line 160)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Forest of Agents with Coordinator-Based Planning\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized roles
    let mut forest = ForestBuilder::new()
        .config(config)
        // Coordinator agent - creates plans and manages the team
        .agent(
            "coordinator".to_string(),
            Agent::builder("coordinator")
                .system_prompt(
                    "You are an expert project coordinator and task planner. Your role is to:\n\
                    1. Analyze complex tasks and break them into manageable subtasks\n\
                    2. Create detailed plans using the 'create_plan' tool\n\
                    3. Assign tasks to the most appropriate team members based on their expertise\n\
                    4. Define task dependencies to ensure proper execution order\n\
                    5. Synthesize final results from all team members\n\n\
                    Available team members:\n\
                    - researcher: Gathers information, conducts analysis, finds data\n\
                    - writer: Creates content, documentation, and written materials\n\
                    - analyst: Analyzes data, identifies patterns, provides insights\n\
                    - reviewer: Reviews work quality, provides feedback, ensures standards\n\n\
                    When creating a plan, think carefully about:\n\
                    - What information is needed first (research/data gathering)\n\
                    - What depends on what (task dependencies)\n\
                    - Who is best suited for each task\n\
                    - How to ensure quality (review steps)\n\n\
                    Always use the create_plan tool to structure the work.",
                )
                .max_iterations(20),
        )
        // Research agent - gathers information and data
        .agent(
            "researcher".to_string(),
            Agent::builder("researcher")
                .system_prompt(
                    "You are a research specialist who excels at:\n\
                    - Gathering comprehensive information on topics\n\
                    - Identifying key facts, statistics, and sources\n\
                    - Analyzing information for relevance and accuracy\n\
                    - Providing well-organized research findings\n\n\
                    When completing a task:\n\
                    1. Review the shared memory to see what other agents have done\n\
                    2. Conduct thorough research on your assigned topic\n\
                    3. Use 'update_task_memory' tool to save your findings\n\
                    4. Include key data points that other agents might need\n\n\
                    Be thorough but concise in your responses.",
                )
                .max_iterations(10),
        )
        // Writer agent - creates content
        .agent(
            "writer".to_string(),
            Agent::builder("writer")
                .system_prompt(
                    "You are a skilled content writer who excels at:\n\
                    - Creating clear, engaging, and well-structured content\n\
                    - Adapting tone and style to the audience\n\
                    - Incorporating research and data into narratives\n\
                    - Writing comprehensive yet accessible material\n\n\
                    When completing a task:\n\
                    1. Review the shared memory for research and data from other agents\n\
                    2. Create well-structured content based on the requirements\n\
                    3. Use 'update_task_memory' tool to save your written content\n\
                    4. Ensure your content is complete and ready for review\n\n\
                    Write clearly and professionally.",
                )
                .max_iterations(10),
        )
        // Analyst agent - analyzes data and provides insights
        .agent(
            "analyst".to_string(),
            Agent::builder("analyst")
                .system_prompt(
                    "You are a data analyst who excels at:\n\
                    - Analyzing information and identifying patterns\n\
                    - Drawing insights from data and research\n\
                    - Providing actionable recommendations\n\
                    - Summarizing complex information clearly\n\n\
                    When completing a task:\n\
                    1. Review the shared memory for available data and research\n\
                    2. Analyze the information thoroughly\n\
                    3. Use 'update_task_memory' tool to save your analysis and insights\n\
                    4. Provide clear, actionable conclusions\n\n\
                    Be analytical and data-driven in your responses.",
                )
                .max_iterations(10),
        )
        // Reviewer agent - ensures quality
        .agent(
            "reviewer".to_string(),
            Agent::builder("reviewer")
                .system_prompt(
                    "You are a quality reviewer who excels at:\n\
                    - Reviewing content for accuracy and completeness\n\
                    - Identifying areas for improvement\n\
                    - Ensuring consistency and quality standards\n\
                    - Providing constructive feedback\n\n\
                    When completing a task:\n\
                    1. Review the shared memory to see all completed work\n\
                    2. Evaluate the quality, accuracy, and completeness\n\
                    3. Use 'update_task_memory' tool to save your review and any improvements\n\
                    4. Provide clear assessment and final approval\n\n\
                    Be thorough and constructive in your reviews.",
                )
                .max_iterations(15),
        )
        .max_iterations(30)
        .build()
        .await?;

    println!("✅ Forest created with 5 specialized agents\n");

    let task1 = "Create a comprehensive guide about the benefits of renewable energy. \
                 Include research-backed information, clear explanations, data analysis, \
                 and ensure it's well-reviewed for quality.";

    println!("📋 Task: {}\n", task1);

    let result1 = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task1.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "analyst".to_string(),
                "reviewer".to_string(),
            ],
        )
        .await?;

    println!("\n{}\n", "=".repeat(70));
    println!("✨ FINAL RESULT:\n{}\n", result1);
    println!("{}\n", "=".repeat(70));

    // Show the shared memory state
    println!("📊 SHARED MEMORY STATE:");
    let context = forest.get_shared_context().await;

    if let Some(plan) = context.get_plan() {
        println!("\n📋 Task Plan Summary:");
        println!("  Objective: {}", plan.objective);
        println!("  Total Tasks: {}", plan.tasks.len());
        println!(
            "  Completed: {}/{}",
            plan.get_progress().0,
            plan.get_progress().1
        );
        println!("\n  Task Breakdown:");
        for task in plan.tasks_in_order() {
            let status_icon = match task.status {
                helios_engine::forest::TaskStatus::Completed => "✅",
                helios_engine::forest::TaskStatus::InProgress => "🔄",
                helios_engine::forest::TaskStatus::Pending => "⏳",
                helios_engine::forest::TaskStatus::Failed => "❌",
            };
            println!(
                "    {} [{}] {} - {}",
                status_icon, task.assigned_to, task.id, task.description
            );
            if let Some(result) = &task.result {
                let preview = if result.len() > 100 {
                    format!("{}...", &result[..100])
                } else {
                    result.clone()
                };
                println!("       Result: {}", preview);
            }
        }
    }

    println!("\n  Shared Data Keys:");
    for key in context.data.keys() {
        if !key.starts_with("current_")
            && !key.starts_with("involved_")
            && !key.starts_with("task_status")
        {
            println!("    • {}", key);
        }
    }

    println!("\n✅ Demo completed successfully!");

    Ok(())
}

pub async fn set_shared_context(&self, key: String, value: Value)

Sets a value in the shared context.

Examples found in repository

examples/forest_of_agents.rs (lines 192-200)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Forest of Agents Demo (with Real-Time Streaming)");
    println!("====================================================================\n");
    println!("💡 Note: All agent responses stream in real-time, token by token!\n");

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create a Forest of Agents with specialized agents
    // Using the improved syntax to add multiple agents at once!
    let mut forest = ForestBuilder::new()
        .config(config)
        .agents(vec![
            // Coordinator agent - manages the team and delegates tasks
            (
                "coordinator".to_string(),
                Agent::builder("coordinator")
                    .system_prompt(
                        "You are a project coordinator. For simple tasks that you can handle yourself, \
                        complete them directly and provide a complete response. For complex tasks that \
                        require specialized expertise, you can delegate using the 'delegate_task' tool \
                        to agents like 'researcher', 'writer', 'editor', and 'qa'.\n\n\
                        When you delegate a task, WAIT for the response and then synthesize the results. \
                        Always provide a final, complete answer to the user's request."
                    )
                    .max_iterations(10)
            ),
            // Research agent - gathers and analyzes information
            (
                "researcher".to_string(),
                Agent::builder("researcher")
                    .system_prompt(
                        "You are a research specialist who excels at gathering information, \
                        analyzing data, and providing insights. You work closely with the coordinator \
                        and writer to ensure all work is based on accurate information. Use \
                        communication tools to share your findings and request clarification when needed."
                    )
                    .max_iterations(10)
            ),
            // Writer agent - creates content and documentation
            (
                "writer".to_string(),
                Agent::builder("writer")
                    .system_prompt(
                        "You are a skilled writer who creates clear, well-structured content and \
                        documentation. When you receive a task, complete it fully and provide the \
                        final written content. You can use communication tools to request information \
                        from the researcher if needed."
                    )
                    .max_iterations(10)
            ),
            // Editor agent - reviews and improves content
            (
                "editor".to_string(),
                Agent::builder("editor")
                    .system_prompt(
                        "You are an editor who reviews content for quality, clarity, and consistency. \
                        When you receive content to review, provide constructive feedback and an \
                        improved version."
                    )
                    .max_iterations(10)
            ),
            // Quality Assurance agent - validates the final output
            (
                "qa".to_string(),
                Agent::builder("qa")
                    .system_prompt(
                        "You are a quality assurance specialist who validates that all requirements \
                        are met and the output is accurate and complete. When you receive content to \
                        review, verify it meets all requirements and provide your assessment."
                    )
                    .max_iterations(10)
            ),
        ])
        .max_iterations(15)
        .build()
        .await?;

    println!("✅ Created Forest of Agents with 5 specialized agents:");
    println!("  • 🎯 Coordinator: Manages projects and delegates tasks");
    println!("  • 🔬 Researcher: Gathers and analyzes information");
    println!("  • ✍️  Writer: Creates content and documentation");
    println!("  • 📝 Editor: Reviews and improves content quality");
    println!("  • ✅ QA: Validates requirements and final output");
    println!();

    // Demonstrate collaborative task execution with streaming
    println!("🎯 TASK: Create a brief guide on sustainable gardening");
    println!("{}", "=".repeat(70));
    println!();

    println!("🎬 Starting collaborative task execution...");
    println!("   (Watch the responses stream in real-time!)\n");

    // Simpler task for demonstration - DISABLED TOOLS FOR TESTING
    let task = "Create a brief guide (2-3 paragraphs) on sustainable gardening. \
                Include key benefits and one practical technique.";

    println!("📋 Task Description:");
    println!("   {}\n", task);

    println!("{}", "─".repeat(70));
    println!("🤖 COORDINATOR (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    let _result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec![
                "researcher".to_string(),
                "writer".to_string(),
                "editor".to_string(),
                "qa".to_string(),
            ],
        )
        .await?;

    println!();
    println!("{}", "─".repeat(70));
    println!();
    println!("✨ Collaborative task completed!");
    println!();

    // Demonstrate direct agent communication with streaming
    println!("💬 Testing direct agent-to-agent communication with streaming:");
    println!("{}", "─".repeat(70));
    println!();

    let mut forest_clone = forest;

    // Test a simple chat to show streaming
    println!("📤 Sending task to Writer agent...");
    println!("🤖 WRITER (streaming response):");
    print!("   ");
    io::stdout().flush()?;

    if let Some(writer) = forest_clone.get_agent_mut(&"writer".to_string()) {
        let _response = writer
            .chat("Write one short paragraph about composting.")
            .await?;
        println!();
    }

    println!();
    println!("{}", "─".repeat(70));
    println!();

    // Send a direct message between agents
    println!("📤 Coordinator → Researcher: Direct message");
    forest_clone
        .send_message(
            &"coordinator".to_string(),
            Some(&"researcher".to_string()),
            "Great job on the research! The information was very helpful.".to_string(),
        )
        .await?;

    forest_clone.process_messages().await?;

    if let Some(researcher) = forest_clone.get_agent(&"researcher".to_string()) {
        let messages = researcher.chat_session().messages.clone();
        if let Some(last_msg) = messages.last() {
            println!("📥 Researcher received: \"{}\"", last_msg.content);
        }
    }
    println!();

    // Demonstrate shared context
    println!("🧠 Shared Context Demo:");
    println!("{}", "─".repeat(70));
    forest_clone
        .set_shared_context(
            "project_status".to_string(),
            serde_json::json!({
                "name": "Sustainable Gardening Guide",
                "status": "completed",
                "contributors": ["coordinator", "researcher", "writer"],
                "completion_date": "2025-11-03"
            }),
        )
        .await;

    let context = forest_clone.get_shared_context().await;
    if let Some(status) = context.get("project_status") {
        println!("📊 Shared project status:");
        println!("{}", serde_json::to_string_pretty(&status).unwrap());
    }
    println!();

    println!("{}", "=".repeat(70));
    println!("✅ Forest of Agents Demo Completed Successfully!");
    println!("{}", "=".repeat(70));
    println!();
    println!("🎉 Key Features Demonstrated:");
    println!("  ✓ Real-time streaming responses from all agents");
    println!("  ✓ Multi-agent collaboration on tasks");
    println!("  ✓ Inter-agent communication (direct messages)");
    println!("  ✓ Task delegation and coordination");
    println!("  ✓ Shared context and memory");
    println!("  ✓ Specialized agent roles working together");
    println!();
    println!("💡 Notice how all responses streamed token-by-token in real-time!");
    println!("   This provides immediate feedback and better user experience.");

    Ok(())
}

Trait Implementations

impl Default for ForestOfAgents

fn default() -> Self

Returns the “default value” for a type.