Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Implementations

impl AgentBuilder

pub fn new(name: impl Into<String>) -> Self

pub fn config(self, config: Config) -> Self

Examples found in repository

examples/basic_chat.rs (line 16)

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

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`.
    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 20)

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

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/serve_with_custom_endpoints.rs (line 20)

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?;

    // Define custom endpoints
    let custom_endpoints = CustomEndpointsConfig {
        endpoints: vec![
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/version".to_string(),
                response: serde_json::json!({
                    "version": "0.2.8",
                    "service": "Helios Engine",
                    "features": ["agents", "tools", "streaming", "custom_endpoints"]
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/status".to_string(),
                response: serde_json::json!({
                    "status": "operational",
                    "uptime": "unknown",
                    "model": "agent-based"
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "POST".to_string(),
                path: "/api/echo".to_string(),
                response: serde_json::json!({
                    "message": "Echo endpoint - this returns static data",
                    "note": "For dynamic responses, use the chat completions endpoint"
                }),
                status_code: 200,
            },
        ],
    };

    // Start the server with custom endpoints
    println!("Starting server on http://127.0.0.1:8000");
    println!("📡 OpenAI-compatible API endpoints:");
    println!("   POST /v1/chat/completions");
    println!("   GET  /v1/models");
    println!("📡 Custom endpoints:");
    println!("   GET  /api/version");
    println!("   GET  /api/status");
    println!("   POST /api/echo");
    println!();
    println!("Try: curl http://127.0.0.1:8000/api/version");

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

    Ok(())
}

Additional examples can be found in:

• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/agent_with_rag.rs
• examples/complete_demo.rs

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

Examples found in repository

examples/basic_chat.rs (line 17)

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

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

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

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

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/serve_with_custom_endpoints.rs (line 21)

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?;

    // Define custom endpoints
    let custom_endpoints = CustomEndpointsConfig {
        endpoints: vec![
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/version".to_string(),
                response: serde_json::json!({
                    "version": "0.2.8",
                    "service": "Helios Engine",
                    "features": ["agents", "tools", "streaming", "custom_endpoints"]
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/status".to_string(),
                response: serde_json::json!({
                    "status": "operational",
                    "uptime": "unknown",
                    "model": "agent-based"
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "POST".to_string(),
                path: "/api/echo".to_string(),
                response: serde_json::json!({
                    "message": "Echo endpoint - this returns static data",
                    "note": "For dynamic responses, use the chat completions endpoint"
                }),
                status_code: 200,
            },
        ],
    };

    // Start the server with custom endpoints
    println!("Starting server on http://127.0.0.1:8000");
    println!("📡 OpenAI-compatible API endpoints:");
    println!("   POST /v1/chat/completions");
    println!("   GET  /v1/models");
    println!("📡 Custom endpoints:");
    println!("   GET  /api/version");
    println!("   GET  /api/status");
    println!("   POST /api/echo");
    println!();
    println!("Try: curl http://127.0.0.1:8000/api/version");

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

    Ok(())
}

Additional examples can be found in:

• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/agent_with_rag.rs
• examples/complete_demo.rs

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

Examples found in repository

examples/custom_tool.rs (line 82)

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

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

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

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

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?;

    // Define custom endpoints
    let custom_endpoints = CustomEndpointsConfig {
        endpoints: vec![
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/version".to_string(),
                response: serde_json::json!({
                    "version": "0.2.8",
                    "service": "Helios Engine",
                    "features": ["agents", "tools", "streaming", "custom_endpoints"]
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/status".to_string(),
                response: serde_json::json!({
                    "status": "operational",
                    "uptime": "unknown",
                    "model": "agent-based"
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "POST".to_string(),
                path: "/api/echo".to_string(),
                response: serde_json::json!({
                    "message": "Echo endpoint - this returns static data",
                    "note": "For dynamic responses, use the chat completions endpoint"
                }),
                status_code: 200,
            },
        ],
    };

    // Start the server with custom endpoints
    println!("Starting server on http://127.0.0.1:8000");
    println!("📡 OpenAI-compatible API endpoints:");
    println!("   POST /v1/chat/completions");
    println!("   GET  /v1/models");
    println!("📡 Custom endpoints:");
    println!("   GET  /api/version");
    println!("   GET  /api/status");
    println!("   POST /api/echo");
    println!();
    println!("Try: curl http://127.0.0.1:8000/api/version");

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

    Ok(())
}

examples/agent_with_file_tools.rs (line 28)

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/agent_with_rag.rs
• examples/complete_demo.rs

pub fn max_iterations(self, max: usize) -> Self

Examples found in repository

examples/agent_with_tools.rs (line 19)

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

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/serve_with_custom_endpoints.rs (line 23)

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?;

    // Define custom endpoints
    let custom_endpoints = CustomEndpointsConfig {
        endpoints: vec![
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/version".to_string(),
                response: serde_json::json!({
                    "version": "0.2.8",
                    "service": "Helios Engine",
                    "features": ["agents", "tools", "streaming", "custom_endpoints"]
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/status".to_string(),
                response: serde_json::json!({
                    "status": "operational",
                    "uptime": "unknown",
                    "model": "agent-based"
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "POST".to_string(),
                path: "/api/echo".to_string(),
                response: serde_json::json!({
                    "message": "Echo endpoint - this returns static data",
                    "note": "For dynamic responses, use the chat completions endpoint"
                }),
                status_code: 200,
            },
        ],
    };

    // Start the server with custom endpoints
    println!("Starting server on http://127.0.0.1:8000");
    println!("📡 OpenAI-compatible API endpoints:");
    println!("   POST /v1/chat/completions");
    println!("   GET  /v1/models");
    println!("📡 Custom endpoints:");
    println!("   GET  /api/version");
    println!("   GET  /api/status");
    println!("   POST /api/echo");
    println!();
    println!("Try: curl http://127.0.0.1:8000/api/version");

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

    Ok(())
}

examples/agent_with_file_tools.rs (line 32)

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/agent_with_memory_db.rs (line 30)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Agent with Memory DB Example");
    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 "DataAgent" and equip it with the MemoryDBTool.
    let mut agent = Agent::builder("DataAgent")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to an in-memory database. \
             You can store and retrieve information using the memory_db tool. \
             Operations available: set, get, delete, list, clear, exists. \
             Use this to remember important information across our conversation.",
        )
        .tool(Box::new(MemoryDBTool::new()))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with memory database tool\n");

    // --- Example 1: Store user preferences ---
    println!("Example 1: Storing User Preferences");
    println!("====================================\n");

    let response = agent
        .chat("Store my name as 'Alice' and my favorite color as 'blue' in the database")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 2: Retrieve stored data ---
    println!("\nExample 2: Retrieving Stored Data");
    println!("==================================\n");

    let response = agent.chat("What's my name and favorite color?").await?;
    println!("Agent: {}\n", response);

    // --- Example 3: Store calculations ---
    println!("\nExample 3: Caching Calculations");
    println!("================================\n");

    let response = agent
        .chat("Calculate 123 * 456 and store the result in the database with key 'calculation_result'")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 4: List all stored data ---
    println!("\nExample 4: Listing All Data");
    println!("===========================\n");

    let response = agent
        .chat("Show me everything stored in the database")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 5: Check if key exists ---
    println!("\nExample 5: Checking Key Existence");
    println!("==================================\n");

    let response = agent
        .chat("Check if 'name' and 'age' exist in the database")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 6: Delete specific data ---
    println!("\nExample 6: Deleting Data");
    println!("========================\n");

    let response = agent
        .chat("Delete the 'calculation_result' from the database")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 7: Final state ---
    println!("\nExample 7: Final Database State");
    println!("================================\n");

    let response = agent
        .chat("List all remaining items in the database")
        .await?;
    println!("Agent: {}\n", response);

    println!("\n✅ Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • Setting key-value pairs in memory database");
    println!("  • Retrieving stored values");
    println!("  • Listing all database contents");
    println!("  • Checking key existence");
    println!("  • Deleting specific entries");
    println!("  • Persistent data across multiple agent interactions");
    println!("\n📝 Use Cases:");
    println!("  • Caching expensive computations");
    println!("  • Storing user preferences during conversation");
    println!("  • Maintaining context across multiple queries");
    println!("  • Temporary data storage for complex workflows");

    Ok(())
}

examples/agent_with_rag.rs (line 56)

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

    // Check for the required OpenAI API key.
    let embedding_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()
    });

    // 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 a new `QdrantRAGTool`.
    let rag_tool = QdrantRAGTool::new(
        "http://localhost:6333",                // Qdrant URL
        "helios_knowledge",                     // Collection name
        "https://api.openai.com/v1/embeddings", // Embedding API
        embedding_api_key,                      // API key
    );

    // Create an agent named "KnowledgeAgent" and equip it with the RAG tool.
    let mut agent = Agent::builder("KnowledgeAgent")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to a RAG (Retrieval-Augmented Generation) system. \
             You can store documents and retrieve relevant information to answer questions. \
             When answering questions, first search for relevant documents, then provide informed answers based on the retrieved context."
        )
        .tool(Box::new(rag_tool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with RAG capabilities\n");

    // --- Example 1: Add knowledge to the database ---
    println!("Example 1: Adding Documents to Knowledge Base");
    println!("==============================================\n");

    let response = agent
        .chat(
            "Store this information: Rust is a systems programming language that runs blazingly fast, \
             prevents segfaults, and guarantees thread safety. It was created by Mozilla Research."
        )
        .await?;
    println!("Agent: {}\n", response);

    let response = agent
        .chat(
            "Store this: Python is a high-level, interpreted programming language known for its \
             clear syntax and readability. It was created by Guido van Rossum in 1991.",
        )
        .await?;
    println!("Agent: {}\n", response);

    let response = agent
        .chat(
            "Store this: JavaScript is a programming language commonly used for web development. \
             It allows developers to create interactive web pages and runs in web browsers.",
        )
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 2: Semantic search - ask questions ---
    println!("\nExample 2: Semantic Search and Q&A");
    println!("===================================\n");

    let response = agent
        .chat("What programming language is known for preventing segfaults?")
        .await?;
    println!("Agent: {}\n", response);

    let response = agent
        .chat("Tell me about the programming language created in 1991")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 3: Multi-document retrieval ---
    println!("\nExample 3: Multi-Document Retrieval");
    println!("====================================\n");

    let response = agent
        .chat("Search for information about programming languages and summarize what you find")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 4: Adding documents with metadata ---
    println!("\nExample 4: Documents with Metadata");
    println!("===================================\n");

    let response = agent
        .chat(
            "Store this with metadata: \
             The Helios Engine is a Rust framework for building LLM agents. \
             Metadata: category=framework, language=rust, year=2024",
        )
        .await?;
    println!("Agent: {}\n", response);

    println!("\n✅ Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • Document embedding with OpenAI embeddings");
    println!("  • Vector storage in Qdrant database");
    println!("  • Semantic search with cosine similarity");
    println!("  • RAG workflow for context-aware answers");
    println!("  • Metadata support for document organization");

    println!("\n📝 RAG Use Cases:");
    println!("  • Question answering over custom knowledge bases");
    println!("  • Document search and retrieval");
    println!("  • Building chatbots with domain-specific knowledge");
    println!("  • Information extraction from large document sets");

    println!("\n🔧 Setup Instructions:");
    println!("  1. Start Qdrant: docker run -p 6333:6333 qdrant/qdrant");
    println!("  2. Set API key: export OPENAI_API_KEY=your-key");
    println!("  3. Run example: cargo run --example agent_with_rag");

    Ok(())
}

Additional examples can be found in:

• examples/complete_demo.rs

pub async fn build(self) -> Result<Agent>

Examples found in repository

examples/basic_chat.rs (line 18)

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

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

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

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

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/serve_with_custom_endpoints.rs (line 24)

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?;

    // Define custom endpoints
    let custom_endpoints = CustomEndpointsConfig {
        endpoints: vec![
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/version".to_string(),
                response: serde_json::json!({
                    "version": "0.2.8",
                    "service": "Helios Engine",
                    "features": ["agents", "tools", "streaming", "custom_endpoints"]
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/status".to_string(),
                response: serde_json::json!({
                    "status": "operational",
                    "uptime": "unknown",
                    "model": "agent-based"
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "POST".to_string(),
                path: "/api/echo".to_string(),
                response: serde_json::json!({
                    "message": "Echo endpoint - this returns static data",
                    "note": "For dynamic responses, use the chat completions endpoint"
                }),
                status_code: 200,
            },
        ],
    };

    // Start the server with custom endpoints
    println!("Starting server on http://127.0.0.1:8000");
    println!("📡 OpenAI-compatible API endpoints:");
    println!("   POST /v1/chat/completions");
    println!("   GET  /v1/models");
    println!("📡 Custom endpoints:");
    println!("   GET  /api/version");
    println!("   GET  /api/status");
    println!("   POST /api/echo");
    println!();
    println!("Try: curl http://127.0.0.1:8000/api/version");

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

    Ok(())
}

Additional examples can be found in:

• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/agent_with_rag.rs
• examples/complete_demo.rs