use NonZeroUsize for max_iterations

number of iterations must be at least 1. Use NonZeroUsize for this.

Signed-off-by: Aurabindo Pillai <mail@aurabindo.in>

Author: aurabindo

crates/agents-runtime/src/agent/builder.rs

@@ -18,6 +18,7 @@ use agents_core::llm::LanguageModel;
 use agents_core::persistence::Checkpointer;
 use agents_core::tools::ToolBox;
 use std::collections::{HashMap, HashSet};
+use std::num::NonZeroUsize;
 use std::sync::Arc;
 
 /// Builder API to assemble a DeepAgent in a single fluent flow, mirroring the Python
@@ -36,7 +37,7 @@ pub struct ConfigurableAgentBuilder {
     event_dispatcher: Option<Arc<agents_core::events::EventDispatcher>>,
     enable_pii_sanitization: bool,
     token_tracking_config: Option<TokenTrackingConfig>,
-    max_iterations: usize,
+    max_iterations: NonZeroUsize,
 }
 
 impl ConfigurableAgentBuilder {
@@ -55,7 +56,7 @@ impl ConfigurableAgentBuilder {
             event_dispatcher: None,
             enable_pii_sanitization: true, // Enabled by default for security
             token_tracking_config: None,
-            max_iterations: 10,
+            max_iterations: NonZeroUsize::new(10).unwrap(),
         }
     }
 
@@ -308,10 +309,16 @@ impl ConfigurableAgentBuilder {
     /// user requests, calling tools and reasoning about the results. This setting
     /// controls how many iterations the agent can perform before it stops.
     ///
+    /// **Note**: `max_iterations` must be greater than 0. Passing 0 will result in a panic.
+    ///
     /// # Default
     ///
     /// Defaults to 10 iterations if not specified.
     ///
+    /// # Panics
+    ///
+    /// Panics if `max_iterations` is 0.
+    ///
     /// # Example
     ///
     /// ```ignore
@@ -321,7 +328,8 @@ impl ConfigurableAgentBuilder {
     ///     .build()?;
     /// ```
     pub fn with_max_iterations(mut self, max_iterations: usize) -> Self {
-        self.max_iterations = max_iterations;
+        self.max_iterations =
+            NonZeroUsize::new(max_iterations).expect("max_iterations must be greater than 0");
         self
     }
 
@@ -386,7 +394,7 @@ impl ConfigurableAgentBuilder {
             .with_auto_general_purpose(auto_general_purpose)
             .with_prompt_caching(enable_prompt_caching)
             .with_pii_sanitization(enable_pii_sanitization)
-            .with_max_iterations(max_iterations);
+            .with_max_iterations(max_iterations.get());
 
         if let Some(ckpt) = checkpointer {
             cfg = cfg.with_checkpointer(ckpt);
@@ -421,25 +429,25 @@ mod tests {
     #[test]
     fn test_builder_default_max_iterations() {
         let builder = ConfigurableAgentBuilder::new("test instructions");
-        assert_eq!(builder.max_iterations, 10);
+        assert_eq!(builder.max_iterations.get(), 10);
     }
 
     #[test]
     fn test_builder_custom_max_iterations() {
         let builder = ConfigurableAgentBuilder::new("test instructions").with_max_iterations(20);
-        assert_eq!(builder.max_iterations, 20);
+        assert_eq!(builder.max_iterations.get(), 20);
     }
 
     #[test]
-    fn test_builder_zero_max_iterations() {
-        let builder = ConfigurableAgentBuilder::new("test instructions").with_max_iterations(0);
-        assert_eq!(builder.max_iterations, 0);
+    #[should_panic(expected = "max_iterations must be greater than 0")]
+    fn test_builder_zero_max_iterations_panics() {
+        let _builder = ConfigurableAgentBuilder::new("test instructions").with_max_iterations(0);
     }
 
     #[test]
     fn test_builder_large_max_iterations() {
         let builder = ConfigurableAgentBuilder::new("test instructions").with_max_iterations(1000);
-        assert_eq!(builder.max_iterations, 1000);
+        assert_eq!(builder.max_iterations.get(), 1000);
     }
 
     #[test]
@@ -450,7 +458,7 @@ mod tests {
             .with_prompt_caching(true)
             .with_pii_sanitization(false);
 
-        assert_eq!(builder.max_iterations, 15);
+        assert_eq!(builder.max_iterations.get(), 15);
         assert_eq!(builder.auto_general_purpose, false);
         assert_eq!(builder.enable_prompt_caching, true);
         assert_eq!(builder.enable_pii_sanitization, false);

crates/agents-runtime/src/agent/config.rs

@@ -8,6 +8,7 @@ use agents_core::agent::PlannerHandle;
 use agents_core::persistence::Checkpointer;
 use agents_core::tools::ToolBox;
 use std::collections::{HashMap, HashSet};
+use std::num::NonZeroUsize;
 use std::sync::Arc;
 
 /// Parameters for create_deep_agent() that mirror the Python API exactly
@@ -54,7 +55,7 @@ pub struct DeepAgentConfig {
     pub event_dispatcher: Option<Arc<agents_core::events::EventDispatcher>>,
     pub enable_pii_sanitization: bool,
     pub token_tracking_config: Option<TokenTrackingConfig>,
-    pub max_iterations: usize,
+    pub max_iterations: NonZeroUsize,
 }
 
 impl DeepAgentConfig {
@@ -73,7 +74,7 @@ impl DeepAgentConfig {
             event_dispatcher: None,
             enable_pii_sanitization: true, // Enabled by default for security
             token_tracking_config: None,
-            max_iterations: 10,
+            max_iterations: NonZeroUsize::new(10).unwrap(),
         }
     }
 
@@ -183,9 +184,19 @@ impl DeepAgentConfig {
     }
 
     /// Set the maximum number of ReAct loop iterations before stopping.
+    ///
+    /// **Note**: `max_iterations` must be greater than 0. Passing 0 will result in a panic.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `max_iterations` is 0.
+    ///
+    /// # Default
+    ///
     /// Defaults to 10 if not specified.
     pub fn with_max_iterations(mut self, max_iterations: usize) -> Self {
-        self.max_iterations = max_iterations;
+        self.max_iterations =
+            NonZeroUsize::new(max_iterations).expect("max_iterations must be greater than 0");
         self
     }
 }
@@ -310,14 +321,14 @@ mod tests {
     fn test_config_default_max_iterations() {
         let planner = create_mock_planner();
         let config = DeepAgentConfig::new("test instructions", planner);
-        assert_eq!(config.max_iterations, 10);
+        assert_eq!(config.max_iterations.get(), 10);
     }
 
     #[test]
     fn test_config_custom_max_iterations() {
         let planner = create_mock_planner();
         let config = DeepAgentConfig::new("test instructions", planner).with_max_iterations(25);
-        assert_eq!(config.max_iterations, 25);
+        assert_eq!(config.max_iterations.get(), 25);
     }
 
     #[test]
@@ -329,7 +340,7 @@ mod tests {
             .with_prompt_caching(true)
             .with_pii_sanitization(false);
 
-        assert_eq!(config.max_iterations, 30);
+        assert_eq!(config.max_iterations.get(), 30);
         assert_eq!(config.auto_general_purpose, false);
         assert_eq!(config.enable_prompt_caching, true);
         assert_eq!(config.enable_pii_sanitization, false);
@@ -341,7 +352,14 @@ mod tests {
         let config = DeepAgentConfig::new("test instructions", planner).with_max_iterations(42);
 
         // Verify the value is actually stored
-        assert_eq!(config.max_iterations, 42);
+        assert_eq!(config.max_iterations.get(), 42);
+    }
+
+    #[test]
+    #[should_panic(expected = "max_iterations must be greater than 0")]
+    fn test_config_zero_max_iterations_panics() {
+        let planner = create_mock_planner();
+        let _config = DeepAgentConfig::new("test instructions", planner).with_max_iterations(0);
     }
 
     #[test]
@@ -351,19 +369,19 @@ mod tests {
         // Test that max_iterations works with various combinations
         let config =
             DeepAgentConfig::new("test instructions", planner.clone()).with_max_iterations(5);
-        assert_eq!(config.max_iterations, 5);
+        assert_eq!(config.max_iterations.get(), 5);
 
         let config2 = DeepAgentConfig::new("test instructions", planner.clone())
             .with_prompt_caching(true)
             .with_max_iterations(15);
-        assert_eq!(config2.max_iterations, 15);
+        assert_eq!(config2.max_iterations.get(), 15);
         assert_eq!(config2.enable_prompt_caching, true);
 
         let config3 = DeepAgentConfig::new("test instructions", planner)
             .with_auto_general_purpose(false)
             .with_max_iterations(100)
             .with_pii_sanitization(true);
-        assert_eq!(config3.max_iterations, 100);
+        assert_eq!(config3.max_iterations.get(), 100);
         assert_eq!(config3.auto_general_purpose, false);
         assert_eq!(config3.enable_pii_sanitization, true);
     }

crates/agents-runtime/src/agent/runtime.rs

@@ -22,6 +22,7 @@ use agents_core::tools::{ToolBox, ToolContext, ToolResult};
 use async_trait::async_trait;
 use serde_json::Value;
 use std::collections::{HashMap, HashSet};
+use std::num::NonZeroUsize;
 use std::sync::{Arc, RwLock};
 
 // Built-in tool names exposed by middlewares. The `task` tool for subagents is not gated.
@@ -64,7 +65,7 @@ pub struct DeepAgent {
     checkpointer: Option<Arc<dyn Checkpointer>>,
     event_dispatcher: Option<Arc<agents_core::events::EventDispatcher>>,
     enable_pii_sanitization: bool,
-    max_iterations: usize,
+    max_iterations: NonZeroUsize,
 }
 
 impl DeepAgent {
@@ -509,7 +510,7 @@ impl DeepAgent {
         self.append_history(input.clone());
 
         // ReAct loop: continue until LLM responds with text (not tool calls)
-        let max_iterations = self.max_iterations;
+        let max_iterations = self.max_iterations.get();
         let mut iteration = 0;
 
         loop {
@@ -946,7 +947,7 @@ pub fn create_deep_agent_from_config(config: DeepAgentConfig) -> DeepAgent {
         let mut sub_cfg = DeepAgentConfig::new(subagent_config.instructions.clone(), sub_planner);
 
         // Inherit max_iterations from parent
-        sub_cfg = sub_cfg.with_max_iterations(config.max_iterations);
+        sub_cfg = sub_cfg.with_max_iterations(config.max_iterations.get());
 
         // Configure tools
         if let Some(ref tools) = subagent_config.tools {
@@ -1003,7 +1004,7 @@ pub fn create_deep_agent_from_config(config: DeepAgentConfig) -> DeepAgent {
                     .with_auto_general_purpose(false)
                     .with_prompt_caching(config.enable_prompt_caching)
                     .with_pii_sanitization(config.enable_pii_sanitization)
-                    .with_max_iterations(config.max_iterations);
+                    .with_max_iterations(config.max_iterations.get());
             if let Some(ref selected) = config.builtin_tools {
                 sub_cfg = sub_cfg.with_builtin_tools(selected.iter().cloned());
             }