fix(agents): raise step limit and centralize on one global default (#1389)

## Why this matters

Agents were running out of steps mid-task. The browser agent (and
others) stopped at **10 steps** and told users to re-run with
`--max-steps 60`, even on routine multi-step work. The cap was hardcoded
low almost everywhere — `10` for most agents, `5`–`6` for a couple — and
the Agent UI pinned `10` in four more places, while the CLI used `100`
and background ticks `20`. So the limit was both too low *and*
inconsistent depending on how you launched the agent.

After this change there's **one knob**: `default_max_steps()` in
`base/agent.py` (default **50**, overridable at runtime with
`GAIA_AGENT_MAX_STEPS=<n>`). Every agent config inherits it, as do the
base `Agent`, the UI chat paths, and the autonomous-tick loop — so
retuning the whole fleet is a one-line change or a single env var, no
per-agent edits. Agents that genuinely need more keep their explicit
override (CodeAgent=100, EMR=50), and a typo'd env value now fails
loudly instead of silently capping.

## Test plan

- [x] `pytest tests/unit/agents/test_default_max_steps.py` — new helper
tests (default, env override, empty, loud-failure on
non-int/non-positive, configs inherit override)
- [x] `pytest tests/unit/agents/` — existing config-default tests
updated to assert against the helper; all green (pre-existing
context-overflow + Windows-encoding failures are unrelated, confirmed
failing on `main`)
- [x] `python util/lint.py --black --isort` clean; `pyflakes` clean on
all touched files
- [ ] Manual: launch the browser agent in the Agent UI and confirm it no
longer stops at 10 steps; set `GAIA_AGENT_MAX_STEPS=5` and confirm every
agent caps at 5

Co-authored-by: Ovtcharov <kovtchar@amd.com>

Author: kovtcharov-amd

docs/reference/cli.mdx

@@ -96,6 +96,21 @@ gaia --ui --base-url https://your-server:13305/api/v1
   `gaia chat --ui` continues to work as an alias. The Agent UI requires an AMD Ryzen AI Max (Strix Halo) or an AMD Radeon GPU with ≥ 24 GB VRAM. If your device is not supported, a dismissible warning banner will appear in the UI.
 </Note>
 
+### Agent step limit
+
+Agents stop after a maximum number of reasoning/tool steps. The default is **50**, applied consistently across the CLI, the Agent UI, and background runs.
+
+- **Per-invocation:** pass `--max-steps <n>` to any agent command (e.g. `gaia browse --max-steps 80`). `gaia blender` uses `--steps <n>`.
+- **Fleet-wide:** set the `GAIA_AGENT_MAX_STEPS` environment variable to change the default for every agent at once, without per-command flags.
+
+```bash
+# Raise the limit for every agent in this shell
+export GAIA_AGENT_MAX_STEPS=80
+gaia browse "research the latest AMD Ryzen AI news"
+```
+
+A few agents intentionally override the default (e.g. the Code agent uses 100 for multi-file generation). An invalid `GAIA_AGENT_MAX_STEPS` value (non-integer or ≤ 0) fails fast with an actionable error rather than silently capping agents.
+
 ---
 
 ## Initialization

hub/agents/python/analyst/gaia_agent_analyst/agent.py

@@ -2,10 +2,10 @@
 # SPDX-License-Identifier: MIT
 """Structured-data analysis GAIA agent."""
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import List, Optional
 
-from gaia.agents.base.agent import Agent
+from gaia.agents.base.agent import Agent, default_max_steps
 from gaia.agents.base.tools import _TOOL_REGISTRY
 from gaia.agents.tools import ScratchpadToolsMixin
 from gaia.mcp.mixin import MCPClientMixin
@@ -20,7 +20,7 @@ class AnalystAgentConfig:
     claude_model: str = "claude-sonnet-4-20250514"
     base_url: Optional[str] = None
     model_id: Optional[str] = None
-    max_steps: int = 10
+    max_steps: int = field(default_factory=default_max_steps)
     streaming: bool = False
     debug: bool = False
     debug_prompts: bool = False

hub/agents/python/analyst/tests/test_analyst_agent.py

@@ -26,10 +26,12 @@ class TestAnalystAgentConfig(unittest.TestCase):
     def test_defaults(self):
         from gaia_agent_analyst import AnalystAgentConfig
 
+        from gaia.agents.base.agent import default_max_steps
+
         cfg = AnalystAgentConfig()
         self.assertFalse(cfg.use_claude)
         self.assertIsNone(cfg.model_id)
-        self.assertEqual(cfg.max_steps, 10)
+        self.assertEqual(cfg.max_steps, default_max_steps())
         self.assertTrue(cfg.scratchpad_db_path)
 
 

hub/agents/python/blender/gaia_agent_blender/agent.py

@@ -30,7 +30,7 @@ def __init__(
         mcp: Optional[MCPClient] = None,
         model_id: str = None,
         base_url: str = "http://localhost:13305/api/v1",
-        max_steps: int = 5,
+        max_steps: Optional[int] = None,
         debug_prompts: bool = False,
         output_dir: str = None,
         streaming: bool = False,
@@ -526,10 +526,11 @@ def create_interactive_scene(
         Returns:
             Dict containing the scene creation result
         """
-        # Same process as process_query but with more steps allowed if specified
+        # When the caller doesn't override, fall back to the agent's configured
+        # max_steps (the global default unless explicitly set at construction).
         return self.process_query(
             f"Create a complete 3D scene with the following description: {scene_description}",
-            max_steps=max_steps if max_steps is not None else self.max_steps * 2,
+            max_steps=max_steps,
             trace=trace,
             filename=filename,
         )

hub/agents/python/browser/gaia_agent_browser/agent.py

@@ -2,10 +2,10 @@
 # SPDX-License-Identifier: MIT
 """Browser-focused GAIA agent."""
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import List, Optional
 
-from gaia.agents.base.agent import Agent
+from gaia.agents.base.agent import Agent, default_max_steps
 from gaia.agents.base.tools import _TOOL_REGISTRY
 from gaia.agents.tools import BrowserToolsMixin
 from gaia.mcp.mixin import MCPClientMixin
@@ -20,7 +20,7 @@ class BrowserAgentConfig:
     claude_model: str = "claude-sonnet-4-20250514"
     base_url: Optional[str] = None
     model_id: Optional[str] = None
-    max_steps: int = 10
+    max_steps: int = field(default_factory=default_max_steps)
     streaming: bool = False
     debug: bool = False
     debug_prompts: bool = False

hub/agents/python/code/gaia_agent_code/agent.py

@@ -115,8 +115,10 @@ def __init__(
         self.language = language
         self.project_type = project_type
 
-        # Default to more steps for complex workflows
-        if "max_steps" not in kwargs:
+        # Default to more steps for complex workflows. Treat an explicit None
+        # (the CLI's "use the default" sentinel) the same as omitted, so this
+        # override isn't silently dropped to the global default.
+        if kwargs.get("max_steps") is None:
             kwargs["max_steps"] = 100  # Increased for complex project generation
         # Use the coding model for better code understanding
         if "model_id" not in kwargs:

hub/agents/python/code/tests/test_code_agent.py

@@ -68,6 +68,11 @@ def test_agent_initialization(self):
         self.assertTrue(agent2.debug)
         self.assertTrue(agent2.show_prompts)
 
+        # Explicit max_steps=None is the CLI "use the default" sentinel and must
+        # NOT drop CodeAgent's 100-step override to the global default.
+        agent3 = CodeAgent(max_steps=None)
+        self.assertEqual(agent3.max_steps, 100)
+
     def test_system_prompt(self):
         """Test that system prompt is properly generated."""
         prompt = self.agent._get_system_prompt()

hub/agents/python/connectors-demo/gaia_agent_connectors_demo/agent.py

@@ -36,13 +36,13 @@
 
 import json
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime, time
 from typing import Any, ClassVar, Dict, List, Optional
 
 import httpx
 
-from gaia.agents.base.agent import Agent
+from gaia.agents.base.agent import Agent, default_max_steps
 from gaia.agents.base.console import AgentConsole
 from gaia.agents.base.tools import tool
 from gaia.connectors.errors import ConnectorsError
@@ -295,7 +295,7 @@ class ConnectorsDemoAgentConfig:
 
     base_url: Optional[str] = None
     model_id: Optional[str] = None
-    max_steps: int = 6
+    max_steps: int = field(default_factory=default_max_steps)
     streaming: bool = False
     debug: bool = False
     show_stats: bool = False

hub/agents/python/docker/gaia_agent_docker/agent.py

@@ -14,6 +14,7 @@
 from pathlib import Path
 from typing import Any, Dict
 
+from gaia.agents.base.agent import default_max_steps
 from gaia.agents.base.console import AgentConsole, SilentConsole
 from gaia.agents.base.mcp_agent import MCPAgent
 from gaia.agents.base.tools import tool
@@ -22,7 +23,6 @@
 logger = logging.getLogger(__name__)
 
 DEFAULT_MODEL = "Qwen3.5-35B-A3B-GGUF"
-DEFAULT_MAX_STEPS = 10
 DEFAULT_PORT = 8080
 
 
@@ -45,7 +45,7 @@ def __init__(self, **kwargs):
 
         Args:
             **kwargs: Agent initialization parameters:
-                - max_steps: Maximum conversation steps (default: 10)
+                - max_steps: Maximum conversation steps (default: global default_max_steps())
                 - model_id: LLM model to use (default: Qwen3.5-35B-A3B-GGUF)
                 - silent_mode: Suppress console output (default: False)
                 - debug: Enable debug logging (default: False)
@@ -55,8 +55,10 @@ def __init__(self, **kwargs):
         if "model_id" not in kwargs:
             kwargs["model_id"] = DEFAULT_MODEL
 
-        if "max_steps" not in kwargs:
-            kwargs["max_steps"] = DEFAULT_MAX_STEPS
+        # An explicit None (the CLI's "use the default" sentinel) counts as no
+        # override and falls through to the global default.
+        if kwargs.get("max_steps") is None:
+            kwargs["max_steps"] = default_max_steps()
 
         # Security: Configure allowed paths for file operations
         # If None, allow current directory and subdirectories

hub/agents/python/emr/gaia_agent_emr/agent.py

@@ -130,8 +130,11 @@ def __init__(
         # Signature: callback(filename, step_num, total_steps, step_name, status)
         self._progress_callback: Optional[callable] = None
 
-        # Set reasonable defaults for agent - higher max_steps for interactive use
-        kwargs.setdefault("max_steps", 50)
+        # Set reasonable defaults for agent - higher max_steps for interactive
+        # use. Treat an explicit None (the CLI "use the default" sentinel) the
+        # same as omitted so this override isn't dropped to the global default.
+        if kwargs.get("max_steps") is None:
+            kwargs["max_steps"] = 50
 
         super().__init__(**kwargs)