Struct ForestBuilder 

pub struct ForestBuilder { /* private fields */ }

Builder for creating a Forest of Agents with multiple agents.

Implementations

impl ForestBuilder

pub fn new() -> Self

Creates a new ForestBuilder.

Examples found in repository

examples/forest_simple_demo.rs (line 15)

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/send_message_tool_demo.rs (line 28)

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 29)

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 26)

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 fn config(self, config: Config) -> Self

Sets the configuration for all agents in the forest.

Examples found in repository

examples/forest_simple_demo.rs (line 16)

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/send_message_tool_demo.rs (line 29)

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 30)

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 27)

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 fn agent(self, id: AgentId, builder: AgentBuilder) -> Self

Adds an agent to the forest with a builder.

Examples found in repository

examples/forest_simple_demo.rs (lines 17-28)

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/send_message_tool_demo.rs (lines 30-34)

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_with_coordinator.rs (lines 29-52)

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 fn agents(self, agents: Vec<(AgentId, AgentBuilder)>) -> Self

Adds multiple agents to the forest at once.

Example

let forest = ForestBuilder::new()
    .config(config)
    .agents(vec![
        ("worker1".to_string(), Agent::builder("worker1")),
        ("worker2".to_string(), Agent::builder("worker2")),
    ])
    .build()
    .await?;

Examples found in repository

examples/forest_of_agents.rs (lines 31-92)

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 max_iterations(self, max: usize) -> Self

Sets the maximum iterations for agent interactions.

Examples found in repository

examples/forest_simple_demo.rs (line 47)

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/send_message_tool_demo.rs (line 40)

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 93)

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 129)

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 build(self) -> Result<ForestOfAgents>

Builds the Forest of Agents.

Examples found in repository

examples/forest_simple_demo.rs (line 48)

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/send_message_tool_demo.rs (line 41)

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 94)

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 130)

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(())
}

Trait Implementations

impl Default for ForestBuilder

fn default() -> Self

Returns the “default value” for a type.