Struct Agent 

pub struct Agent { /* private fields */ }

Represents an LLM-powered agent that can chat, use tools, and manage a conversation.

Implementations

impl Agent

pub fn builder(name: impl Into<String>) -> AgentBuilder

Returns a new AgentBuilder for constructing an agent.

Arguments

• name - The name of the agent.

Examples found in repository

examples/custom_tool.rs (line 79)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // Create an agent named "WeatherAgent" and equip it with the `WeatherTool`.
    let mut agent = Agent::builder("WeatherAgent")
        .config(config)
        .system_prompt("You are a helpful weather assistant. Use the weather tool to answer questions about weather.")
        .tool(Box::new(WeatherTool))
        .build()
        .await?;

    // --- Ask the agent about the weather ---
    let response = agent.chat("What's the weather like in New York?").await?;
    println!("Agent: {}\n", response);

    // --- Ask again, but with a different unit ---
    let response = agent.chat("How about in London, but in celsius?").await?;
    println!("Agent: {}\n", response);

    Ok(())
}

examples/agent_with_tools.rs (line 15)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // Create an agent named "ToolAgent" and equip it with the `CalculatorTool` and `EchoTool`.
    // Using the improved syntax to add multiple tools at once!
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .max_iterations(5)
        .build()
        .await?;

    println!(
        "Available tools: {:?}\n",
        agent.tool_registry().list_tools()
    );

    // --- Test the calculator tool ---
    let response = agent.chat("What is 25 * 4 + 10?").await?;
    println!("Agent: {}\n", response);

    // --- Test the echo tool ---
    let response = agent
        .chat("Can you echo this message: 'Hello from Helios!'")
        .await?;
    println!("Agent: {}\n", response);

    Ok(())
}

examples/serve_agent.rs (line 19)

async fn main() -> helios_engine::Result<()> {
    // Initialize tracing
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::INFO)
        .init();

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

    // Create an agent with tools
    let agent = Agent::builder("API Agent")
        .config(config)
        .system_prompt("You are a helpful AI assistant with access to a calculator tool.")
        .tool(Box::new(CalculatorTool))
        .max_iterations(5)
        .build()
        .await?;

    // Start the server
    println!("Starting server on http://127.0.0.1:8000");
    println!("Try: curl http://127.0.0.1:8000/v1/chat/completions \\");
    println!("  -H 'Content-Type: application/json' \\");
    println!("  -d '{{\"model\": \"local-model\", \"messages\": [{{\"role\": \"user\", \"content\": \"What is 15 * 7?\"}}]}}'");

    helios_engine::serve::start_server_with_agent(
        agent,
        "local-model".to_string(),
        "127.0.0.1:8000",
    )
    .await?;

    Ok(())
}

examples/basic_chat.rs (line 23)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Basic Chat Example");
    println!("=====================================");
    println!("💡 Streaming is enabled by default - watch tokens appear in real-time!\n");

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

    // Create a simple agent named "BasicAgent".
    let mut agent = Agent::builder("BasicAgent")
        .config(config)
        .system_prompt("You are a helpful assistant.")
        .build()
        .await?;

    // --- Send a message to the agent ---
    println!("User: Hello! How are you?");
    print!("Agent (streaming): ");
    io::stdout().flush()?;

    let _response = agent.chat("Hello! How are you?").await?;
    println!();

    // --- Continue the conversation ---
    println!("\nUser: What can you help me with?");
    print!("Agent (streaming): ");
    io::stdout().flush()?;

    let _response = agent.chat("What can you help me with?").await?;
    println!();

    println!("\n Demo completed! Notice how responses streamed in real-time.");

    Ok(())
}

examples/multiple_agents.rs (line 17)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // --- Create multiple agents with different personalities and tools ---

    // An agent specialized in math, equipped with a calculator tool.
    let mut math_agent = Agent::builder("MathAgent")
        .config(config.clone())
        .system_prompt("You are a math expert. You love numbers and equations.")
        .tool(Box::new(CalculatorTool))
        .build()
        .await?;

    // A creative agent for writing and storytelling.
    let mut creative_agent = Agent::builder("CreativeAgent")
        .config(config)
        .system_prompt("You are a creative writer who loves storytelling and poetry.")
        .build()
        .await?;

    // --- Interact with the Math Agent ---
    println!("=== Math Agent ===");
    let response = math_agent.chat("What is the square root of 144?").await?;
    println!("Math Agent: {}\n", response);

    // --- Interact with the Creative Agent ---
    println!("=== Creative Agent ===");
    let response = creative_agent
        .chat("Write a haiku about programming.")
        .await?;
    println!("Creative Agent: {}\n", response);

    Ok(())
}

examples/rag_qdrant_comparison.rs (line 32)

async fn demonstrate_in_memory() -> helios_engine::Result<()> {
    println!("=== IN-MEMORY RAG DEMONSTRATION ===\n");

    let api_key = std::env::var("OPENAI_API_KEY").unwrap_or_else(|_| {
        println!("⚠ Warning: OPENAI_API_KEY not set. Using placeholder.");
        "your-api-key-here".to_string()
    });

    let config = Config::from_file("config.toml").unwrap_or_else(|_| Config::new_default());

    // Create in-memory RAG tool
    let rag_tool = RAGTool::new_in_memory("https://api.openai.com/v1/embeddings", &api_key);

    let mut agent = Agent::builder("InMemoryAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with in-memory RAG capabilities.")
        .tool(Box::new(rag_tool))
        .max_iterations(8)
        .build()
        .await?;

    println!("✓ In-memory agent created\n");

    // Add some documents
    println!("Adding documents...");
    agent.chat("Store: The capital of France is Paris.").await?;
    agent
        .chat("Store: The capital of Germany is Berlin.")
        .await?;
    agent.chat("Store: The capital of Italy is Rome.").await?;
    println!("✓ Documents added\n");

    // Search
    println!("Searching...");
    let response = agent.chat("What is the capital of Germany?").await?;
    println!("Agent: {}\n", response);

    println!("Advantages of in-memory:");
    println!("  ✓ No external dependencies");
    println!("  ✓ Fast and simple");
    println!("  ✓ Perfect for development");
    println!("  ✗ No persistence (data lost on restart)");
    println!("  ✗ Limited scalability\n");

    Ok(())
}

async fn demonstrate_qdrant() -> helios_engine::Result<()> {
    println!("=== QDRANT RAG DEMONSTRATION ===\n");

    let api_key = std::env::var("OPENAI_API_KEY").unwrap_or_else(|_| {
        println!("⚠ Warning: OPENAI_API_KEY not set. Using placeholder.");
        "your-api-key-here".to_string()
    });

    let config = Config::from_file("config.toml").unwrap_or_else(|_| Config::new_default());

    // Create Qdrant RAG tool
    let rag_tool = RAGTool::new_qdrant(
        "http://localhost:6333",
        "comparison_demo",
        "https://api.openai.com/v1/embeddings",
        &api_key,
    );

    let mut agent = Agent::builder("QdrantAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with Qdrant RAG capabilities.")
        .tool(Box::new(rag_tool))
        .max_iterations(8)
        .build()
        .await?;

    println!("✓ Qdrant agent created\n");

    // Clear any existing data
    println!("Clearing existing data...");
    agent.chat("Clear all documents").await?;
    println!("✓ Cleared\n");

    // Add some documents
    println!("Adding documents...");
    agent
        .chat("Store: The Eiffel Tower is located in Paris, France.")
        .await?;
    agent
        .chat("Store: The Colosseum is located in Rome, Italy.")
        .await?;
    agent
        .chat("Store: The Brandenburg Gate is located in Berlin, Germany.")
        .await?;
    println!("✓ Documents added\n");

    // Search
    println!("Searching...");
    let response = agent.chat("What famous landmark is in Berlin?").await?;
    println!("Agent: {}\n", response);

    println!("Advantages of Qdrant:");
    println!("  ✓ Persistent storage");
    println!("  ✓ Highly scalable");
    println!("  ✓ Production-ready");
    println!("  ✓ Advanced features (filtering, etc.)");
    println!("  ✗ Requires external service");
    println!("  ✗ More complex setup\n");

    Ok(())
}

Additional examples can be found in:

• examples/serve_with_custom_endpoints.rs
• examples/react_agent.rs
• examples/forest_simple_demo.rs
• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/serve_simple_endpoints.rs
• examples/react_debugging.rs
• examples/react_comparison.rs
• examples/rag_in_memory.rs
• examples/ultra_simple.rs
• examples/agent_with_rag.rs
• examples/tool_builder_demo.rs
• examples/send_message_tool_demo.rs
• examples/complete_demo.rs
• examples/react_custom_prompt.rs
• examples/forest_of_agents.rs
• examples/forest_with_coordinator.rs

pub async fn quick(name: impl Into<String>) -> Result<Self>

Creates a quick-start agent with minimal configuration.

This is the simplest way to create an agent - just provide a name and it uses the default configuration (reads from config.toml if available, otherwise uses defaults).

Arguments

• name - The name of the agent.

Example

let mut agent = Agent::quick("MyAgent").await?;
let response = agent.chat("Hello!").await?;
println!("{}", response);

Examples found in repository

examples/quickstart.rs (line 13)

async fn main() -> helios_engine::Result<()> {
    println!("⚡ Helios Quick Start\n");

    // Step 1: Create an agent in ONE LINE (using auto config)
    let mut agent = Agent::quick("MyAgent").await?;
    println!("✓ Agent created");

    // Step 2: Ask a question
    let response = agent.ask("What's the capital of France?").await?;
    println!("Q: What's the capital of France?");
    println!("A: {}\n", response);

    // Step 3: Ask another question (agent remembers context!)
    let response2 = agent.ask("What's its population?").await?;
    println!("Q: What's its population?");
    println!("A: {}\n", response2);

    // That's it! You're using Helios! 🎉
    println!("✅ Done! Create an agent and chat - that simple!");

    Ok(())
}

examples/ultra_simple.rs (line 61)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Ultra Simple Helios Example\n");

    // ========== SIMPLEST AGENT CREATION ==========
    println!("1️⃣  Creating an agent - shortest possible syntax:\n");

    // One-liner: Create agent with auto config
    let mut agent = Agent::builder("Helper")
        .auto_config()
        .prompt("You are helpful and concise.")
        .build()
        .await?;

    println!("✓ Agent created!\n");

    // ========== SIMPLEST CHAT ==========
    println!("2️⃣  Asking questions - simplest possible:\n");

    // Use .ask() instead of .chat() for more natural syntax
    let answer = agent.ask("What is 2+2?").await?;
    println!("Q: What is 2+2?\nA: {}\n", answer);

    // ========== SIMPLEST CONFIG ==========
    println!("3️⃣  Creating config with shortest syntax:\n");

    // Ultra-short config creation
    let _config = Config::builder()
        .m("gpt-4") // .m() is shorthand for .model()
        .key("your-api-key") // .key() is shorthand for .api_key()
        .temp(0.8) // .temp() is shorthand for .temperature()
        .tokens(1024) // .tokens() is shorthand for .max_tokens()
        .build();

    println!("✓ Config created with ultra-short syntax!\n");

    // ========== SIMPLEST AGENT WITH TOOLS ==========
    println!("4️⃣  Agent with tools - simplest way:\n");

    let mut calc_agent = Agent::builder("Calculator")
        .auto_config()
        .prompt("You are a math expert.")
        .with_tool(Box::new(CalculatorTool)) // Add single tool
        .build()
        .await?;

    let result = calc_agent.ask("Calculate 15 * 7 + 5").await?;
    println!("Q: Calculate 15 * 7 + 5\nA: {}\n", result);

    // ========== SIMPLEST QUICK AGENT ==========
    println!("5️⃣  Quick agent - one method call:\n");

    // Agent::quick() creates agent in ONE LINE with auto config!
    let mut quick_agent = Agent::quick("QuickBot").await?;
    let quick_answer = quick_agent.ask("Say hello!").await?;
    println!("Response: {}\n", quick_answer);

    // ========== SIMPLEST CHAT MESSAGES ==========
    println!("6️⃣  Creating messages - super short syntax:\n");

    use helios_engine::ChatMessage;

    // Short aliases for message creation
    let _sys_msg = ChatMessage::sys("You are helpful"); // .sys() not .system()
    let _user_msg = ChatMessage::msg("Hello there"); // .msg() not .user()
    let _reply_msg = ChatMessage::reply("Hi! How can I help?"); // .reply() not .assistant()

    println!("✓ Messages created with ultra-short syntax!\n");

    // ========== SHORTEST AUTOFOREST ==========
    println!("7️⃣  AutoForest - simplest multi-agent orchestration:\n");

    use helios_engine::AutoForest;

    let mut forest = AutoForest::new(Config::builder().m("gpt-4").build())
        .with_tools(vec![Box::new(CalculatorTool)])
        .build()
        .await?;

    // Use .run() for shortest syntax
    let forest_result = forest.run("Analyze these numbers: 10, 20, 30, 40").await?;
    println!("Forest Result:\n{}\n", forest_result);

    // ========== COMPARISON TABLE ==========
    println!("📊 Syntax Comparison - Short vs Long:\n");
    println!("┌─────────────────────┬──────────────────────┬─────────────────┐");
    println!("│ Operation           │ Short Syntax         │ Long Syntax      │");
    println!("├─────────────────────┼──────────────────────┼─────────────────┤");
    println!("│ Create Agent        │ Agent::quick()       │ Agent::builder()│");
    println!("│ Ask Question        │ .ask()               │ .chat()          │");
    println!("│ System Prompt       │ .prompt()            │ .system_prompt() │");
    println!("│ Config Model        │ .m()                 │ .model()         │");
    println!("│ Config Key          │ .key()               │ .api_key()       │");
    println!("│ Config Temp         │ .temp()              │ .temperature()   │");
    println!("│ Config Tokens       │ .tokens()            │ .max_tokens()    │");
    println!("│ System Message      │ ChatMessage::sys()   │ ChatMessage::system()");
    println!("│ User Message        │ ChatMessage::msg()   │ ChatMessage::user()");
    println!("│ Assistant Message   │ ChatMessage::reply() │ ChatMessage::assistant()");
    println!("│ AutoForest Execute  │ .run()               │ .execute_task()  │");
    println!("└─────────────────────┴──────────────────────┴─────────────────┘\n");

    println!("✅ All examples completed!");
    println!("💡 Tip: Mix and match short and long syntax based on your preference!");

    Ok(())
}

pub fn name(&self) -> &str

Returns the name of the agent.

pub fn set_system_prompt(&mut self, prompt: impl Into<String>)

Sets the system prompt for the agent.

Arguments

• prompt - The system prompt to set.

pub fn register_tool(&mut self, tool: Box<dyn Tool>)

Registers a tool with the agent.

Arguments

• tool - The tool to register.

pub fn tool_registry(&self) -> &ToolRegistry

Returns a reference to the agent’s tool registry.

Examples found in repository

examples/agent_with_tools.rs (line 25)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // Create an agent named "ToolAgent" and equip it with the `CalculatorTool` and `EchoTool`.
    // Using the improved syntax to add multiple tools at once!
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .max_iterations(5)
        .build()
        .await?;

    println!(
        "Available tools: {:?}\n",
        agent.tool_registry().list_tools()
    );

    // --- Test the calculator tool ---
    let response = agent.chat("What is 25 * 4 + 10?").await?;
    println!("Agent: {}\n", response);

    // --- Test the echo tool ---
    let response = agent
        .chat("Can you echo this message: 'Hello from Helios!'")
        .await?;
    println!("Agent: {}\n", response);

    Ok(())
}

examples/react_agent.rs (line 37)

async fn main() -> helios_engine::Result<()> {
    println!("🧠 Helios Engine - ReAct Agent Example");
    println!("======================================\n");

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

    // Create an agent with ReAct mode enabled.
    // Notice the simple `.react()` call in the builder pattern!
    let mut agent = Agent::builder("ReActAgent")
        .config(config)
        .system_prompt(
            "You are a helpful assistant that thinks carefully before acting. \
             Use your reasoning to plan your approach.",
        )
        .tools(vec![
            Box::new(CalculatorTool),
            Box::new(EchoTool),
            Box::new(FileReadTool),
        ])
        .react() // Enable ReAct mode - that's all it takes!
        .max_iterations(5)
        .build()
        .await?;

    println!(
        "Available tools: {:?}\n",
        agent.tool_registry().list_tools()
    );

    println!("═══════════════════════════════════════════════════════════");
    println!("Example 1: Mathematical Problem");
    println!("═══════════════════════════════════════════════════════════\n");

    // --- Test 1: Math problem requiring reasoning ---
    println!("User: I need to calculate (25 * 4) + (100 / 5). Can you help?\n");
    let response = agent
        .chat("I need to calculate (25 * 4) + (100 / 5). Can you help?")
        .await?;
    println!("\nAgent: {}\n", response);

    println!("═══════════════════════════════════════════════════════════");
    println!("Example 2: Multi-step Task");
    println!("═══════════════════════════════════════════════════════════\n");

    // --- Test 2: Multi-step task ---
    println!("User: First calculate 15 * 7, then echo the result back to me.\n");
    let response = agent
        .chat("First calculate 15 * 7, then echo the result back to me.")
        .await?;
    println!("\nAgent: {}\n", response);

    println!("═══════════════════════════════════════════════════════════");
    println!(" ReAct Demo Complete!");
    println!("═══════════════════════════════════════════════════════════");
    println!("\nNotice how the agent:");
    println!("  1. 💭 First reasons about the task");
    println!("  2. 📋 Creates a plan");
    println!("  3. ⚡ Then executes the actions\n");
    println!("This leads to more thoughtful and systematic problem-solving!");

    Ok(())
}

examples/react_debugging.rs (line 41)

async fn main() -> helios_engine::Result<()> {
    println!("🔍 Helios Engine - ReAct for Debugging");
    println!("=======================================\n");

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

    // Create a ReAct agent with verbose reasoning
    let debug_prompt = r#"Debug this task step by step. For each step, explain:

1. CURRENT STATE: What information do I have?
2. NEXT ACTION: What should I do next?
3. REASONING: Why is this the right action?
4. EXPECTED RESULT: What should happen?
5. VALIDATION: How will I know if it worked?

Be extremely detailed in your thinking."#;

    let mut debug_agent = Agent::builder("DebugAgent")
        .config(config)
        .system_prompt("You are a debugging assistant who explains every decision.")
        .tools(vec![
            Box::new(CalculatorTool),
            Box::new(JsonParserTool),
            Box::new(FileReadTool),
        ])
        .react_with_prompt(debug_prompt)
        .max_iterations(15) // Allow more iterations for complex debugging
        .build()
        .await?;

    println!(
        "Available tools: {:?}\n",
        debug_agent.tool_registry().list_tools()
    );

    // Scenario 1: Tracing calculation steps
    println!("═══════════════════════════════════════════════════════════");
    println!("Scenario 1: Trace Complex Calculation");
    println!("═══════════════════════════════════════════════════════════\n");

    println!("Problem: Calculate the compound interest formula result");
    println!("Formula: A = P(1 + r)^n where P=1000, r=0.05, n=3\n");

    let response = debug_agent
        .chat("Calculate compound interest: Principal=1000, rate=0.05, time=3 years. Use A = P * (1 + r)^n")
        .await?;
    println!("\nAgent: {}\n", response);

    // Scenario 2: Understanding tool selection
    println!("═══════════════════════════════════════════════════════════");
    println!("Scenario 2: Tool Selection Reasoning");
    println!("═══════════════════════════════════════════════════════════\n");

    println!("Task: Parse JSON and extract a value, then perform calculation\n");

    let response = debug_agent
        .chat(r#"Parse this JSON: {"price": 25.50, "quantity": 4} and calculate the total cost"#)
        .await?;
    println!("\nAgent: {}\n", response);

    // Scenario 3: Error recovery reasoning
    println!("═══════════════════════════════════════════════════════════");
    println!("Scenario 3: Multi-Step Problem Solving");
    println!("═══════════════════════════════════════════════════════════\n");

    println!("Task: Calculate average of a series of operations\n");

    let response = debug_agent
        .chat("Calculate: (10 * 5) + (20 * 3) + (15 * 2), then divide by 3 to get the average")
        .await?;
    println!("\nAgent: {}\n", response);

    // Explanation
    println!("═══════════════════════════════════════════════════════════");
    println!("💡 Debugging Benefits");
    println!("═══════════════════════════════════════════════════════════\n");

    println!("ReAct mode helps you:");
    println!("  1. 🔍 See exactly what the agent is thinking");
    println!("  2. 🎯 Understand why it chose specific tools");
    println!("  3. 📋 Follow the step-by-step execution plan");
    println!("  4. 🐛 Identify where reasoning might go wrong");
    println!("  5. 🔧 Optimize prompts based on visible thinking\n");

    println!("Tips for debugging with ReAct:");
    println!("  • Use detailed custom prompts for more verbose reasoning");
    println!("  • Increase max_iterations for complex tasks");
    println!("  • Watch the '💭 ReAct Reasoning' output carefully");
    println!("  • Compare reasoning across different queries");
    println!("  • Adjust system prompts based on reasoning patterns\n");

    Ok(())
}

examples/react_comparison.rs (line 34)

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

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

    // Create two identical agents, one with ReAct and one without
    let mut standard_agent = Agent::builder("StandardAgent")
        .config(config1)
        .system_prompt("You are a helpful assistant with access to tools.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .build()
        .await?;

    let mut react_agent = Agent::builder("ReActAgent")
        .config(config2)
        .system_prompt("You are a helpful assistant with access to tools.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .react() // The only difference!
        .build()
        .await?;

    println!(
        "Tools available: {:?}\n",
        standard_agent.tool_registry().list_tools()
    );

    // Test Case 1: Simple calculation
    println!("═══════════════════════════════════════════════════════════");
    println!("Test Case 1: Simple Mathematical Calculation");
    println!("═══════════════════════════════════════════════════════════\n");

    let query1 = "What is 25 * 8?";
    println!("Query: {}\n", query1);

    println!("--- STANDARD AGENT ---");
    let response1 = standard_agent.chat(query1).await?;
    println!("Response: {}\n", response1);

    println!("--- REACT AGENT ---");
    let response2 = react_agent.chat(query1).await?;
    println!("Response: {}\n", response2);

    // Test Case 2: Multi-step problem
    println!("═══════════════════════════════════════════════════════════");
    println!("Test Case 2: Multi-Step Problem");
    println!("═══════════════════════════════════════════════════════════\n");

    let query2 = "Calculate (15 + 25) * 3, then echo the result";
    println!("Query: {}\n", query2);

    println!("--- STANDARD AGENT ---");
    let response3 = standard_agent.chat(query2).await?;
    println!("Response: {}\n", response3);

    println!("--- REACT AGENT ---");
    let response4 = react_agent.chat(query2).await?;
    println!("Response: {}\n", response4);

    // Test Case 3: Complex multi-tool task
    println!("═══════════════════════════════════════════════════════════");
    println!("Test Case 3: Complex Multi-Tool Task");
    println!("═══════════════════════════════════════════════════════════\n");

    let query3 =
        "First calculate 100 / 4, then multiply that by 3, and finally echo the final answer";
    println!("Query: {}\n", query3);

    println!("--- STANDARD AGENT ---");
    let response5 = standard_agent.chat(query3).await?;
    println!("Response: {}\n", response5);

    println!("--- REACT AGENT ---");
    let response6 = react_agent.chat(query3).await?;
    println!("Response: {}\n", response6);

    // Summary
    println!("═══════════════════════════════════════════════════════════");
    println!("📊 Comparison Summary");
    println!("═══════════════════════════════════════════════════════════\n");

    println!("STANDARD AGENT:");
    println!("  ✓ Faster execution (no reasoning overhead)");
    println!("  ✓ Direct tool usage");
    println!("  ✗ No visible thought process");
    println!("  ✗ May miss planning opportunities\n");

    println!("REACT AGENT:");
    println!("  ✓ Shows reasoning process (💭 ReAct Reasoning)");
    println!("  ✓ Systematic approach to problems");
    println!("  ✓ Better for complex tasks");
    println!("  ✗ Slightly slower (extra LLM call)\n");

    println!("WHEN TO USE:");
    println!("  → Standard: Simple, direct tasks where speed matters");
    println!("  → ReAct: Complex tasks, debugging, when you want transparency\n");

    Ok(())
}

pub fn tool_registry_mut(&mut self) -> &mut ToolRegistry

Returns a mutable reference to the agent’s tool registry.

pub fn chat_session(&self) -> &ChatSession

Returns a reference to the agent’s chat session.

Examples found in repository

examples/send_message_tool_demo.rs (line 145)

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

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 chat_session_mut(&mut self) -> &mut ChatSession

Returns a mutable reference to the agent’s chat session.

pub fn clear_history(&mut self)

Clears the agent’s chat history.

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

Sends a message to the agent and gets a response.

Arguments

• message - The message to send.

Returns

A Result containing the agent’s response.

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

A convenience method for sending a message to the agent.

Examples found in repository

examples/custom_tool.rs (line 87)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // Create an agent named "WeatherAgent" and equip it with the `WeatherTool`.
    let mut agent = Agent::builder("WeatherAgent")
        .config(config)
        .system_prompt("You are a helpful weather assistant. Use the weather tool to answer questions about weather.")
        .tool(Box::new(WeatherTool))
        .build()
        .await?;

    // --- Ask the agent about the weather ---
    let response = agent.chat("What's the weather like in New York?").await?;
    println!("Agent: {}\n", response);

    // --- Ask again, but with a different unit ---
    let response = agent.chat("How about in London, but in celsius?").await?;
    println!("Agent: {}\n", response);

    Ok(())
}

examples/agent_with_tools.rs (line 29)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // Create an agent named "ToolAgent" and equip it with the `CalculatorTool` and `EchoTool`.
    // Using the improved syntax to add multiple tools at once!
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .max_iterations(5)
        .build()
        .await?;

    println!(
        "Available tools: {:?}\n",
        agent.tool_registry().list_tools()
    );

    // --- Test the calculator tool ---
    let response = agent.chat("What is 25 * 4 + 10?").await?;
    println!("Agent: {}\n", response);

    // --- Test the echo tool ---
    let response = agent
        .chat("Can you echo this message: 'Hello from Helios!'")
        .await?;
    println!("Agent: {}\n", response);

    Ok(())
}

examples/basic_chat.rs (line 34)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Basic Chat Example");
    println!("=====================================");
    println!("💡 Streaming is enabled by default - watch tokens appear in real-time!\n");

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

    // Create a simple agent named "BasicAgent".
    let mut agent = Agent::builder("BasicAgent")
        .config(config)
        .system_prompt("You are a helpful assistant.")
        .build()
        .await?;

    // --- Send a message to the agent ---
    println!("User: Hello! How are you?");
    print!("Agent (streaming): ");
    io::stdout().flush()?;

    let _response = agent.chat("Hello! How are you?").await?;
    println!();

    // --- Continue the conversation ---
    println!("\nUser: What can you help me with?");
    print!("Agent (streaming): ");
    io::stdout().flush()?;

    let _response = agent.chat("What can you help me with?").await?;
    println!();

    println!("\n Demo completed! Notice how responses streamed in real-time.");

    Ok(())
}

examples/multiple_agents.rs (line 33)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // --- Create multiple agents with different personalities and tools ---

    // An agent specialized in math, equipped with a calculator tool.
    let mut math_agent = Agent::builder("MathAgent")
        .config(config.clone())
        .system_prompt("You are a math expert. You love numbers and equations.")
        .tool(Box::new(CalculatorTool))
        .build()
        .await?;

    // A creative agent for writing and storytelling.
    let mut creative_agent = Agent::builder("CreativeAgent")
        .config(config)
        .system_prompt("You are a creative writer who loves storytelling and poetry.")
        .build()
        .await?;

    // --- Interact with the Math Agent ---
    println!("=== Math Agent ===");
    let response = math_agent.chat("What is the square root of 144?").await?;
    println!("Math Agent: {}\n", response);

    // --- Interact with the Creative Agent ---
    println!("=== Creative Agent ===");
    let response = creative_agent
        .chat("Write a haiku about programming.")
        .await?;
    println!("Creative Agent: {}\n", response);

    Ok(())
}

examples/rag_qdrant_comparison.rs (line 44)

async fn demonstrate_in_memory() -> helios_engine::Result<()> {
    println!("=== IN-MEMORY RAG DEMONSTRATION ===\n");

    let api_key = std::env::var("OPENAI_API_KEY").unwrap_or_else(|_| {
        println!("⚠ Warning: OPENAI_API_KEY not set. Using placeholder.");
        "your-api-key-here".to_string()
    });

    let config = Config::from_file("config.toml").unwrap_or_else(|_| Config::new_default());

    // Create in-memory RAG tool
    let rag_tool = RAGTool::new_in_memory("https://api.openai.com/v1/embeddings", &api_key);

    let mut agent = Agent::builder("InMemoryAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with in-memory RAG capabilities.")
        .tool(Box::new(rag_tool))
        .max_iterations(8)
        .build()
        .await?;

    println!("✓ In-memory agent created\n");

    // Add some documents
    println!("Adding documents...");
    agent.chat("Store: The capital of France is Paris.").await?;
    agent
        .chat("Store: The capital of Germany is Berlin.")
        .await?;
    agent.chat("Store: The capital of Italy is Rome.").await?;
    println!("✓ Documents added\n");

    // Search
    println!("Searching...");
    let response = agent.chat("What is the capital of Germany?").await?;
    println!("Agent: {}\n", response);

    println!("Advantages of in-memory:");
    println!("  ✓ No external dependencies");
    println!("  ✓ Fast and simple");
    println!("  ✓ Perfect for development");
    println!("  ✗ No persistence (data lost on restart)");
    println!("  ✗ Limited scalability\n");

    Ok(())
}

async fn demonstrate_qdrant() -> helios_engine::Result<()> {
    println!("=== QDRANT RAG DEMONSTRATION ===\n");

    let api_key = std::env::var("OPENAI_API_KEY").unwrap_or_else(|_| {
        println!("⚠ Warning: OPENAI_API_KEY not set. Using placeholder.");
        "your-api-key-here".to_string()
    });

    let config = Config::from_file("config.toml").unwrap_or_else(|_| Config::new_default());

    // Create Qdrant RAG tool
    let rag_tool = RAGTool::new_qdrant(
        "http://localhost:6333",
        "comparison_demo",
        "https://api.openai.com/v1/embeddings",
        &api_key,
    );

    let mut agent = Agent::builder("QdrantAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with Qdrant RAG capabilities.")
        .tool(Box::new(rag_tool))
        .max_iterations(8)
        .build()
        .await?;

    println!("✓ Qdrant agent created\n");

    // Clear any existing data
    println!("Clearing existing data...");
    agent.chat("Clear all documents").await?;
    println!("✓ Cleared\n");

    // Add some documents
    println!("Adding documents...");
    agent
        .chat("Store: The Eiffel Tower is located in Paris, France.")
        .await?;
    agent
        .chat("Store: The Colosseum is located in Rome, Italy.")
        .await?;
    agent
        .chat("Store: The Brandenburg Gate is located in Berlin, Germany.")
        .await?;
    println!("✓ Documents added\n");

    // Search
    println!("Searching...");
    let response = agent.chat("What famous landmark is in Berlin?").await?;
    println!("Agent: {}\n", response);

    println!("Advantages of Qdrant:");
    println!("  ✓ Persistent storage");
    println!("  ✓ Highly scalable");
    println!("  ✓ Production-ready");
    println!("  ✓ Advanced features (filtering, etc.)");
    println!("  ✗ Requires external service");
    println!("  ✗ More complex setup\n");

    Ok(())
}

examples/react_agent.rs (line 47)

async fn main() -> helios_engine::Result<()> {
    println!("🧠 Helios Engine - ReAct Agent Example");
    println!("======================================\n");

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

    // Create an agent with ReAct mode enabled.
    // Notice the simple `.react()` call in the builder pattern!
    let mut agent = Agent::builder("ReActAgent")
        .config(config)
        .system_prompt(
            "You are a helpful assistant that thinks carefully before acting. \
             Use your reasoning to plan your approach.",
        )
        .tools(vec![
            Box::new(CalculatorTool),
            Box::new(EchoTool),
            Box::new(FileReadTool),
        ])
        .react() // Enable ReAct mode - that's all it takes!
        .max_iterations(5)
        .build()
        .await?;

    println!(
        "Available tools: {:?}\n",
        agent.tool_registry().list_tools()
    );

    println!("═══════════════════════════════════════════════════════════");
    println!("Example 1: Mathematical Problem");
    println!("═══════════════════════════════════════════════════════════\n");

    // --- Test 1: Math problem requiring reasoning ---
    println!("User: I need to calculate (25 * 4) + (100 / 5). Can you help?\n");
    let response = agent
        .chat("I need to calculate (25 * 4) + (100 / 5). Can you help?")
        .await?;
    println!("\nAgent: {}\n", response);

    println!("═══════════════════════════════════════════════════════════");
    println!("Example 2: Multi-step Task");
    println!("═══════════════════════════════════════════════════════════\n");

    // --- Test 2: Multi-step task ---
    println!("User: First calculate 15 * 7, then echo the result back to me.\n");
    let response = agent
        .chat("First calculate 15 * 7, then echo the result back to me.")
        .await?;
    println!("\nAgent: {}\n", response);

    println!("═══════════════════════════════════════════════════════════");
    println!(" ReAct Demo Complete!");
    println!("═══════════════════════════════════════════════════════════");
    println!("\nNotice how the agent:");
    println!("  1. 💭 First reasons about the task");
    println!("  2. 📋 Creates a plan");
    println!("  3. ⚡ Then executes the actions\n");
    println!("This leads to more thoughtful and systematic problem-solving!");

    Ok(())
}

Additional examples can be found in:

• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/react_debugging.rs
• examples/react_comparison.rs
• examples/rag_in_memory.rs
• examples/agent_with_rag.rs
• examples/tool_builder_demo.rs
• examples/complete_demo.rs
• examples/react_custom_prompt.rs
• examples/forest_of_agents.rs

pub async fn ask(&mut self, question: impl Into<String>) -> Result<String>

Ultra-simple alias for chat - just ask a question!

Examples found in repository

examples/quickstart.rs (line 17)

async fn main() -> helios_engine::Result<()> {
    println!("⚡ Helios Quick Start\n");

    // Step 1: Create an agent in ONE LINE (using auto config)
    let mut agent = Agent::quick("MyAgent").await?;
    println!("✓ Agent created");

    // Step 2: Ask a question
    let response = agent.ask("What's the capital of France?").await?;
    println!("Q: What's the capital of France?");
    println!("A: {}\n", response);

    // Step 3: Ask another question (agent remembers context!)
    let response2 = agent.ask("What's its population?").await?;
    println!("Q: What's its population?");
    println!("A: {}\n", response2);

    // That's it! You're using Helios! 🎉
    println!("✅ Done! Create an agent and chat - that simple!");

    Ok(())
}

examples/ultra_simple.rs (line 28)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Ultra Simple Helios Example\n");

    // ========== SIMPLEST AGENT CREATION ==========
    println!("1️⃣  Creating an agent - shortest possible syntax:\n");

    // One-liner: Create agent with auto config
    let mut agent = Agent::builder("Helper")
        .auto_config()
        .prompt("You are helpful and concise.")
        .build()
        .await?;

    println!("✓ Agent created!\n");

    // ========== SIMPLEST CHAT ==========
    println!("2️⃣  Asking questions - simplest possible:\n");

    // Use .ask() instead of .chat() for more natural syntax
    let answer = agent.ask("What is 2+2?").await?;
    println!("Q: What is 2+2?\nA: {}\n", answer);

    // ========== SIMPLEST CONFIG ==========
    println!("3️⃣  Creating config with shortest syntax:\n");

    // Ultra-short config creation
    let _config = Config::builder()
        .m("gpt-4") // .m() is shorthand for .model()
        .key("your-api-key") // .key() is shorthand for .api_key()
        .temp(0.8) // .temp() is shorthand for .temperature()
        .tokens(1024) // .tokens() is shorthand for .max_tokens()
        .build();

    println!("✓ Config created with ultra-short syntax!\n");

    // ========== SIMPLEST AGENT WITH TOOLS ==========
    println!("4️⃣  Agent with tools - simplest way:\n");

    let mut calc_agent = Agent::builder("Calculator")
        .auto_config()
        .prompt("You are a math expert.")
        .with_tool(Box::new(CalculatorTool)) // Add single tool
        .build()
        .await?;

    let result = calc_agent.ask("Calculate 15 * 7 + 5").await?;
    println!("Q: Calculate 15 * 7 + 5\nA: {}\n", result);

    // ========== SIMPLEST QUICK AGENT ==========
    println!("5️⃣  Quick agent - one method call:\n");

    // Agent::quick() creates agent in ONE LINE with auto config!
    let mut quick_agent = Agent::quick("QuickBot").await?;
    let quick_answer = quick_agent.ask("Say hello!").await?;
    println!("Response: {}\n", quick_answer);

    // ========== SIMPLEST CHAT MESSAGES ==========
    println!("6️⃣  Creating messages - super short syntax:\n");

    use helios_engine::ChatMessage;

    // Short aliases for message creation
    let _sys_msg = ChatMessage::sys("You are helpful"); // .sys() not .system()
    let _user_msg = ChatMessage::msg("Hello there"); // .msg() not .user()
    let _reply_msg = ChatMessage::reply("Hi! How can I help?"); // .reply() not .assistant()

    println!("✓ Messages created with ultra-short syntax!\n");

    // ========== SHORTEST AUTOFOREST ==========
    println!("7️⃣  AutoForest - simplest multi-agent orchestration:\n");

    use helios_engine::AutoForest;

    let mut forest = AutoForest::new(Config::builder().m("gpt-4").build())
        .with_tools(vec![Box::new(CalculatorTool)])
        .build()
        .await?;

    // Use .run() for shortest syntax
    let forest_result = forest.run("Analyze these numbers: 10, 20, 30, 40").await?;
    println!("Forest Result:\n{}\n", forest_result);

    // ========== COMPARISON TABLE ==========
    println!("📊 Syntax Comparison - Short vs Long:\n");
    println!("┌─────────────────────┬──────────────────────┬─────────────────┐");
    println!("│ Operation           │ Short Syntax         │ Long Syntax      │");
    println!("├─────────────────────┼──────────────────────┼─────────────────┤");
    println!("│ Create Agent        │ Agent::quick()       │ Agent::builder()│");
    println!("│ Ask Question        │ .ask()               │ .chat()          │");
    println!("│ System Prompt       │ .prompt()            │ .system_prompt() │");
    println!("│ Config Model        │ .m()                 │ .model()         │");
    println!("│ Config Key          │ .key()               │ .api_key()       │");
    println!("│ Config Temp         │ .temp()              │ .temperature()   │");
    println!("│ Config Tokens       │ .tokens()            │ .max_tokens()    │");
    println!("│ System Message      │ ChatMessage::sys()   │ ChatMessage::system()");
    println!("│ User Message        │ ChatMessage::msg()   │ ChatMessage::user()");
    println!("│ Assistant Message   │ ChatMessage::reply() │ ChatMessage::assistant()");
    println!("│ AutoForest Execute  │ .run()               │ .execute_task()  │");
    println!("└─────────────────────┴──────────────────────┴─────────────────┘\n");

    println!("✅ All examples completed!");
    println!("💡 Tip: Mix and match short and long syntax based on your preference!");

    Ok(())
}

pub fn with_system_prompt(self, prompt: impl Into<String>) -> Self

Sets system prompt and returns self for chaining

pub fn with_tool(self, tool: Box<dyn Tool>) -> Self

Registers a tool and returns self for chaining

pub fn with_tools(self, tools: Vec<Box<dyn Tool>>) -> Self

Registers multiple tools and returns self for chaining

pub fn set_max_iterations(&mut self, max: usize)

Sets the maximum number of iterations for tool execution.

Arguments

• max - The maximum number of iterations.

pub fn get_session_summary(&self) -> String

Returns a summary of the current chat session.

Examples found in repository

examples/agent_with_file_tools.rs (line 77)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Agent with File Tools Example");
    println!("=================================================\n");

    // Load configuration
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "FileAssistant" and equip it with file tools.
    let mut agent = Agent::builder("FileAssistant")
        .config(config)
        .system_prompt(
            "You are a helpful file management assistant. You can search for files, \
             read file contents, and edit files. Always confirm with the user before \
             making changes to files. Keep track of important session information.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with file tools");
    println!("✓ Available tools: file_search, file_read, file_edit, file_write\n");

    // Set initial session memory for the agent.
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("tasks_completed", "0");

    // --- Example 1: Search for Rust files ---
    println!("Example 1: Searching for Rust files");
    println!("====================================\n");

    let response = agent
        .chat("Find all Rust source files in the src directory")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_search");

    // --- Example 2: Read a specific file ---
    println!("\nExample 2: Reading file contents");
    println!("==================================\n");

    let response = agent
        .chat("Read the contents of src/lib.rs and give me a summary")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_read");

    // --- Example 3: Show session summary ---
    println!("\nExample 3: Session Summary");
    println!("==========================\n");

    println!("{}", agent.get_session_summary());

    // --- Example 4: Check session memory ---
    println!("\nExample 4: Checking Session Memory");
    println!("===================================\n");

    println!(
        "Working directory: {}",
        agent
            .get_memory("working_directory")
            .unwrap_or(&"unknown".to_string())
    );
    println!(
        "Tasks completed: {}",
        agent
            .get_memory("tasks_completed")
            .unwrap_or(&"0".to_string())
    );
    println!(
        "Last task: {}",
        agent.get_memory("last_task").unwrap_or(&"none".to_string())
    );

    println!("\n Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • File search with pattern matching and content search");
    println!("  • File reading with line range support");
    println!("  • File editing with find/replace functionality");
    println!("  • Session memory for tracking agent state");
    println!("  • Streaming responses (works with both local and remote models)");

    Ok(())
}

examples/complete_demo.rs (line 89)

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

    // Load configuration from `config.toml` or use default.
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "SmartAssistant" and equip it with all file tools.
    println!("📦 Creating agent with file tools...");
    let mut agent = Agent::builder("SmartAssistant")
        .config(config)
        .system_prompt(
            "You are an intelligent assistant with file management capabilities. \
             You can search files, read them, and make edits. Always explain what \
             you're doing and track important information in session memory.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created successfully!\n");

    // Initialize session memory with some starting values.
    println!("🧠 Initializing session memory...");
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("files_accessed", "0");
    agent.set_memory("edits_made", "0");
    println!("✓ Session memory initialized\n");

    // --- Demo 1: Search for files with streaming response ---
    println!("Demo 1: File Search with Streaming");
    println!("===================================");
    println!("User: Find all Rust example files\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response1 = agent
        .chat("Find all Rust example files in the examples directory")
        .await?;
    println!("{}\n", response1);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_search");

    // --- Demo 2: Read a file ---
    println!("\nDemo 2: Reading File Contents");
    println!("==============================");
    println!("User: Read the NEW_FEATURES.md file and summarize the key points\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response2 = agent
        .chat("Read the NEW_FEATURES.md file and give me a brief summary of what's new")
        .await?;
    println!("{}\n", response2);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_read");

    // --- Demo 3: Show session summary ---
    println!("\nDemo 3: Session Summary");
    println!("=======================\n");
    println!("{}", agent.get_session_summary());

    // --- Demo 4: Interactive mode ---
    println!("\n\nDemo 4: Interactive Mode");
    println!("========================");
    println!("You can now interact with the agent. Type 'exit' to quit.\n");

    loop {
        print!("\nYou: ");
        io::stdout().flush()?;

        let mut input = String::new();
        io::stdin().read_line(&mut input)?;
        let input = input.trim();

        if input.is_empty() {
            continue;
        }

        match input.to_lowercase().as_str() {
            "exit" | "quit" => {
                println!("\n👋 Goodbye!");
                break;
            }
            "summary" => {
                println!("\n📊 Session Summary:");
                println!("{}", agent.get_session_summary());
                continue;
            }
            "memory" => {
                println!("\n🧠 Session Memory:");
                if let Some(start) = agent.get_memory("session_start") {
                    println!("  Session started: {}", start);
                }
                if let Some(dir) = agent.get_memory("working_directory") {
                    println!("  Working directory: {}", dir);
                }
                if let Some(files) = agent.get_memory("files_accessed") {
                    println!("  Files accessed: {}", files);
                }
                if let Some(edits) = agent.get_memory("edits_made") {
                    println!("  Edits made: {}", edits);
                }
                if let Some(action) = agent.get_memory("last_action") {
                    println!("  Last action: {}", action);
                }
                continue;
            }
            "help" => {
                println!("\n📖 Available Commands:");
                println!("  exit, quit  - Exit the demo");
                println!("  summary     - Show session summary");
                println!("  memory      - Show session memory");
                println!("  help        - Show this help");
                println!("\n💡 Try asking the agent to:");
                println!("  • Search for specific files");
                println!("  • Read file contents");
                println!("  • Summarize what it has done");
                continue;
            }
            _ => {}
        }

        // Send message to agent with streaming.
        print!("\nAgent: ");
        io::stdout().flush()?;

        match agent.chat(input).await {
            Ok(response) => {
                println!("{}", response);

                // Update memory after each interaction.
                agent.increment_counter("files_accessed");
            }
            Err(e) => {
                eprintln!("\n❌ Error: {}", e);
            }
        }
    }

    // --- Final summary ---
    println!("\n📊 Final Session Summary:");
    println!("{}", agent.get_session_summary());

    println!("\n Demo completed successfully!");
    println!("\n💡 Features Demonstrated:");
    println!("  ✓ Streaming responses (local/remote models)");
    println!("  ✓ File search with pattern matching");
    println!("  ✓ File reading with summaries");
    println!("  ✓ Session memory tracking");
    println!("  ✓ Interactive conversation");
    println!("  ✓ Real-time progress updates");

    Ok(())
}

pub fn clear_memory(&mut self)

Clears the agent’s memory (agent-scoped metadata).

pub fn set_memory(&mut self, key: impl Into<String>, value: impl Into<String>)

Sets a value in the agent’s memory.

Examples found in repository

examples/agent_with_file_tools.rs (line 40)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Agent with File Tools Example");
    println!("=================================================\n");

    // Load configuration
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "FileAssistant" and equip it with file tools.
    let mut agent = Agent::builder("FileAssistant")
        .config(config)
        .system_prompt(
            "You are a helpful file management assistant. You can search for files, \
             read file contents, and edit files. Always confirm with the user before \
             making changes to files. Keep track of important session information.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with file tools");
    println!("✓ Available tools: file_search, file_read, file_edit, file_write\n");

    // Set initial session memory for the agent.
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("tasks_completed", "0");

    // --- Example 1: Search for Rust files ---
    println!("Example 1: Searching for Rust files");
    println!("====================================\n");

    let response = agent
        .chat("Find all Rust source files in the src directory")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_search");

    // --- Example 2: Read a specific file ---
    println!("\nExample 2: Reading file contents");
    println!("==================================\n");

    let response = agent
        .chat("Read the contents of src/lib.rs and give me a summary")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_read");

    // --- Example 3: Show session summary ---
    println!("\nExample 3: Session Summary");
    println!("==========================\n");

    println!("{}", agent.get_session_summary());

    // --- Example 4: Check session memory ---
    println!("\nExample 4: Checking Session Memory");
    println!("===================================\n");

    println!(
        "Working directory: {}",
        agent
            .get_memory("working_directory")
            .unwrap_or(&"unknown".to_string())
    );
    println!(
        "Tasks completed: {}",
        agent
            .get_memory("tasks_completed")
            .unwrap_or(&"0".to_string())
    );
    println!(
        "Last task: {}",
        agent.get_memory("last_task").unwrap_or(&"none".to_string())
    );

    println!("\n Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • File search with pattern matching and content search");
    println!("  • File reading with line range support");
    println!("  • File editing with find/replace functionality");
    println!("  • Session memory for tracking agent state");
    println!("  • Streaming responses (works with both local and remote models)");

    Ok(())
}

examples/complete_demo.rs (line 43)

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

    // Load configuration from `config.toml` or use default.
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "SmartAssistant" and equip it with all file tools.
    println!("📦 Creating agent with file tools...");
    let mut agent = Agent::builder("SmartAssistant")
        .config(config)
        .system_prompt(
            "You are an intelligent assistant with file management capabilities. \
             You can search files, read them, and make edits. Always explain what \
             you're doing and track important information in session memory.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created successfully!\n");

    // Initialize session memory with some starting values.
    println!("🧠 Initializing session memory...");
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("files_accessed", "0");
    agent.set_memory("edits_made", "0");
    println!("✓ Session memory initialized\n");

    // --- Demo 1: Search for files with streaming response ---
    println!("Demo 1: File Search with Streaming");
    println!("===================================");
    println!("User: Find all Rust example files\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response1 = agent
        .chat("Find all Rust example files in the examples directory")
        .await?;
    println!("{}\n", response1);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_search");

    // --- Demo 2: Read a file ---
    println!("\nDemo 2: Reading File Contents");
    println!("==============================");
    println!("User: Read the NEW_FEATURES.md file and summarize the key points\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response2 = agent
        .chat("Read the NEW_FEATURES.md file and give me a brief summary of what's new")
        .await?;
    println!("{}\n", response2);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_read");

    // --- Demo 3: Show session summary ---
    println!("\nDemo 3: Session Summary");
    println!("=======================\n");
    println!("{}", agent.get_session_summary());

    // --- Demo 4: Interactive mode ---
    println!("\n\nDemo 4: Interactive Mode");
    println!("========================");
    println!("You can now interact with the agent. Type 'exit' to quit.\n");

    loop {
        print!("\nYou: ");
        io::stdout().flush()?;

        let mut input = String::new();
        io::stdin().read_line(&mut input)?;
        let input = input.trim();

        if input.is_empty() {
            continue;
        }

        match input.to_lowercase().as_str() {
            "exit" | "quit" => {
                println!("\n👋 Goodbye!");
                break;
            }
            "summary" => {
                println!("\n📊 Session Summary:");
                println!("{}", agent.get_session_summary());
                continue;
            }
            "memory" => {
                println!("\n🧠 Session Memory:");
                if let Some(start) = agent.get_memory("session_start") {
                    println!("  Session started: {}", start);
                }
                if let Some(dir) = agent.get_memory("working_directory") {
                    println!("  Working directory: {}", dir);
                }
                if let Some(files) = agent.get_memory("files_accessed") {
                    println!("  Files accessed: {}", files);
                }
                if let Some(edits) = agent.get_memory("edits_made") {
                    println!("  Edits made: {}", edits);
                }
                if let Some(action) = agent.get_memory("last_action") {
                    println!("  Last action: {}", action);
                }
                continue;
            }
            "help" => {
                println!("\n📖 Available Commands:");
                println!("  exit, quit  - Exit the demo");
                println!("  summary     - Show session summary");
                println!("  memory      - Show session memory");
                println!("  help        - Show this help");
                println!("\n💡 Try asking the agent to:");
                println!("  • Search for specific files");
                println!("  • Read file contents");
                println!("  • Summarize what it has done");
                continue;
            }
            _ => {}
        }

        // Send message to agent with streaming.
        print!("\nAgent: ");
        io::stdout().flush()?;

        match agent.chat(input).await {
            Ok(response) => {
                println!("{}", response);

                // Update memory after each interaction.
                agent.increment_counter("files_accessed");
            }
            Err(e) => {
                eprintln!("\n❌ Error: {}", e);
            }
        }
    }

    // --- Final summary ---
    println!("\n📊 Final Session Summary:");
    println!("{}", agent.get_session_summary());

    println!("\n Demo completed successfully!");
    println!("\n💡 Features Demonstrated:");
    println!("  ✓ Streaming responses (local/remote models)");
    println!("  ✓ File search with pattern matching");
    println!("  ✓ File reading with summaries");
    println!("  ✓ Session memory tracking");
    println!("  ✓ Interactive conversation");
    println!("  ✓ Real-time progress updates");

    Ok(())
}

pub fn get_memory(&self, key: &str) -> Option<&String>

Gets a value from the agent’s memory.

Examples found in repository

examples/agent_with_file_tools.rs (line 86)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Agent with File Tools Example");
    println!("=================================================\n");

    // Load configuration
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "FileAssistant" and equip it with file tools.
    let mut agent = Agent::builder("FileAssistant")
        .config(config)
        .system_prompt(
            "You are a helpful file management assistant. You can search for files, \
             read file contents, and edit files. Always confirm with the user before \
             making changes to files. Keep track of important session information.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with file tools");
    println!("✓ Available tools: file_search, file_read, file_edit, file_write\n");

    // Set initial session memory for the agent.
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("tasks_completed", "0");

    // --- Example 1: Search for Rust files ---
    println!("Example 1: Searching for Rust files");
    println!("====================================\n");

    let response = agent
        .chat("Find all Rust source files in the src directory")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_search");

    // --- Example 2: Read a specific file ---
    println!("\nExample 2: Reading file contents");
    println!("==================================\n");

    let response = agent
        .chat("Read the contents of src/lib.rs and give me a summary")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_read");

    // --- Example 3: Show session summary ---
    println!("\nExample 3: Session Summary");
    println!("==========================\n");

    println!("{}", agent.get_session_summary());

    // --- Example 4: Check session memory ---
    println!("\nExample 4: Checking Session Memory");
    println!("===================================\n");

    println!(
        "Working directory: {}",
        agent
            .get_memory("working_directory")
            .unwrap_or(&"unknown".to_string())
    );
    println!(
        "Tasks completed: {}",
        agent
            .get_memory("tasks_completed")
            .unwrap_or(&"0".to_string())
    );
    println!(
        "Last task: {}",
        agent.get_memory("last_task").unwrap_or(&"none".to_string())
    );

    println!("\n Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • File search with pattern matching and content search");
    println!("  • File reading with line range support");
    println!("  • File editing with find/replace functionality");
    println!("  • Session memory for tracking agent state");
    println!("  • Streaming responses (works with both local and remote models)");

    Ok(())
}

examples/complete_demo.rs (line 120)

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

    // Load configuration from `config.toml` or use default.
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "SmartAssistant" and equip it with all file tools.
    println!("📦 Creating agent with file tools...");
    let mut agent = Agent::builder("SmartAssistant")
        .config(config)
        .system_prompt(
            "You are an intelligent assistant with file management capabilities. \
             You can search files, read them, and make edits. Always explain what \
             you're doing and track important information in session memory.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created successfully!\n");

    // Initialize session memory with some starting values.
    println!("🧠 Initializing session memory...");
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("files_accessed", "0");
    agent.set_memory("edits_made", "0");
    println!("✓ Session memory initialized\n");

    // --- Demo 1: Search for files with streaming response ---
    println!("Demo 1: File Search with Streaming");
    println!("===================================");
    println!("User: Find all Rust example files\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response1 = agent
        .chat("Find all Rust example files in the examples directory")
        .await?;
    println!("{}\n", response1);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_search");

    // --- Demo 2: Read a file ---
    println!("\nDemo 2: Reading File Contents");
    println!("==============================");
    println!("User: Read the NEW_FEATURES.md file and summarize the key points\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response2 = agent
        .chat("Read the NEW_FEATURES.md file and give me a brief summary of what's new")
        .await?;
    println!("{}\n", response2);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_read");

    // --- Demo 3: Show session summary ---
    println!("\nDemo 3: Session Summary");
    println!("=======================\n");
    println!("{}", agent.get_session_summary());

    // --- Demo 4: Interactive mode ---
    println!("\n\nDemo 4: Interactive Mode");
    println!("========================");
    println!("You can now interact with the agent. Type 'exit' to quit.\n");

    loop {
        print!("\nYou: ");
        io::stdout().flush()?;

        let mut input = String::new();
        io::stdin().read_line(&mut input)?;
        let input = input.trim();

        if input.is_empty() {
            continue;
        }

        match input.to_lowercase().as_str() {
            "exit" | "quit" => {
                println!("\n👋 Goodbye!");
                break;
            }
            "summary" => {
                println!("\n📊 Session Summary:");
                println!("{}", agent.get_session_summary());
                continue;
            }
            "memory" => {
                println!("\n🧠 Session Memory:");
                if let Some(start) = agent.get_memory("session_start") {
                    println!("  Session started: {}", start);
                }
                if let Some(dir) = agent.get_memory("working_directory") {
                    println!("  Working directory: {}", dir);
                }
                if let Some(files) = agent.get_memory("files_accessed") {
                    println!("  Files accessed: {}", files);
                }
                if let Some(edits) = agent.get_memory("edits_made") {
                    println!("  Edits made: {}", edits);
                }
                if let Some(action) = agent.get_memory("last_action") {
                    println!("  Last action: {}", action);
                }
                continue;
            }
            "help" => {
                println!("\n📖 Available Commands:");
                println!("  exit, quit  - Exit the demo");
                println!("  summary     - Show session summary");
                println!("  memory      - Show session memory");
                println!("  help        - Show this help");
                println!("\n💡 Try asking the agent to:");
                println!("  • Search for specific files");
                println!("  • Read file contents");
                println!("  • Summarize what it has done");
                continue;
            }
            _ => {}
        }

        // Send message to agent with streaming.
        print!("\nAgent: ");
        io::stdout().flush()?;

        match agent.chat(input).await {
            Ok(response) => {
                println!("{}", response);

                // Update memory after each interaction.
                agent.increment_counter("files_accessed");
            }
            Err(e) => {
                eprintln!("\n❌ Error: {}", e);
            }
        }
    }

    // --- Final summary ---
    println!("\n📊 Final Session Summary:");
    println!("{}", agent.get_session_summary());

    println!("\n Demo completed successfully!");
    println!("\n💡 Features Demonstrated:");
    println!("  ✓ Streaming responses (local/remote models)");
    println!("  ✓ File search with pattern matching");
    println!("  ✓ File reading with summaries");
    println!("  ✓ Session memory tracking");
    println!("  ✓ Interactive conversation");
    println!("  ✓ Real-time progress updates");

    Ok(())
}

pub fn remove_memory(&mut self, key: &str) -> Option<String>

Removes a value from the agent’s memory.

pub fn increment_counter(&mut self, key: &str) -> u32

Increments a counter in the agent’s memory.

Examples found in repository

examples/complete_demo.rs (line 66)

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

    // Load configuration from `config.toml` or use default.
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "SmartAssistant" and equip it with all file tools.
    println!("📦 Creating agent with file tools...");
    let mut agent = Agent::builder("SmartAssistant")
        .config(config)
        .system_prompt(
            "You are an intelligent assistant with file management capabilities. \
             You can search files, read them, and make edits. Always explain what \
             you're doing and track important information in session memory.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created successfully!\n");

    // Initialize session memory with some starting values.
    println!("🧠 Initializing session memory...");
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("files_accessed", "0");
    agent.set_memory("edits_made", "0");
    println!("✓ Session memory initialized\n");

    // --- Demo 1: Search for files with streaming response ---
    println!("Demo 1: File Search with Streaming");
    println!("===================================");
    println!("User: Find all Rust example files\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response1 = agent
        .chat("Find all Rust example files in the examples directory")
        .await?;
    println!("{}\n", response1);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_search");

    // --- Demo 2: Read a file ---
    println!("\nDemo 2: Reading File Contents");
    println!("==============================");
    println!("User: Read the NEW_FEATURES.md file and summarize the key points\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response2 = agent
        .chat("Read the NEW_FEATURES.md file and give me a brief summary of what's new")
        .await?;
    println!("{}\n", response2);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_read");

    // --- Demo 3: Show session summary ---
    println!("\nDemo 3: Session Summary");
    println!("=======================\n");
    println!("{}", agent.get_session_summary());

    // --- Demo 4: Interactive mode ---
    println!("\n\nDemo 4: Interactive Mode");
    println!("========================");
    println!("You can now interact with the agent. Type 'exit' to quit.\n");

    loop {
        print!("\nYou: ");
        io::stdout().flush()?;

        let mut input = String::new();
        io::stdin().read_line(&mut input)?;
        let input = input.trim();

        if input.is_empty() {
            continue;
        }

        match input.to_lowercase().as_str() {
            "exit" | "quit" => {
                println!("\n👋 Goodbye!");
                break;
            }
            "summary" => {
                println!("\n📊 Session Summary:");
                println!("{}", agent.get_session_summary());
                continue;
            }
            "memory" => {
                println!("\n🧠 Session Memory:");
                if let Some(start) = agent.get_memory("session_start") {
                    println!("  Session started: {}", start);
                }
                if let Some(dir) = agent.get_memory("working_directory") {
                    println!("  Working directory: {}", dir);
                }
                if let Some(files) = agent.get_memory("files_accessed") {
                    println!("  Files accessed: {}", files);
                }
                if let Some(edits) = agent.get_memory("edits_made") {
                    println!("  Edits made: {}", edits);
                }
                if let Some(action) = agent.get_memory("last_action") {
                    println!("  Last action: {}", action);
                }
                continue;
            }
            "help" => {
                println!("\n📖 Available Commands:");
                println!("  exit, quit  - Exit the demo");
                println!("  summary     - Show session summary");
                println!("  memory      - Show session memory");
                println!("  help        - Show this help");
                println!("\n💡 Try asking the agent to:");
                println!("  • Search for specific files");
                println!("  • Read file contents");
                println!("  • Summarize what it has done");
                continue;
            }
            _ => {}
        }

        // Send message to agent with streaming.
        print!("\nAgent: ");
        io::stdout().flush()?;

        match agent.chat(input).await {
            Ok(response) => {
                println!("{}", response);

                // Update memory after each interaction.
                agent.increment_counter("files_accessed");
            }
            Err(e) => {
                eprintln!("\n❌ Error: {}", e);
            }
        }
    }

    // --- Final summary ---
    println!("\n📊 Final Session Summary:");
    println!("{}", agent.get_session_summary());

    println!("\n Demo completed successfully!");
    println!("\n💡 Features Demonstrated:");
    println!("  ✓ Streaming responses (local/remote models)");
    println!("  ✓ File search with pattern matching");
    println!("  ✓ File reading with summaries");
    println!("  ✓ Session memory tracking");
    println!("  ✓ Interactive conversation");
    println!("  ✓ Real-time progress updates");

    Ok(())
}

pub fn increment_tasks_completed(&mut self) -> u32

Increments the “tasks_completed” counter in the agent’s memory.

Examples found in repository

examples/agent_with_file_tools.rs (line 57)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Agent with File Tools Example");
    println!("=================================================\n");

    // Load configuration
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "FileAssistant" and equip it with file tools.
    let mut agent = Agent::builder("FileAssistant")
        .config(config)
        .system_prompt(
            "You are a helpful file management assistant. You can search for files, \
             read file contents, and edit files. Always confirm with the user before \
             making changes to files. Keep track of important session information.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with file tools");
    println!("✓ Available tools: file_search, file_read, file_edit, file_write\n");

    // Set initial session memory for the agent.
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("tasks_completed", "0");

    // --- Example 1: Search for Rust files ---
    println!("Example 1: Searching for Rust files");
    println!("====================================\n");

    let response = agent
        .chat("Find all Rust source files in the src directory")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_search");

    // --- Example 2: Read a specific file ---
    println!("\nExample 2: Reading file contents");
    println!("==================================\n");

    let response = agent
        .chat("Read the contents of src/lib.rs and give me a summary")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_read");

    // --- Example 3: Show session summary ---
    println!("\nExample 3: Session Summary");
    println!("==========================\n");

    println!("{}", agent.get_session_summary());

    // --- Example 4: Check session memory ---
    println!("\nExample 4: Checking Session Memory");
    println!("===================================\n");

    println!(
        "Working directory: {}",
        agent
            .get_memory("working_directory")
            .unwrap_or(&"unknown".to_string())
    );
    println!(
        "Tasks completed: {}",
        agent
            .get_memory("tasks_completed")
            .unwrap_or(&"0".to_string())
    );
    println!(
        "Last task: {}",
        agent.get_memory("last_task").unwrap_or(&"none".to_string())
    );

    println!("\n Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • File search with pattern matching and content search");
    println!("  • File reading with line range support");
    println!("  • File editing with find/replace functionality");
    println!("  • Session memory for tracking agent state");
    println!("  • Streaming responses (works with both local and remote models)");

    Ok(())
}

pub async fn chat_with_history( &mut self, messages: Vec<ChatMessage>, temperature: Option<f32>, max_tokens: Option<u32>, stop: Option<Vec<String>>, ) -> Result<String>

Executes a stateless conversation with the provided message history.

This method creates a temporary chat session with the provided messages and executes the agent logic without modifying the agent’s persistent session. This is useful for OpenAI API compatibility where each request contains the full conversation history.

Arguments

• messages - The complete conversation history for this request
• temperature - Optional temperature parameter for generation
• max_tokens - Optional maximum tokens parameter for generation
• stop - Optional stop sequences for generation

Returns

A Result containing the assistant’s response content.

pub async fn chat_stream_with_history<F>( &mut self, messages: Vec<ChatMessage>, temperature: Option<f32>, max_tokens: Option<u32>, stop: Option<Vec<String>>, on_chunk: F, ) -> Result<ChatMessage>

where F: FnMut(&str) + Send,

Executes a stateless conversation with the provided message history and streams the response.

This method creates a temporary chat session with the provided messages and streams the agent’s response in real-time as tokens are generated. Note: Tool calls are not supported in streaming mode yet - they will be executed after the initial response is complete.

Arguments

• messages - The complete conversation history for this request
• temperature - Optional temperature parameter for generation
• max_tokens - Optional maximum tokens parameter for generation
• stop - Optional stop sequences for generation
• on_chunk - Callback function called for each chunk of generated text

Returns

A Result containing the final assistant message after streaming is complete.