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/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 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`.
    // Using the improved syntax to add multiple tools at once!
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .max_iterations(5)
        .build()
        .await?;

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

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

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

    Ok(())
}

examples/serve_agent.rs (line 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/basic_chat.rs (line 24)

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

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

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

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

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

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

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

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

    Ok(())
}

examples/multiple_agents.rs (line 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/rag_qdrant_comparison.rs (line 33)

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

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

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

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

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

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

Additional examples can be found in:

• examples/serve_with_custom_endpoints.rs
• examples/react_agent.rs
• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/serve_simple_endpoints.rs
• examples/react_debugging.rs
• examples/react_comparison.rs
• examples/rag_in_memory.rs
• examples/agent_with_rag.rs
• examples/tool_builder_demo.rs
• examples/complete_demo.rs
• examples/react_custom_prompt.rs

pub fn auto_config(self) -> Self

Shorthand: set config directly from a file or use defaults

Examples found in repository

examples/ultra_simple.rs (line 17)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    use helios_engine::ChatMessage;

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

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

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

    use helios_engine::AutoForest;

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

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

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

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

    Ok(())
}

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

Examples found in repository

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 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`.
    // Using the improved syntax to add multiple tools at once!
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .max_iterations(5)
        .build()
        .await?;

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

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

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

    Ok(())
}

examples/serve_agent.rs (line 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/basic_chat.rs (line 25)

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

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

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

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

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

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

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

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

    Ok(())
}

examples/multiple_agents.rs (line 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/rag_qdrant_comparison.rs (line 34)

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

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

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

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

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

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

Additional examples can be found in:

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

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

Shorthand: use ‘prompt’ instead of ‘system_prompt’

Examples found in repository

examples/ultra_simple.rs (line 18)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    use helios_engine::ChatMessage;

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

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

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

    use helios_engine::AutoForest;

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

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

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

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

    Ok(())
}

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

Adds a single tool to the agent.

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/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/rag_qdrant_comparison.rs (line 35)

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/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/serve_simple_endpoints.rs
• examples/rag_in_memory.rs
• examples/agent_with_rag.rs
• examples/tool_builder_demo.rs
• examples/complete_demo.rs
• examples/react_custom_prompt.rs

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

Shorthand: add a single tool (alias for tool())

Examples found in repository

examples/ultra_simple.rs (line 50)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    use helios_engine::ChatMessage;

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

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

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

    use helios_engine::AutoForest;

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

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

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

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

    Ok(())
}

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

Adds multiple tools to the agent at once.

Example

let agent = Agent::builder("MyAgent")
    .config(config)
    .tools(vec![
        Box::new(CalculatorTool),
        Box::new(EchoTool),
    ])
    .build()
    .await?;

Examples found in repository

examples/agent_with_tools.rs (line 18)

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

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

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

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

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

    Ok(())
}

examples/react_agent.rs (lines 25-29)

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/react_debugging.rs (lines 29-33)

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

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

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

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

Be extremely detailed in your thinking."#;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/react_comparison.rs (line 20)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/react_custom_prompt.rs (line 62)

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

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

    // Example 1: Math-focused reasoning prompt
    println!("═══════════════════════════════════════════════════════════");
    println!("Example 1: Mathematical Problem Solver");
    println!("═══════════════════════════════════════════════════════════\n");

    let math_prompt = r#"As a mathematical problem solver, analyze this systematically:

1. IDENTIFY: What mathematical operations are required?
2. DECOMPOSE: Break complex calculations into simple steps
3. ORDER: Determine the correct order of operations (PEMDAS/BODMAS)
4. PLAN: List which calculator functions to use and in what sequence
5. VERIFY: Consider how to check the answer

Provide your mathematical reasoning clearly."#;

    let mut math_agent = Agent::builder("MathExpert")
        .config(config.clone())
        .system_prompt("You are a mathematical expert who thinks carefully about calculations.")
        .tool(Box::new(CalculatorTool))
        .react_with_prompt(math_prompt)
        .build()
        .await?;

    println!("User: Calculate ((15 * 8) + (20 * 3)) / 2\n");
    let response = math_agent
        .chat("Calculate ((15 * 8) + (20 * 3)) / 2")
        .await?;
    println!("\nAgent: {}\n", response);

    // Example 2: Data analysis reasoning prompt
    println!("═══════════════════════════════════════════════════════════");
    println!("Example 2: Data Analysis Agent");
    println!("═══════════════════════════════════════════════════════════\n");

    let data_prompt = r#"As a data analyst, approach this task methodically:

1. UNDERSTAND: What data or files are we working with?
2. EXTRACT: What information needs to be retrieved?
3. PROCESS: What transformations or calculations are needed?
4. TOOLS: Which tools should I use and in what order?
5. OUTPUT: What format should the final answer take?

Think through the data pipeline step by step."#;

    let mut data_agent = Agent::builder("DataAnalyst")
        .config(config.clone())
        .system_prompt("You are a data analyst who carefully plans data processing tasks.")
        .tools(vec![Box::new(FileReadTool), Box::new(CalculatorTool)])
        .react_with_prompt(data_prompt)
        .build()
        .await?;

    println!("User: If I have numbers 10, 20, 30, 40, 50, what's their average?\n");
    let response = data_agent
        .chat("If I have numbers 10, 20, 30, 40, 50, what's their average?")
        .await?;
    println!("\nAgent: {}\n", response);

    // Example 3: Task planning reasoning prompt
    println!("═══════════════════════════════════════════════════════════");
    println!("Example 3: Task Planning Agent");
    println!("═══════════════════════════════════════════════════════════\n");

    let planning_prompt = r#"As a task planning expert, organize this systematically:

1. GOAL: What is the end objective?
2. PREREQUISITES: What information do I already have?
3. DEPENDENCIES: What needs to happen before what?
4. RESOURCES: What tools are available to me?
5. STEPS: Create a numbered action plan
6. CONTINGENCY: What could go wrong?

Plan the execution strategy carefully."#;

    let mut planning_agent = Agent::builder("TaskPlanner")
        .config(config.clone())
        .system_prompt("You are a strategic planner who breaks down complex tasks.")
        .tool(Box::new(CalculatorTool))
        .react_with_prompt(planning_prompt)
        .build()
        .await?;

    println!("User: I need to calculate the total cost: 5 items at $12.50 each, plus 8% tax\n");
    let response = planning_agent
        .chat("I need to calculate the total cost: 5 items at $12.50 each, plus 8% tax")
        .await?;
    println!("\nAgent: {}\n", response);

    // Example 4: Scientific reasoning prompt
    println!("═══════════════════════════════════════════════════════════");
    println!("Example 4: Scientific Reasoning Agent");
    println!("═══════════════════════════════════════════════════════════\n");

    let scientific_prompt = r#"Apply the scientific method to this problem:

1. OBSERVATION: What is being asked?
2. HYPOTHESIS: What approach should work?
3. VARIABLES: What factors are involved?
4. METHOD: What tools and operations are needed?
5. PREDICTION: What result do we expect?
6. VERIFICATION: How can we validate the answer?

Use rigorous scientific thinking."#;

    let mut science_agent = Agent::builder("Scientist")
        .config(config)
        .system_prompt("You are a scientist who applies rigorous methodology.")
        .tool(Box::new(CalculatorTool))
        .react_with_prompt(scientific_prompt)
        .build()
        .await?;

    println!("User: If velocity = 30 m/s and time = 4 seconds, what's the distance?\n");
    let response = science_agent
        .chat("If velocity = 30 m/s and time = 4 seconds, what's the distance?")
        .await?;
    println!("\nAgent: {}\n", response);

    println!("═══════════════════════════════════════════════════════════");
    println!(" Custom Prompt Demo Complete!");
    println!("═══════════════════════════════════════════════════════════");
    println!("\nKey Takeaways:");
    println!("  • Custom prompts tailor reasoning to specific domains");
    println!("  • Different prompts optimize for different task types");
    println!("  • Use .react_with_prompt() for domain-specific reasoning");
    println!("  • Each agent can have its own reasoning style\n");

    Ok(())
}

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

Shorthand: add multiple tools (alias for tools())

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`.
    // Using the improved syntax to add multiple tools at once!
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .max_iterations(5)
        .build()
        .await?;

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

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

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

    Ok(())
}

examples/serve_agent.rs (line 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/rag_qdrant_comparison.rs (line 36)

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/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/react_agent.rs (line 31)

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/forest_simple_demo.rs (line 27)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Forest of Agents - Simple Demo\n");

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

    // Create a simpler forest with just 3 agents
    let mut forest = ForestBuilder::new()
        .config(config)
        .agent(
            "coordinator".to_string(),
            Agent::builder("coordinator")
                .system_prompt(
                    "You are a project coordinator. Your ONLY job is to create plans, not execute tasks.\n\
                    When given a task, IMMEDIATELY use the create_plan tool with this format:\n\
                    - objective: the overall goal\n\
                    - tasks: JSON array with structure [{\"id\":\"task_1\",\"description\":\"...\",\"assigned_to\":\"worker1\",\"dependencies\":[]}]\n\n\
                    Keep plans simple with 2-3 tasks max. Do NOT try to complete the task yourself."
                )
                .max_iterations(15)
        )
        .agent(
            "worker1".to_string(),
            Agent::builder("worker1")
                .system_prompt(
                    "You are a helpful worker. Complete the task assigned to you and use the \
                    update_task_memory tool to save your results. Be brief and direct."
                )
                .max_iterations(8)
        )
        .agent(
            "worker2".to_string(),
            Agent::builder("worker2")
                .system_prompt(
                    "You are a helpful worker. Complete the task assigned to you and use the \
                    update_task_memory tool to save your results. Be brief and direct."
                )
                .max_iterations(8)
        )
        .max_iterations(20)
        .build()
        .await?;

    println!(" Forest created with 3 agents\n");

    // Simple task
    let task = "List 3 benefits of exercise. Keep it brief.";
    println!("📋 Task: {}\n", task);

    let result = forest
        .execute_collaborative_task(
            &"coordinator".to_string(),
            task.to_string(),
            vec!["worker1".to_string(), "worker2".to_string()],
        )
        .await?;

    println!("\n{}\n", "=".repeat(60));
    println!("✨ RESULT:\n{}\n", result);
    println!("{}\n", "=".repeat(60));

    // Show task breakdown
    let context = forest.get_shared_context().await;
    if let Some(plan) = context.get_plan() {
        println!("📊 Plan Summary:");
        let (completed, total) = plan.get_progress();
        println!("  Completed: {}/{} tasks\n", completed, total);

        for task in plan.tasks_in_order() {
            let status = match task.status {
                helios_engine::forest::TaskStatus::Completed => "",
                helios_engine::forest::TaskStatus::InProgress => "🔄",
                helios_engine::forest::TaskStatus::Pending => "⏳",
                helios_engine::forest::TaskStatus::Failed => "❌",
            };
            println!("  {} [{}] {}", status, task.assigned_to, task.description);
        }
    } else {
        println!("📊 No plan was created (coordinator handled directly)");
    }

    println!("\n Demo completed!");

    Ok(())
}

Additional examples can be found in:

• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/serve_simple_endpoints.rs
• examples/react_debugging.rs
• examples/rag_in_memory.rs
• examples/agent_with_rag.rs
• examples/complete_demo.rs
• examples/forest_of_agents.rs
• examples/forest_with_coordinator.rs

pub fn react(self) -> Self

Enables ReAct mode for the agent.

In ReAct mode, the agent will reason about the task and create a plan before taking actions. This helps the agent think through problems more systematically and make better decisions.

Example

let agent = Agent::builder("MyAgent")
    .config(config)
    .react()
    .build()
    .await?;

Examples found in repository

examples/react_agent.rs (line 30)

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/react_comparison.rs (line 28)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

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

Enables ReAct mode with a custom reasoning prompt.

This allows you to customize how the agent reasons about tasks. You can tailor the reasoning process to specific domains or tasks.

Arguments

• prompt - Custom prompt to guide the agent’s reasoning

Example

let custom_prompt = r#"
As a mathematical problem solver:
1. Identify the mathematical operations needed
2. Break down complex calculations into steps
3. Determine the order of operations
4. Plan which calculator functions to use
"#;

let agent = Agent::builder("MathAgent")
    .config(config)
    .react_with_prompt(custom_prompt)
    .build()
    .await?;

Examples found in repository

examples/react_debugging.rs (line 34)

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

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

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

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

Be extremely detailed in your thinking."#;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/react_custom_prompt.rs (line 34)

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

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

    // Example 1: Math-focused reasoning prompt
    println!("═══════════════════════════════════════════════════════════");
    println!("Example 1: Mathematical Problem Solver");
    println!("═══════════════════════════════════════════════════════════\n");

    let math_prompt = r#"As a mathematical problem solver, analyze this systematically:

1. IDENTIFY: What mathematical operations are required?
2. DECOMPOSE: Break complex calculations into simple steps
3. ORDER: Determine the correct order of operations (PEMDAS/BODMAS)
4. PLAN: List which calculator functions to use and in what sequence
5. VERIFY: Consider how to check the answer

Provide your mathematical reasoning clearly."#;

    let mut math_agent = Agent::builder("MathExpert")
        .config(config.clone())
        .system_prompt("You are a mathematical expert who thinks carefully about calculations.")
        .tool(Box::new(CalculatorTool))
        .react_with_prompt(math_prompt)
        .build()
        .await?;

    println!("User: Calculate ((15 * 8) + (20 * 3)) / 2\n");
    let response = math_agent
        .chat("Calculate ((15 * 8) + (20 * 3)) / 2")
        .await?;
    println!("\nAgent: {}\n", response);

    // Example 2: Data analysis reasoning prompt
    println!("═══════════════════════════════════════════════════════════");
    println!("Example 2: Data Analysis Agent");
    println!("═══════════════════════════════════════════════════════════\n");

    let data_prompt = r#"As a data analyst, approach this task methodically:

1. UNDERSTAND: What data or files are we working with?
2. EXTRACT: What information needs to be retrieved?
3. PROCESS: What transformations or calculations are needed?
4. TOOLS: Which tools should I use and in what order?
5. OUTPUT: What format should the final answer take?

Think through the data pipeline step by step."#;

    let mut data_agent = Agent::builder("DataAnalyst")
        .config(config.clone())
        .system_prompt("You are a data analyst who carefully plans data processing tasks.")
        .tools(vec![Box::new(FileReadTool), Box::new(CalculatorTool)])
        .react_with_prompt(data_prompt)
        .build()
        .await?;

    println!("User: If I have numbers 10, 20, 30, 40, 50, what's their average?\n");
    let response = data_agent
        .chat("If I have numbers 10, 20, 30, 40, 50, what's their average?")
        .await?;
    println!("\nAgent: {}\n", response);

    // Example 3: Task planning reasoning prompt
    println!("═══════════════════════════════════════════════════════════");
    println!("Example 3: Task Planning Agent");
    println!("═══════════════════════════════════════════════════════════\n");

    let planning_prompt = r#"As a task planning expert, organize this systematically:

1. GOAL: What is the end objective?
2. PREREQUISITES: What information do I already have?
3. DEPENDENCIES: What needs to happen before what?
4. RESOURCES: What tools are available to me?
5. STEPS: Create a numbered action plan
6. CONTINGENCY: What could go wrong?

Plan the execution strategy carefully."#;

    let mut planning_agent = Agent::builder("TaskPlanner")
        .config(config.clone())
        .system_prompt("You are a strategic planner who breaks down complex tasks.")
        .tool(Box::new(CalculatorTool))
        .react_with_prompt(planning_prompt)
        .build()
        .await?;

    println!("User: I need to calculate the total cost: 5 items at $12.50 each, plus 8% tax\n");
    let response = planning_agent
        .chat("I need to calculate the total cost: 5 items at $12.50 each, plus 8% tax")
        .await?;
    println!("\nAgent: {}\n", response);

    // Example 4: Scientific reasoning prompt
    println!("═══════════════════════════════════════════════════════════");
    println!("Example 4: Scientific Reasoning Agent");
    println!("═══════════════════════════════════════════════════════════\n");

    let scientific_prompt = r#"Apply the scientific method to this problem:

1. OBSERVATION: What is being asked?
2. HYPOTHESIS: What approach should work?
3. VARIABLES: What factors are involved?
4. METHOD: What tools and operations are needed?
5. PREDICTION: What result do we expect?
6. VERIFICATION: How can we validate the answer?

Use rigorous scientific thinking."#;

    let mut science_agent = Agent::builder("Scientist")
        .config(config)
        .system_prompt("You are a scientist who applies rigorous methodology.")
        .tool(Box::new(CalculatorTool))
        .react_with_prompt(scientific_prompt)
        .build()
        .await?;

    println!("User: If velocity = 30 m/s and time = 4 seconds, what's the distance?\n");
    let response = science_agent
        .chat("If velocity = 30 m/s and time = 4 seconds, what's the distance?")
        .await?;
    println!("\nAgent: {}\n", response);

    println!("═══════════════════════════════════════════════════════════");
    println!(" Custom Prompt Demo Complete!");
    println!("═══════════════════════════════════════════════════════════");
    println!("\nKey Takeaways:");
    println!("  • Custom prompts tailor reasoning to specific domains");
    println!("  • Different prompts optimize for different task types");
    println!("  • Use .react_with_prompt() for domain-specific reasoning");
    println!("  • Each agent can have its own reasoning style\n");

    Ok(())
}

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

Examples found in repository

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`.
    // Using the improved syntax to add multiple tools at once!
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tools(vec![Box::new(CalculatorTool), Box::new(EchoTool)])
        .max_iterations(5)
        .build()
        .await?;

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

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

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

    Ok(())
}

examples/serve_agent.rs (line 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/basic_chat.rs (line 26)

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

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

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

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

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

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

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

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

    Ok(())
}

examples/multiple_agents.rs (line 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/rag_qdrant_comparison.rs (line 37)

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

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

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

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

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

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

Additional examples can be found in:

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