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/forest_simple_demo.rs
• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/rag_in_memory.rs
• examples/agent_with_rag.rs
• examples/tool_builder_demo.rs
• examples/send_message_tool_demo.rs
• examples/complete_demo.rs
• examples/forest_of_agents.rs
• examples/forest_with_coordinator.rs

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

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/agent_with_file_tools.rs (line 52)

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

Additional examples can be found in:

• examples/agent_with_memory_db.rs
• examples/rag_in_memory.rs
• examples/agent_with_rag.rs
• examples/tool_builder_demo.rs
• examples/complete_demo.rs
• examples/forest_of_agents.rs

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.