Refactor agent definitions to use dict keys by name

Author: virrius

agents.yaml.example

@@ -11,7 +11,7 @@
 
 agents:
   # Example 1: Simple custom research agent with overrides
-  - name: "custom_research_agent"
+  custom_research_agent:
     base_class: "SGRResearchAgent"
 
     # Optional: Override LLM settings for this agent
@@ -68,7 +68,7 @@ agents:
       - "FinalAnswerTool"
 
   # Example 2: Minimal agent with defaults
-  - name: "simple_agent"
+  simple_agent:
     base_class: "SGRToolCallingResearchAgent"
 
     # Only override what's needed
@@ -80,7 +80,7 @@ agents:
       - "FinalAnswerTool"
 
   # Example 3: Fast research agent optimized for speed
-  - name: "fast_research_agent"
+  fast_research_agent:
     base_class: "SGRToolCallingResearchAgent"
 
     llm:
@@ -101,7 +101,7 @@ agents:
       - "ReasoningTool"
 
   # Example 4: Specialized technical analyst with custom prompts
-  - name: "technical_analyst"
+  technical_analyst:
     base_class: "SGRResearchAgent"
 
     llm:
@@ -125,7 +125,7 @@ agents:
       - "FinalAnswerTool"
 
   # Example 5: Agent using inline prompts instead of files
-  - name: "inline_prompt_agent"
+  inline_prompt_agent:
     base_class: "SGRResearchAgent"
 
     prompts:

sgr_deep_research/__main__.py

@@ -10,6 +10,7 @@
 from sgr_deep_research.api.endpoints import router
 from sgr_deep_research.core import AgentRegistry, ToolRegistry
 from sgr_deep_research.core.agent_config import GlobalConfig
+from sgr_deep_research.default_definitions import get_default_agents_definitions
 from sgr_deep_research.settings import ServerConfig, setup_logging
 
 setup_logging()
@@ -30,8 +31,9 @@ async def lifespan(app: FastAPI):
 def main():
     """Запуск FastAPI сервера."""
     args = ServerConfig()
-    GlobalConfig.from_yaml(args.config_file)
-    GlobalConfig.definitions_from_yaml(args.agents_file)
+    config = GlobalConfig.from_yaml(args.config_file)
+    config.agents.update(get_default_agents_definitions())
+    config.definitions_from_yaml(args.agents_file)
     app = FastAPI(title="SGR Deep Research API", version=__version__, lifespan=lifespan)
     app.include_router(router)
     uvicorn.run(app, host=args.host, port=args.port, log_level="info")

sgr_deep_research/core/agent_config.py

@@ -1,3 +1,4 @@
+import logging
 from pathlib import Path
 from typing import ClassVar, Self
 
@@ -6,6 +7,8 @@
 
 from sgr_deep_research.core.agent_definition import AgentConfig, Definitions
 
+logger = logging.getLogger(__name__)
+
 
 class GlobalConfig(BaseSettings, AgentConfig, Definitions):
     _instance: ClassVar[Self | None] = None
@@ -44,8 +47,39 @@ def from_yaml(cls, yaml_path: str) -> Self:
 
     @classmethod
     def definitions_from_yaml(cls, agents_yaml_path: str) -> Self:
+        """Load agent definitions from YAML file and merge with existing
+        agents.
+
+        Args:
+            agents_yaml_path: Path to YAML file with agent definitions
+
+        Returns:
+            GlobalConfig instance with merged agents
+
+        Raises:
+            FileNotFoundError: If YAML file not found
+            ValueError: If YAML file doesn't contain 'agents' key
+        """
         agents_yaml_path = Path(agents_yaml_path)
         if not agents_yaml_path.exists():
             raise FileNotFoundError(f"Agents definitions file not found: {agents_yaml_path}")
-        cls._instance.agents = Definitions(**yaml.safe_load(agents_yaml_path.read_text(encoding="utf-8"))).agents
+
+        yaml_data = yaml.safe_load(agents_yaml_path.read_text(encoding="utf-8"))
+        if not yaml_data.get("agents"):
+            raise ValueError(f"Agents definitions file must contain 'agents' key: {agents_yaml_path}")
+
+        for agent_name, agent_config in yaml_data.get("agents").items():
+            agent_config["name"] = agent_name
+
+        custom_agents = Definitions(**yaml_data).agents
+
+        # Check for agents that will be overridden
+        overridden = set(cls._instance.agents.keys()) & set(custom_agents.keys())
+        if overridden:
+            logger.warning(
+                f"Custom agents from {agents_yaml_path.name} will override existing agents: "
+                f"{', '.join(sorted(overridden))}"
+            )
+
+        cls._instance.agents.update(custom_agents)
         return cls._instance

sgr_deep_research/core/agent_definition.py

@@ -176,4 +176,6 @@ def from_yaml(cls, yaml_path: str) -> Self:
 
 
 class Definitions(BaseModel):
-    agents: list[AgentDefinition] = Field(default_factory=list, description="List of agent definitions")
+    agents: dict[str, AgentDefinition] = Field(
+        default_factory=dict, description="Dictionary of agent definitions by name"
+    )

sgr_deep_research/core/agent_factory.py

@@ -8,7 +8,6 @@
 
 from sgr_deep_research.core.agent_config import GlobalConfig
 from sgr_deep_research.core.agent_definition import AgentDefinition, LLMConfig
-from sgr_deep_research.core.agents.definitions import get_default_agents_definitions
 from sgr_deep_research.core.base_agent import BaseAgent
 from sgr_deep_research.core.services import AgentRegistry, MCP2ToolConverter, ToolRegistry
 
@@ -108,15 +107,10 @@ async def create(cls, agent_def: AgentDefinition, task: str) -> Agent:
 
     @classmethod
     def get_definitions_list(cls) -> list[AgentDefinition]:
-        """Get all agent definitions (default + custom from config).
+        """Get all agent definitions from config.
 
         Returns:
-            List of agent definitions (default agents + custom agents from config)
+            List of agent definitions from config
         """
         config = GlobalConfig()
-
-        all_agents = {agent.name: agent for agent in get_default_agents_definitions()}
-        if will_be_rewritten := set(all_agents.keys()).intersection({agent.name for agent in config.agents}):
-            logger.warning(f"Custom agents with names {', '.join(will_be_rewritten)} will override default agents.")
-        all_agents.update({agent.name: agent for agent in config.agents})
-        return list(all_agents.values())
+        return list(config.agents.values())

sgr_deep_research/core/agents/__init__.py

@@ -1,6 +1,5 @@
 """Agents module for SGR Deep Research."""
 
-from sgr_deep_research.core.agents.definitions import get_default_agents_definitions
 from sgr_deep_research.core.agents.sgr_agent import SGRResearchAgent
 from sgr_deep_research.core.agents.sgr_auto_tools_agent import SGRAutoToolCallingResearchAgent
 from sgr_deep_research.core.agents.sgr_so_tools_agent import SGRSOToolCallingResearchAgent
@@ -13,5 +12,4 @@
     "SGRAutoToolCallingResearchAgent",
     "ToolCallingResearchAgent",
     "SGRSOToolCallingResearchAgent",
-    "get_default_agents_definitions",
 ]

sgr_deep_research/core/agents/definitions.py renamed to sgr_deep_research/default_definitions.py

@@ -17,16 +17,16 @@
 ]
 
 
-def get_default_agents_definitions() -> list[AgentDefinition]:
+def get_default_agents_definitions() -> dict[str, AgentDefinition]:
     """Get default agent definitions.
 
     This function creates agent definitions lazily to avoid issues with
     configuration initialization order.
 
     Returns:
-        List of default agent definitions
+        Dictionary of default agent definitions keyed by agent name
     """
-    return [
+    agents = [
         AgentDefinition(
             name="sgr_agent",
             base_class=SGRResearchAgent,
@@ -53,3 +53,4 @@ def get_default_agents_definitions() -> list[AgentDefinition]:
             tools=DEFAULT_TOOLKIT,
         ),
     ]
+    return {agent.name: agent for agent in agents}