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/basic_chat.rs (line 15)

async fn main() -> helios_engine::Result<()> {
    // 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 ---
    let response = agent.chat("Hello! How are you?").await?;
    println!("Agent: {}", response);

    // --- Continue the conversation ---
    let response = agent.chat("What can you help me with?").await?;
    println!("Agent: {}", response);

    Ok(())
}

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

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`.
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tool(Box::new(CalculatorTool))
        .tool(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/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/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/rag_in_memory.rs
• examples/agent_with_rag.rs
• examples/complete_demo.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`.
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tool(Box::new(CalculatorTool))
        .tool(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.

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/basic_chat.rs (line 22)

async fn main() -> helios_engine::Result<()> {
    // 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 ---
    let response = agent.chat("Hello! How are you?").await?;
    println!("Agent: {}", response);

    // --- Continue the conversation ---
    let response = agent.chat("What can you help me with?").await?;
    println!("Agent: {}", response);

    Ok(())
}

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`.
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tool(Box::new(CalculatorTool))
        .tool(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/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/complete_demo.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.