Refactor Foundry agent and factory imports, improve logic

Updated import paths from 'v3' to 'af' for consistency and modularity. Improved error handling, logging, and tool/resource collection logic in FoundryAgentTemplate. Cleaned up unused Bing references and clarified code interpreter and MCP tool handling. These changes enhance maintainability and agent lifecycle management.

Author: Fr4nc3

src/backend/af/magentic_agents/foundry_agent.py

@@ -1,22 +1,22 @@
-"""Agent template for building foundry agents with Azure AI Search, Bing, and MCP plugins (agent_framework version)."""
+"""Agent template for building Foundry agents with Azure AI Search, optional MCP tool, and Code Interpreter (agent_framework version)."""
 
 import logging
 from typing import List, Optional
 
 from azure.ai.agents.models import Agent, AzureAISearchTool, CodeInterpreterToolDefinition
 from agent_framework.azure import AzureAIAgentClient
-from agent_framework import ChatMessage, Role, ChatOptions, HostedMCPTool  # HostedMCPTool for MCP plugin mapping
+from agent_framework import ChatMessage, Role, ChatOptions, HostedMCPTool
 
-from v3.magentic_agents.common.lifecycle import AzureAgentBase
-from v3.magentic_agents.models.agent_models import MCPConfig, SearchConfig
-from v3.config.agent_registry import agent_registry
+from af.magentic_agents.common.lifecycle import AzureAgentBase
+from af.magentic_agents.models.agent_models import MCPConfig, SearchConfig
+from af.config.agent_registry import agent_registry
 
-# exception too broad warning
+# Broad exception flag
 # pylint: disable=w0718
 
 
 class FoundryAgentTemplate(AzureAgentBase):
-    """Agent that uses Azure AI Search (RAG) and optional MCP tools via agent_framework."""
+    """Agent that uses Azure AI Search (RAG) and optional MCP tool via agent_framework."""
 
     def __init__(
         self,
@@ -26,7 +26,6 @@ def __init__(
         model_deployment_name: str,
         enable_code_interpreter: bool = False,
         mcp_config: MCPConfig | None = None,
-        # bing_config: BingConfig | None = None,
         search_config: SearchConfig | None = None,
     ) -> None:
         super().__init__(mcp=mcp_config)
@@ -35,85 +34,91 @@ def __init__(
         self.agent_instructions = agent_instructions
         self.model_deployment_name = model_deployment_name
         self.enable_code_interpreter = enable_code_interpreter
-        # self.bing = bing_config
         self.mcp = mcp_config
         self.search = search_config
+
         self._search_connection = None
-        self._bing_connection = None
         self.logger = logging.getLogger(__name__)
 
-        if self.model_deployment_name in ["o3", "o4-mini"]:
-            raise ValueError(
-                "The current version of Foundry agents does not support reasoning models."
-            )
+        if self.model_deployment_name in {"o3", "o4-mini"}:
+            raise ValueError("Foundry agents do not support reasoning models in this implementation.")
 
+    # -------------------------
+    # Tool construction helpers
+    # -------------------------
     async def _make_azure_search_tool(self) -> Optional[AzureAISearchTool]:
-        """Create Azure AI Search tool for RAG capabilities."""
-        if not all([self.client, self.search and self.search.connection_name, self.search and self.search.index_name]):
-            self.logger.info("Azure AI Search tool not enabled")
+        """Create Azure AI Search tool (RAG capability)."""
+        if not (self.client and self.search and self.search.connection_name and self.search.index_name):
+            self.logger.info("Azure AI Search tool not enabled (missing config or client).")
             return None
 
         try:
-            self._search_connection = await self.client.connections.get(
-                name=self.search.connection_name
-            )
+            self._search_connection = await self.client.connections.get(name=self.search.connection_name)
             self.logger.info("Found Azure AI Search connection: %s", self._search_connection.id)
 
-            search_tool = AzureAISearchTool(
+            return AzureAISearchTool(
                 index_connection_id=self._search_connection.id,
                 index_name=self.search.index_name,
             )
-            self.logger.info("Azure AI Search tool created for index: %s", self.search.index_name)
-            return search_tool
-
         except Exception as ex:
             self.logger.error(
-                "Azure AI Search tool creation failed: %s | Connection name: %s | Index name: %s | "
-                "Ensure the connection exists in Azure AI Foundry portal.",
+                "Azure AI Search tool creation failed: %s | connection=%s | index=%s",
                 ex,
                 getattr(self.search, "connection_name", None),
                 getattr(self.search, "index_name", None),
             )
             return None
 
     async def _collect_tools_and_resources(self) -> tuple[List, dict]:
-        """Collect all available tools and tool_resources to embed in persistent agent definition."""
+        """Collect tool definitions + tool_resources for agent definition creation."""
         tools: List = []
         tool_resources: dict = {}
 
+        # Search tool
         if self.search and self.search.connection_name and self.search.index_name:
             search_tool = await self._make_azure_search_tool()
             if search_tool:
                 tools.extend(search_tool.definitions)
                 tool_resources = search_tool.resources
                 self.logger.info(
-                    "Added Azure AI Search tools: %d tool definitions", len(search_tool.definitions)
+                    "Added %d Azure AI Search tool definitions.",
+                    len(search_tool.definitions),
                 )
             else:
-                self.logger.error("Azure AI Search tool not configured properly")
+                self.logger.warning("Azure AI Search tool not configured properly.")
 
+        # Code Interpreter
         if self.enable_code_interpreter:
             try:
                 tools.append(CodeInterpreterToolDefinition())
-                self.logger.info("Added Code Interpreter tool")
+                self.logger.info("Added Code Interpreter tool definition.")
             except ImportError as ie:
-                self.logger.error("Code Interpreter tool requires additional dependencies: %s", ie)
+                self.logger.error("Code Interpreter dependency missing: %s", ie)
 
-        self.logger.info("Total tools configured in definition: %d", len(tools))
+        self.logger.info("Total tool definitions collected: %d", len(tools))
         return tools, tool_resources
 
+    # -------------------------
+    # Agent lifecycle override
+    # -------------------------
     async def _after_open(self) -> None:
-        """Build or reuse the Azure AI agent definition; create agent_framework client."""
+        """Create or reuse Azure AI agent definition and wrap with AzureAIAgentClient."""
         definition = await self._get_azure_ai_agent_definition(self.agent_name)
 
         if definition is not None:
-            connection_compatible = await self._check_connection_compatibility(definition)
-            if not connection_compatible:
-                await self.client.agents.delete_agent(definition.id)
-                self.logger.info(
-                    "Existing agent '%s' used incompatible connection. Creating new definition.",
-                    self.agent_name,
-                )
+            if not await self._check_connection_compatibility(definition):
+                try:
+                    await self.client.agents.delete_agent(definition.id)
+                    self.logger.info(
+                        "Deleted incompatible existing agent '%s'; will recreate with new connection settings.",
+                        self.agent_name,
+                    )
+                except Exception as ex:
+                    self.logger.warning(
+                        "Failed deleting incompatible agent '%s': %s (will still recreate).",
+                        self.agent_name,
+                        ex,
+                    )
                 definition = None
 
         if definition is None:
@@ -126,138 +131,128 @@ async def _after_open(self) -> None:
                 tools=tools,
                 tool_resources=tool_resources,
             )
+            self.logger.info("Created new Azure AI agent definition '%s'", self.agent_name)
 
+        # Instantiate persistent AzureAIAgentClient bound to existing agent_id
         try:
-            # Wrap existing agent definition with agent_framework client (persistent agent mode)
             self._agent = AzureAIAgentClient(
                 project_client=self.client,
                 agent_id=str(definition.id),
                 agent_name=self.agent_name,
-                thread_id=None,  # created dynamically if omitted during invocation
             )
         except Exception as ex:
             self.logger.error("Failed to initialize AzureAIAgentClient: %s", ex)
             raise
 
-        # Register with global registry
+        # Register agent globally
         try:
             agent_registry.register_agent(self)
-            self.logger.info("📝 Registered agent '%s' with global registry", self.agent_name)
-        except Exception as registry_error:
-            self.logger.warning(
-                "⚠️ Failed to register agent '%s' with registry: %s", self.agent_name, registry_error
-            )
-
-    async def fetch_run_details(self, thread_id: str, run_id: str) -> None:
-        """Fetch and log run details on failure for diagnostics."""
-        try:
-            run = await self.client.agents.runs.get(thread=thread_id, run=run_id)
-            self.logger.error(
-                "Run failure details | status=%s | id=%s | last_error=%s | usage=%s",
-                getattr(run, "status", None),
-                run_id,
-                getattr(run, "last_error", None),
-                getattr(run, "usage", None),
-            )
-        except Exception as ex:
-            self.logger.error("Could not fetch run details: %s", ex)
+            self.logger.info("Registered agent '%s' in global registry.", self.agent_name)
+        except Exception as reg_ex:
+            self.logger.warning("Could not register agent '%s': %s", self.agent_name, reg_ex)
 
+    # -------------------------
+    # Definition compatibility
+    # -------------------------
     async def _check_connection_compatibility(self, existing_definition: Agent) -> bool:
-        """Ensure existing agent definition's Azure AI Search connection matches current configuration."""
+        """Verify existing Azure AI Search connection matches current config."""
         try:
-            if not self.search or not self.search.connection_name:
-                self.logger.info("No search configuration provided; treating existing definition as compatible.")
+            if not (self.search and self.search.connection_name):
+                self.logger.info("No search config provided; assuming compatibility.")
                 return True
 
-            if not getattr(existing_definition, "tool_resources", None):
-                self.logger.info("Existing definition lacks tool resources.")
-                return not self.search.connection_name
-
-            azure_ai_search_resources = existing_definition.tool_resources.get("azure_ai_search", {})
-            if not azure_ai_search_resources:
-                self.logger.info("Existing definition has no Azure AI Search resources.")
+            tool_resources = getattr(existing_definition, "tool_resources", None)
+            if not tool_resources:
+                self.logger.info("Existing agent has no tool resources; incompatible with search requirement.")
                 return False
 
-            indexes = azure_ai_search_resources.get("indexes", [])
+            azure_search = tool_resources.get("azure_ai_search", {})
+            indexes = azure_search.get("indexes", [])
             if not indexes:
-                self.logger.info("Existing definition search resources contain no indexes.")
+                self.logger.info("Existing agent has no Azure AI Search indexes; incompatible.")
                 return False
 
-            existing_connection_id = indexes[0].get("index_connection_id")
-            if not existing_connection_id:
-                self.logger.info("Existing definition missing connection ID.")
+            existing_conn_id = indexes[0].get("index_connection_id")
+            if not existing_conn_id:
+                self.logger.info("Existing agent missing index_connection_id; incompatible.")
                 return False
 
             current_connection = await self.client.connections.get(name=self.search.connection_name)
-            current_connection_id = current_connection.id
-            compatible = existing_connection_id == current_connection_id
-
-            if compatible:
-                self.logger.info("Connection compatible: %s", existing_connection_id)
+            same = existing_conn_id == current_connection.id
+            if same:
+                self.logger.info("Search connection compatible: %s", existing_conn_id)
             else:
                 self.logger.info(
-                    "Connection mismatch: existing %s vs current %s",
-                    existing_connection_id,
-                    current_connection_id,
+                    "Search connection mismatch: existing=%s current=%s",
+                    existing_conn_id,
+                    current_connection.id,
                 )
-            return compatible
+            return same
         except Exception as ex:
-            self.logger.error("Error checking connection compatibility: %s", ex)
+            self.logger.error("Error during connection compatibility check: %s", ex)
             return False
 
     async def _get_azure_ai_agent_definition(self, agent_name: str) -> Agent | None:
-        """Retrieve an existing Azure AI Agent definition by name if present."""
+        """Return existing agent definition by name or None."""
         try:
-            agent_id = None
-            agent_list = self.client.agents.list_agents()
-            async for agent in agent_list:
+            async for agent in self.client.agents.list_agents():
                 if agent.name == agent_name:
-                    agent_id = agent.id
-                    break
-            if agent_id is not None:
-                self.logger.info("Found existing agent definition with ID %s", agent_id)
-                return await self.client.agents.get_agent(agent_id)
+                    self.logger.info("Found existing agent '%s' (id=%s).", agent_name, agent.id)
+                    return await self.client.agents.get_agent(agent.id)
             return None
         except Exception as e:
             if "ResourceNotFound" in str(e) or "404" in str(e):
-                self.logger.info("Agent '%s' not found; will create new definition.", agent_name)
+                self.logger.info("Agent '%s' not found; will create new.", agent_name)
             else:
                 self.logger.warning(
-                    "Unexpected error retrieving agent '%s': %s. Proceeding to create new definition.",
+                    "Unexpected error listing agent '%s': %s; will attempt creation.",
                     agent_name,
                     e,
                 )
             return None
 
+    # -------------------------
+    # Diagnostics helper
+    # -------------------------
+    async def fetch_run_details(self, thread_id: str, run_id: str) -> None:
+        """Log run diagnostics for a failed run."""
+        try:
+            run = await self.client.agents.runs.get(thread=thread_id, run=run_id)
+            self.logger.error(
+                "Run failure | status=%s | id=%s | last_error=%s | usage=%s",
+                getattr(run, "status", None),
+                run_id,
+                getattr(run, "last_error", None),
+                getattr(run, "usage", None),
+            )
+        except Exception as ex:
+            self.logger.error("Failed fetching run details (thread=%s run=%s): %s", thread_id, run_id, ex)
+
+    # -------------------------
+    # Invocation (streaming)
+    # -------------------------
     async def invoke(self, prompt: str):
         """
         Stream model output for a prompt.
 
-        Yields agent_framework ChatResponseUpdate objects:
-        - update.text for incremental text
-        - update.contents for tool calls / usage events
+        Yields ChatResponseUpdate objects:
+          - update.text for incremental text
+          - update.contents for tool calls / usage events
         """
-        if not hasattr(self, "_agent") or self._agent is None:
+        if not self._agent:
             raise RuntimeError("Agent client not initialized; call open() first.")
 
         messages = [ChatMessage(role=Role.USER, text=prompt)]
 
         tools = []
-        # Map MCP plugin (if any) to HostedMCPTool for runtime tool calling
-        if self.mcp_plugin:
-            # Minimal HostedMCPTool; advanced mapping (approval modes, categories) can be added later.
-            tools.append(
-                HostedMCPTool(
-                    name=self.mcp_plugin.name,
-                    server_label=self.mcp_plugin.name.replace(" ", "_"),
-                    description=getattr(self.mcp_plugin, "description", ""),
-                )
-            )
+        # Use mcp_tool prepared in AzureAgentBase
+        if self.mcp_tool and isinstance(self.mcp_tool, HostedMCPTool):
+            tools.append(self.mcp_tool)
 
         chat_options = ChatOptions(
             model_id=self.model_deployment_name,
             tools=tools if tools else None,
-            tool_choice="auto",
+            tool_choice="auto" if tools else "none",
             allow_multiple_tool_calls=True,
             temperature=0.7,
         )
@@ -270,24 +265,25 @@ async def invoke(self, prompt: str):
             yield update
 
 
+# -------------------------
+# Factory
+# -------------------------
 async def create_foundry_agent(
     agent_name: str,
     agent_description: str,
     agent_instructions: str,
     model_deployment_name: str,
-    mcp_config: MCPConfig,
-    # bing_config: BingConfig,
-    search_config: SearchConfig,
+    mcp_config: MCPConfig | None,
+    search_config: SearchConfig | None,
 ) -> FoundryAgentTemplate:
-    """Factory function to create and open a FoundryAgentTemplate (agent_framework version)."""
+    """Factory to create and open a FoundryAgentTemplate (agent_framework version)."""
     agent = FoundryAgentTemplate(
         agent_name=agent_name,
         agent_description=agent_description,
         agent_instructions=agent_instructions,
         model_deployment_name=model_deployment_name,
         enable_code_interpreter=True,
         mcp_config=mcp_config,
-        # bing_config=bing_config,
         search_config=search_config,
     )
     await agent.open()