solana-agent 27.4.3__py3-none-any.whl → 28.0.0__py3-none-any.whl

solana_agent/services/agent.py

@@ -9,6 +9,8 @@ import asyncio
 import datetime as main_datetime
 from datetime import datetime
 import json
+import logging  # Add logging
+import re
 from typing import AsyncGenerator, Dict, List, Literal, Optional, Any, Union
 
 from solana_agent.interfaces.services.agent import AgentService as AgentServiceInterface
@@ -16,6 +18,11 @@ from solana_agent.interfaces.providers.llm import LLMProvider
 from solana_agent.plugins.manager import PluginManager
 from solana_agent.plugins.registry import ToolRegistry
 from solana_agent.domains.agent import AIAgent, BusinessMission
+from solana_agent.interfaces.guardrails.guardrails import (
+    OutputGuardrail,
+)
+
+logger = logging.getLogger(__name__)  # Add logger
 
 
 class AgentService(AgentServiceInterface):
@@ -29,6 +36,9 @@ class AgentService(AgentServiceInterface):
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
         model: Optional[str] = None,
+        output_guardrails: List[
+            OutputGuardrail
+        ] = None,  # <-- Add output_guardrails parameter
     ):
         """Initialize the agent service.
 
@@ -36,6 +46,10 @@ class AgentService(AgentServiceInterface):
             llm_provider: Provider for language model interactions
             business_mission: Optional business mission and values
             config: Optional service configuration
+            api_key: API key for the LLM provider
+            base_url: Base URL for the LLM provider
+            model: Model name for the LLM provider
+            output_guardrails: List of output guardrail instances
         """
         self.llm_provider = llm_provider
         self.business_mission = business_mission
@@ -46,6 +60,7 @@ class AgentService(AgentServiceInterface):
         self.api_key = api_key
         self.base_url = base_url
         self.model = model
+        self.output_guardrails = output_guardrails or []  # <-- Store guardrails
 
         self.plugin_manager = PluginManager(
             config=self.config,
@@ -71,6 +86,7 @@ class AgentService(AgentServiceInterface):
             specialization=specialization,
         )
         self.agents.append(agent)
+        logger.info(f"Registered AI agent: {name}")
 
     def get_agent_system_prompt(self, agent_name: str) -> str:
         """Get the system prompt for an agent.
@@ -152,30 +168,174 @@ class AgentService(AgentServiceInterface):
         """Execute a tool on behalf of an agent."""
 
         if not self.tool_registry:
+            logger.error("Tool registry not available during tool execution.")
             return {"status": "error", "message": "Tool registry not available"}
 
         tool = self.tool_registry.get_tool(tool_name)
         if not tool:
+            logger.warning(f"Tool '{tool_name}' not found for execution.")
             return {"status": "error", "message": f"Tool '{tool_name}' not found"}
 
         # Check if agent has access to this tool
         agent_tools = self.tool_registry.get_agent_tools(agent_name)
 
         if not any(t.get("name") == tool_name for t in agent_tools):
+            logger.warning(
+                f"Agent '{agent_name}' attempted to use unassigned tool '{tool_name}'."
+            )
             return {
                 "status": "error",
                 "message": f"Agent '{agent_name}' doesn't have access to tool '{tool_name}'",
             }
 
         try:
+            logger.info(
+                f"Executing tool '{tool_name}' for agent '{agent_name}' with params: {parameters}"
+            )
             result = await tool.execute(**parameters)
+            logger.info(
+                f"Tool '{tool_name}' execution result status: {result.get('status')}"
+            )
             return result
         except Exception as e:
             import traceback
 
-            print(traceback.format_exc())
+            logger.error(
+                f"Error executing tool '{tool_name}': {e}\n{traceback.format_exc()}"
+            )
             return {"status": "error", "message": f"Error executing tool: {str(e)}"}
 
+    # --- Helper function to recursively substitute placeholders ---
+    def _substitute_placeholders(self, data: Any, results_map: Dict[str, str]) -> Any:
+        """Recursively substitutes placeholders like {{tool_name.result}} or {output_of_tool_name} in strings."""
+        if isinstance(data, str):
+            # Regex to find placeholders like {{tool_name.result}} or {output_of_tool_name}
+            placeholder_pattern = re.compile(
+                r"\{\{(?P<name1>[a-zA-Z0-9_]+)\.result\}\}|\{output_of_(?P<name2>[a-zA-Z0-9_]+)\}"
+            )
+
+            def replace_match(match):
+                tool_name = match.group("name1") or match.group("name2")
+                if tool_name and tool_name in results_map:
+                    logger.debug(f"Substituting placeholder for '{tool_name}'")
+                    return results_map[tool_name]
+                else:
+                    # If placeholder not found, leave it as is but log warning
+                    logger.warning(
+                        f"Could not find result for placeholder tool '{tool_name}'. Leaving placeholder."
+                    )
+                    return match.group(0)  # Return original placeholder
+
+            # Use re.sub with the replacement function
+            return placeholder_pattern.sub(replace_match, data)
+        elif isinstance(data, dict):
+            # Recursively process dictionary values
+            return {
+                k: self._substitute_placeholders(v, results_map)
+                for k, v in data.items()
+            }
+        elif isinstance(data, list):
+            # Recursively process list items
+            return [self._substitute_placeholders(item, results_map) for item in data]
+        else:
+            # Return non-string/dict/list types as is
+            return data
+
+    # --- Helper to parse tool calls ---
+    def _parse_tool_calls(self, text: str) -> List[Dict[str, Any]]:
+        """Parses all [TOOL]...[/TOOL] blocks in the text."""
+        tool_calls = []
+        # Regex to find all tool blocks, non-greedy match for content
+        pattern = re.compile(r"\[TOOL\](.*?)\[/TOOL\]", re.DOTALL | re.IGNORECASE)
+        matches = pattern.finditer(text)
+
+        for match in matches:
+            tool_content = match.group(1).strip()
+            tool_name = None
+            parameters = {}
+            try:
+                for line in tool_content.split("\n"):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    if line.lower().startswith("name:"):
+                        tool_name = line[5:].strip()
+                    elif line.lower().startswith("parameters:"):
+                        params_text = line[11:].strip()
+                        try:
+                            # Prefer JSON parsing
+                            parameters = json.loads(params_text)
+                        except json.JSONDecodeError:
+                            logger.warning(
+                                f"Failed to parse parameters as JSON, falling back: {params_text}"
+                            )
+                            # Fallback: Treat as simple key=value (less robust)
+                            try:
+                                # Basic eval might work for {"key": "value"} but is risky
+                                # parameters = eval(params_text) # Avoid eval if possible
+                                # Safer fallback: Assume simple string if not JSON-like
+                                if not params_text.startswith("{"):
+                                    # Try splitting key=value pairs? Very brittle.
+                                    # For now, log warning and skip complex fallback parsing
+                                    logger.error(
+                                        f"Cannot parse non-JSON parameters reliably: {params_text}"
+                                    )
+                                    parameters = {
+                                        "_raw_params": params_text
+                                    }  # Store raw string
+                                else:
+                                    # If it looks like a dict but isn't valid JSON, log error
+                                    logger.error(
+                                        f"Invalid dictionary format for parameters: {params_text}"
+                                    )
+                                    parameters = {"_raw_params": params_text}
+
+                            except Exception as parse_err:
+                                logger.error(
+                                    f"Fallback parameter parsing failed: {parse_err}"
+                                )
+                                parameters = {
+                                    "_raw_params": params_text
+                                }  # Store raw string on error
+
+                if tool_name:
+                    tool_calls.append({"name": tool_name, "parameters": parameters})
+                else:
+                    logger.warning(f"Parsed tool block missing name: {tool_content}")
+            except Exception as e:
+                logger.error(f"Error parsing tool content: {tool_content} - {e}")
+
+        logger.info(f"Parsed {len(tool_calls)} tool calls from response.")
+        return tool_calls
+
+    # --- Helper to execute a single parsed tool call ---
+    async def _execute_single_tool(
+        self, agent_name: str, tool_call: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Executes a single tool call dictionary and returns its result."""
+        tool_name = tool_call.get("name")
+        parameters = tool_call.get("parameters", {})
+        if not tool_name:
+            return {
+                "tool_name": "unknown",
+                "status": "error",
+                "message": "Tool name missing in parsed call",
+            }
+        # Ensure parameters is a dict, even if parsing failed
+        if not isinstance(parameters, dict):
+            logger.warning(
+                f"Parameters for tool '{tool_name}' is not a dict: {parameters}. Attempting execution with empty params."
+            )
+            parameters = {}
+
+        logger.debug(
+            f"Preparing to execute tool '{tool_name}' with params: {parameters}"
+        )
+        result = await self.execute_tool(agent_name, tool_name, parameters)
+        # Add tool name to result for easier aggregation
+        result["tool_name"] = tool_name
+        return result
+
     async def generate_response(
         self,
         agent_name: str,
@@ -201,11 +361,17 @@ class AgentService(AgentServiceInterface):
         ] = "aac",
         prompt: Optional[str] = None,
     ) -> AsyncGenerator[Union[str, bytes], None]:  # pragma: no cover
-        """Generate a response with support for text/audio input/output."""
+        """Generate a response, supporting multiple sequential tool calls with placeholder substitution.
+
+        Text responses are always generated as a single block.
+        Audio responses always buffer text before TTS.
+        """
         agent = next((a for a in self.agents if a.name == agent_name), None)
         if not agent:
             error_msg = f"Agent '{agent_name}' not found."
+            logger.warning(error_msg)
             if output_format == "audio":
+                # Assuming tts returns an async generator
                 async for chunk in self.llm_provider.tts(
                     error_msg,
                     instructions=audio_instructions,
@@ -214,264 +380,315 @@ class AgentService(AgentServiceInterface):
                 ):
                     yield chunk
             else:
-                yield error_msg
+                yield error_msg  # Yield the single error string
             return
 
+        logger.debug(
+            f"Generating response for agent '{agent_name}'. Output format: {output_format}."
+        )
+
         try:
-            # --- 1. Get Base System Prompt ---
+            # --- System Prompt Assembly ---
             system_prompt_parts = [self.get_agent_system_prompt(agent_name)]
-
-            # --- 2. Add Tool Usage Instructions EARLY ---
-            tool_usage_prompt_text = ""
-            if self.tool_registry:
-                tool_usage_prompt_text = self._get_tool_usage_prompt(agent_name)
-                if tool_usage_prompt_text:
-                    system_prompt_parts.append(
-                        f"\n\n--- TOOL USAGE INSTRUCTIONS ---{tool_usage_prompt_text}"
-                    )
-                    print(
-                        f"Tools available to agent {agent_name}: {[t.get('name') for t in self.get_agent_tools(agent_name)]}"
-                    )
-
-            # --- 3. Add User ID ---
-            system_prompt_parts.append("\n\n--- USER & SESSION INFO ---")
-            system_prompt_parts.append(f"User ID: {user_id}")
-
-            # --- 4. Add Memory Context ---
+            tool_instructions = self._get_tool_usage_prompt(agent_name)
+            if tool_instructions:
+                system_prompt_parts.append(tool_instructions)
+            system_prompt_parts.append(f"USER IDENTIFIER: {user_id}")
             if memory_context:
-                # Make the header clearly separate it
-                system_prompt_parts.append(
-                    "\n\n--- CONVERSATION HISTORY (Memory Context) ---"
-                )
-                system_prompt_parts.append(memory_context)
-
-            # --- 5. Add Additional Prompt (if provided) ---
+                system_prompt_parts.append(f"\nCONVERSATION HISTORY:\n{memory_context}")
             if prompt:
-                # Make the header clearly separate it
-                system_prompt_parts.append(
-                    "\n\n--- ADDITIONAL INSTRUCTIONS FOR THIS TURN ---"
-                )
-                system_prompt_parts.append(prompt)
-
-            # --- Assemble the final system prompt ---
-            final_system_prompt = "\n".join(system_prompt_parts)
+                system_prompt_parts.append(f"\nADDITIONAL PROMPT:\n{prompt}")
+            final_system_prompt = "\n\n".join(filter(None, system_prompt_parts))
 
-            # Variables for tracking the complete response
-            complete_text_response = ""
-            full_response_buffer = ""
-
-            # Variables for robust handling of tool call markers that may be split across chunks
-            tool_buffer = ""
-            pending_chunk = ""  # To hold text that might contain partial markers
-            is_tool_call = False
-
-            # Define start and end markers
+            # --- Initial Response Generation (No Streaming) ---
+            initial_llm_response_buffer = ""
+            tool_calls_detected = False
             start_marker = "[TOOL]"
-            end_marker = "[/TOOL]"
 
-            # Generate and stream response (ALWAYS use non-realtime for text generation)
-            print(f"Generating response with {len(query)} characters of query text")
-            async for chunk in self.llm_provider.generate_text(
-                prompt=query,
+            logger.info(f"Generating initial response for agent '{agent_name}'...")
+            # Call generate_text and await the string result
+            initial_llm_response_buffer = await self.llm_provider.generate_text(
+                prompt=str(query),
                 system_prompt=final_system_prompt,
                 api_key=self.api_key,
                 base_url=self.base_url,
                 model=self.model,
+            )
+
+            # Check for errors returned as string by the adapter
+            if isinstance(
+                initial_llm_response_buffer, str
+            ) and initial_llm_response_buffer.startswith(
+                "I apologize, but I encountered an error"
             ):
-                # If we have pending text from the previous chunk, combine it with this chunk
-                if pending_chunk:
-                    combined_chunk = pending_chunk + chunk
-                    pending_chunk = ""  # Reset pending chunk
+                logger.error(
+                    f"LLM provider failed during initial generation: {initial_llm_response_buffer}"
+                )
+                # Yield the error and exit
+                if output_format == "audio":
+                    async for chunk in self.llm_provider.tts(
+                        initial_llm_response_buffer,
+                        voice=audio_voice,
+                        response_format=audio_output_format,
+                        instructions=audio_instructions,
+                    ):
+                        yield chunk
                 else:
-                    combined_chunk = chunk
-
-                # STEP 1: Check for tool call start marker
-                if start_marker in combined_chunk and not is_tool_call:
-                    print(
-                        f"Found tool start marker in chunk of length {len(combined_chunk)}"
+                    yield initial_llm_response_buffer
+                return
+
+            # Check for tool markers in the complete response
+            if start_marker.lower() in initial_llm_response_buffer.lower():
+                tool_calls_detected = True
+                logger.info("Tool call marker detected in initial response.")
+
+            logger.debug(
+                f"Full initial LLM response buffer:\n--- START ---\n{initial_llm_response_buffer}\n--- END ---"
+            )
+            logger.info(
+                f"Initial LLM response received (length: {len(initial_llm_response_buffer)}). Tools detected: {tool_calls_detected}"
+            )
+
+            # --- Tool Execution Phase (if tools were detected) ---
+            final_response_text = ""
+            if tool_calls_detected:
+                parsed_calls = self._parse_tool_calls(initial_llm_response_buffer)
+
+                if parsed_calls:
+                    # --- Execute tools SEQUENTIALLY with Placeholder Substitution ---
+                    executed_tool_results = []  # Store full result dicts
+                    # Map tool names to their string results for substitution
+                    tool_results_map: Dict[str, str] = {}
+
+                    logger.info(
+                        f"Executing {len(parsed_calls)} tools sequentially with substitution..."
                     )
-                    is_tool_call = True
-
-                    # Extract text before the marker and the marker itself with everything after
-                    start_pos = combined_chunk.find(start_marker)
-                    before_marker = combined_chunk[:start_pos]
-                    after_marker = combined_chunk[start_pos:]
-
-                    # Yield text that appeared before the marker
-                    if before_marker and output_format == "text":
-                        yield before_marker
-
-                    # Start collecting the tool call
-                    tool_buffer = after_marker
-                    continue  # Skip to next chunk
-
-                # STEP 2: Handle ongoing tool call collection
-                if is_tool_call:
-                    tool_buffer += combined_chunk
-
-                    # Check if the tool call is complete
-                    if end_marker in tool_buffer:
-                        print(f"Tool call complete, buffer size: {len(tool_buffer)}")
-
-                        # Process the tool call
-                        response_text = await self._handle_tool_call(
-                            agent_name=agent_name, tool_text=tool_buffer
+                    for i, call in enumerate(parsed_calls):
+                        tool_name_to_exec = call.get("name", "unknown")
+                        logger.info(
+                            f"Executing tool {i + 1}/{len(parsed_calls)}: {tool_name_to_exec}"
                         )
 
-                        # Clean the response to remove any markers or formatting
-                        response_text = self._clean_tool_response(response_text)
-                        print(
-                            f"Tool execution complete, result size: {len(response_text)}"
-                        )
+                        # --- Substitute placeholders in parameters ---
+                        try:
+                            original_params = call.get("parameters", {})
+                            substituted_params = self._substitute_placeholders(
+                                original_params, tool_results_map
+                            )
+                            if substituted_params != original_params:
+                                logger.info(
+                                    f"Substituted parameters for tool '{tool_name_to_exec}': {substituted_params}"
+                                )
+                            call["parameters"] = substituted_params  # Update call dict
+                        except Exception as sub_err:
+                            logger.error(
+                                f"Error substituting placeholders for tool '{tool_name_to_exec}': {sub_err}",
+                                exc_info=True,
+                            )
+                            # Proceed with original params but log the error
+
+                        # --- Execute the tool ---
+                        try:
+                            result = await self._execute_single_tool(agent_name, call)
+                            executed_tool_results.append(result)
+
+                            # --- Store successful result string for future substitutions ---
+                            if result.get("status") == "success":
+                                tool_result_str = str(result.get("result", ""))
+                                tool_results_map[tool_name_to_exec] = tool_result_str
+                                logger.debug(
+                                    f"Stored result for '{tool_name_to_exec}' (length: {len(tool_result_str)})"
+                                )
+                            else:
+                                # Store error message as result
+                                error_message = result.get("message", "Unknown error")
+                                tool_results_map[tool_name_to_exec] = (
+                                    f"Error: {error_message}"
+                                )
+                                logger.warning(
+                                    f"Tool '{tool_name_to_exec}' failed, storing error message as result."
+                                )
+
+                        except Exception as tool_exec_err:
+                            logger.error(
+                                f"Exception during execution of tool {tool_name_to_exec}: {tool_exec_err}",
+                                exc_info=True,
+                            )
+                            error_result = {
+                                "tool_name": tool_name_to_exec,
+                                "status": "error",
+                                "message": f"Exception during execution: {str(tool_exec_err)}",
+                            }
+                            executed_tool_results.append(error_result)
+                            tool_results_map[tool_name_to_exec] = (
+                                f"Error: {str(tool_exec_err)}"  # Store error
+                            )
 
-                        # Create new prompt with search/tool results
-                        # Ensure query is string
-                        user_prompt = f"{str(query)}\n\nTOOL RESULT: {response_text}"
+                    logger.info("Sequential tool execution with substitution complete.")
+                    # --- End Sequential Execution ---
+
+                    # Format results for the follow-up prompt (use executed_tool_results)
+                    tool_results_text_parts = []
+                    for i, result in enumerate(
+                        executed_tool_results
+                    ):  # Use the collected results
+                        tool_name = result.get(
+                            "tool_name", "unknown"
+                        )  # Name should be in the result dict now
+                        if (
+                            isinstance(result, Exception)
+                            or result.get("status") == "error"
+                        ):
+                            error_msg = (
+                                result.get("message", str(result))
+                                if isinstance(result, dict)
+                                else str(result)
+                            )
+                            logger.error(f"Tool '{tool_name}' failed: {error_msg}")
+                            tool_results_text_parts.append(
+                                f"Tool {i + 1} ({tool_name}) Execution Failed:\n{error_msg}"
+                            )
+                        else:
+                            tool_output = str(result.get("result", ""))
+                            tool_results_text_parts.append(
+                                f"Tool {i + 1} ({tool_name}) Result:\n{tool_output}"
+                            )
+                    tool_results_context = "\n\n".join(tool_results_text_parts)
 
-                        # --- REBUILD the system prompt for the follow-up call ---
-                        # Start with base prompt again
-                        follow_up_system_prompt_parts = [
-                            self.get_agent_system_prompt(agent_name)
-                        ]
-                        # Add the instruction NOT to use tools again
+                    # --- Generate Final Response using Tool Results (No Streaming) ---
+                    follow_up_prompt = f"Original Query: {str(query)}\n\nRESULTS FROM TOOL CALLS:\n{tool_results_context}\n\nBased on the original query and the tool results, please provide the final response to the user."
+                    # Rebuild system prompt
+                    follow_up_system_prompt_parts = [
+                        self.get_agent_system_prompt(agent_name)
+                    ]
+                    follow_up_system_prompt_parts.append(f"USER IDENTIFIER: {user_id}")
+                    if memory_context:
                         follow_up_system_prompt_parts.append(
-                            "\n\nCRITICAL: You have received the results from a tool. Base your response on the 'Search Result' provided in the user prompt. DO NOT use the tool calling format again for this turn."
+                            f"\nORIGINAL CONVERSATION HISTORY:\n{memory_context}"
                         )
+                    if prompt:
                         follow_up_system_prompt_parts.append(
-                            "\n\n--- USER & SESSION INFO ---"
+                            f"\nORIGINAL ADDITIONAL PROMPT:\n{prompt}"
                         )
-                        follow_up_system_prompt_parts.append(f"User ID: {user_id}")
-                        if memory_context:
-                            # Make the header clearly separate it
-                            follow_up_system_prompt_parts.append(
-                                "\n\n--- CONVERSATION HISTORY (Memory Context) ---"
-                            )
-                            follow_up_system_prompt_parts.append(memory_context)
-                        if prompt:
-                            # Make the header clearly separate it
-                            follow_up_system_prompt_parts.append(
-                                "\n\n--- ADDITIONAL INSTRUCTIONS FOR THIS TURN ---"
-                            )
-                            follow_up_system_prompt_parts.append(prompt)
+                    follow_up_system_prompt_parts.append(
+                        f"\nCONTEXT: You previously decided to run {len(parsed_calls)} tool(s) sequentially to answer the query. The results are provided above."
+                    )
+                    final_follow_up_system_prompt = "\n\n".join(
+                        filter(None, follow_up_system_prompt_parts)
+                    )
+
+                    logger.info(
+                        "Generating final response incorporating tool results..."
+                    )
+                    # Call generate_text and await the string result
+                    synthesized_response_buffer = await self.llm_provider.generate_text(
+                        prompt=follow_up_prompt,
+                        system_prompt=final_follow_up_system_prompt,
+                        api_key=self.api_key,
+                        base_url=self.base_url,
+                        model=self.model,
+                    )
 
-                        # --- Assemble the final follow_up prompt ---
-                        final_follow_up_system_prompt = "\n".join(
-                            follow_up_system_prompt_parts
+                    # Check for errors returned as string by the adapter
+                    if isinstance(
+                        synthesized_response_buffer, str
+                    ) and synthesized_response_buffer.startswith(
+                        "I apologize, but I encountered an error"
+                    ):
+                        logger.error(
+                            f"LLM provider failed during final generation: {synthesized_response_buffer}"
                         )
-                        # --- End Rebuild ---"
-
-                        # Generate a new response with the tool results
-                        print("Generating new response with tool results")
-                        if output_format == "text":
-                            # Stream the follow-up response for text output
-                            async for (
-                                processed_chunk
-                            ) in self.llm_provider.generate_text(
-                                prompt=user_prompt,
-                                system_prompt=final_follow_up_system_prompt,
-                                api_key=self.api_key,
-                                base_url=self.base_url,
-                                model=self.model,
+                        # Yield the error and exit
+                        if output_format == "audio":
+                            async for chunk in self.llm_provider.tts(
+                                synthesized_response_buffer,
+                                voice=audio_voice,
+                                response_format=audio_output_format,
+                                instructions=audio_instructions,
                             ):
-                                complete_text_response += processed_chunk
-                                yield processed_chunk
+                                yield chunk
                         else:
-                            # For audio output, collect the full response first
-                            tool_response = ""
-                            async for (
-                                processed_chunk
-                            ) in self.llm_provider.generate_text(
-                                prompt=user_prompt,
-                                system_prompt=final_follow_up_system_prompt,
-                            ):
-                                tool_response += processed_chunk
-
-                            # Clean and add to our complete text record and audio buffer
-                            tool_response = self._clean_for_audio(tool_response)
-                            complete_text_response += tool_response
-                            full_response_buffer += tool_response
+                            yield synthesized_response_buffer
+                        return
 
-                        # Reset tool handling state
-                        is_tool_call = False
-                        tool_buffer = ""
-                        pending_chunk = ""
-                        break  # Exit the original generation loop after tool processing
-
-                    # Continue collecting tool call content without yielding
-                    continue
-
-                # STEP 3: Check for possible partial start markers at the end of the chunk
-                # This helps detect markers split across chunks
-                potential_marker = False
-                for i in range(1, len(start_marker)):
-                    if combined_chunk.endswith(start_marker[:i]):
-                        # Found a partial marker at the end
-                        # Save the partial marker
-                        pending_chunk = combined_chunk[-i:]
-                        # Everything except the partial marker
-                        chunk_to_yield = combined_chunk[:-i]
-                        potential_marker = True
-                        print(f"Potential partial marker detected: '{pending_chunk}'")
-                        break
-
-                if potential_marker:
-                    # Process the safe part of the chunk
-                    if chunk_to_yield and output_format == "text":
-                        yield chunk_to_yield
-                    if chunk_to_yield:
-                        complete_text_response += chunk_to_yield
-                        if output_format == "audio":
-                            full_response_buffer += chunk_to_yield
-                    continue
-
-                # STEP 4: Normal text processing for non-tool call content
-                if output_format == "text":
-                    yield combined_chunk
-
-                complete_text_response += combined_chunk
-                if output_format == "audio":
-                    full_response_buffer += combined_chunk
+                    final_response_text = synthesized_response_buffer
+                    logger.info(
+                        f"Final synthesized response length: {len(final_response_text)}"
+                    )
 
-            # Process any incomplete tool call as regular text
-            if is_tool_call and tool_buffer:
-                print(
-                    f"Incomplete tool call detected, returning as regular text: {len(tool_buffer)} chars"
+                else:
+                    # Tools detected but parsing failed
+                    logger.warning(
+                        "Tool markers detected, but no valid tool calls parsed. Treating initial response as final."
+                    )
+                    final_response_text = initial_llm_response_buffer
+            else:
+                # No tools detected
+                final_response_text = initial_llm_response_buffer
+                logger.info("No tools detected. Using initial response as final.")
+
+            # --- Final Output Processing (Guardrails, TTS, Yielding) ---
+            processed_final_text = final_response_text
+            if self.output_guardrails:
+                logger.info(
+                    f"Applying output guardrails to final text response (length: {len(processed_final_text)})"
                 )
-                if output_format == "text":
-                    yield tool_buffer
+                original_len = len(processed_final_text)
+                for guardrail in self.output_guardrails:
+                    try:
+                        processed_final_text = await guardrail.process(
+                            processed_final_text
+                        )
+                    except Exception as e:
+                        logger.error(
+                            f"Error applying output guardrail {guardrail.__class__.__name__} to final text: {e}"
+                        )
+                if len(processed_final_text) != original_len:
+                    logger.info(
+                        f"Guardrails modified final text length from {original_len} to {len(processed_final_text)}"
+                    )
 
-                complete_text_response += tool_buffer
-                if output_format == "audio":
-                    full_response_buffer += tool_buffer
+            self.last_text_response = processed_final_text
 
-            # For audio output, generate speech from the complete buffer
-            if output_format == "audio" and full_response_buffer:
-                # Clean text before TTS
-                print(
-                    f"Processing {len(full_response_buffer)} characters for audio output"
+            if output_format == "text":
+                # Yield the single final string
+                if processed_final_text:
+                    yield processed_final_text
+                else:
+                    logger.warning("Final processed text was empty.")
+                    yield ""
+            elif output_format == "audio":
+                # TTS still needs a generator
+                text_for_tts = processed_final_text
+                cleaned_audio_buffer = self._clean_for_audio(text_for_tts)
+                logger.info(
+                    f"Processing {len(cleaned_audio_buffer)} characters for audio output"
                 )
-                full_response_buffer = self._clean_for_audio(full_response_buffer)
-
-                # Process the entire response with TTS
-                async for audio_chunk in self.llm_provider.tts(
-                    text=full_response_buffer,
-                    voice=audio_voice,
-                    response_format=audio_output_format,
-                    instructions=audio_instructions,
-                ):
-                    yield audio_chunk
+                if cleaned_audio_buffer:
+                    async for audio_chunk in self.llm_provider.tts(
+                        text=cleaned_audio_buffer,
+                        voice=audio_voice,
+                        response_format=audio_output_format,
+                        instructions=audio_instructions,
+                    ):
+                        yield audio_chunk
+                else:
+                    logger.warning("Final text for audio was empty after cleaning.")
 
-            # Store the complete text response
-            self.last_text_response = complete_text_response
-            print(f"Response generation complete: {len(complete_text_response)} chars")
+            logger.info(
+                f"Response generation complete for agent '{agent_name}': {len(self.last_text_response)} final chars"
+            )
 
         except Exception as e:
-            error_msg = f"I apologize, but I encountered an error: {str(e)}"
-            print(f"Error in generate_response: {str(e)}")
+            # --- Error Handling ---
             import traceback
 
-            print(traceback.format_exc())
-
+            error_msg = (
+                "I apologize, but I encountered an error processing your request."
+            )
+            logger.error(
+                f"Error in generate_response for agent '{agent_name}': {e}\n{traceback.format_exc()}"
+            )
             if output_format == "audio":
                 async for chunk in self.llm_provider.tts(
                     error_msg,
@@ -484,35 +701,24 @@ class AgentService(AgentServiceInterface):
                 yield error_msg
 
     async def _bytes_to_generator(self, data: bytes) -> AsyncGenerator[bytes, None]:
-        """Convert bytes to an async generator for streaming.
-
-        Args:
-            data: Bytes of audio data
-
-        Yields:
-            Chunks of audio data
-        """
-        # Define a reasonable chunk size (adjust based on your needs)
+        """Convert bytes to an async generator for streaming."""
         chunk_size = 4096
-
         for i in range(0, len(data), chunk_size):
             yield data[i : i + chunk_size]
-            # Small delay to simulate streaming
             await asyncio.sleep(0.01)
 
     async def _handle_tool_call(self, agent_name: str, tool_text: str) -> str:
         """Handle marker-based tool calls."""
         try:
-            # Extract the content between markers
             start_marker = "[TOOL]"
             end_marker = "[/TOOL]"
-
             start_idx = tool_text.find(start_marker) + len(start_marker)
             end_idx = tool_text.find(end_marker)
+            if start_idx == -1 or end_idx == -1 or end_idx <= start_idx:
+                logger.error(f"Malformed tool call text received: {tool_text}")
+                return "Error: Malformed tool call format."
 
             tool_content = tool_text[start_idx:end_idx].strip()
-
-            # Parse the lines to extract name and parameters
             tool_name = None
             parameters = {}
 
@@ -520,136 +726,168 @@ class AgentService(AgentServiceInterface):
                 line = line.strip()
                 if not line:
                     continue
-
                 if line.startswith("name:"):
                     tool_name = line[5:].strip()
                 elif line.startswith("parameters:"):
                     params_text = line[11:].strip()
-                    # Parse comma-separated parameters
-                    param_pairs = params_text.split(",")
-                    for pair in param_pairs:
-                        if "=" in pair:
-                            k, v = pair.split("=", 1)
-                            parameters[k.strip()] = v.strip()
-
-            # Execute the tool
+                    try:
+                        # Attempt to parse as JSON first for robustness
+                        parameters = json.loads(params_text)
+                    except json.JSONDecodeError:
+                        # Fallback to comma-separated key=value pairs
+                        param_pairs = params_text.split(",")
+                        for pair in param_pairs:
+                            if "=" in pair:
+                                k, v = pair.split("=", 1)
+                                parameters[k.strip()] = v.strip()
+                        logger.warning(
+                            f"Parsed tool parameters using fallback method: {params_text}"
+                        )
+
+            if not tool_name:
+                logger.error(f"Tool name missing in tool call: {tool_content}")
+                return "Error: Tool name missing in call."
+
             result = await self.execute_tool(agent_name, tool_name, parameters)
 
-            # Return the result as string
             if result.get("status") == "success":
                 tool_result = str(result.get("result", ""))
                 return tool_result
             else:
                 error_msg = f"Error calling {tool_name}: {result.get('message', 'Unknown error')}"
+                logger.error(error_msg)
                 return error_msg
 
         except Exception as e:
             import traceback
 
-            print(traceback.format_exc())
+            logger.error(f"Error processing tool call: {e}\n{traceback.format_exc()}")
             return f"Error processing tool call: {str(e)}"
 
     def _get_tool_usage_prompt(self, agent_name: str) -> str:
         """Generate marker-based instructions for tool usage."""
-        # Get tools assigned to this agent
         tools = self.get_agent_tools(agent_name)
         if not tools:
             return ""
 
-        tools_json = json.dumps(tools, indent=2)
+        # Simplify tool representation for the prompt
+        simplified_tools = []
+        for tool in tools:
+            simplified_tool = {
+                "name": tool.get("name"),
+                "description": tool.get("description"),
+                "parameters": tool.get("parameters", {}).get("properties", {}),
+            }
+            simplified_tools.append(simplified_tool)
+
+        tools_json = json.dumps(simplified_tools, indent=2)
+
+        logger.info(
+            f"Generated tool usage prompt for agent '{agent_name}': {tools_json}"
+        )
 
         return f"""
         AVAILABLE TOOLS:
         {tools_json}
 
-        ⚠️ CRITICAL INSTRUCTION: When using a tool, NEVER include explanatory text.
-        Only output the exact tool call format shown below with NO other text.
-        Always call the necessary tool to give the latest information.
+        ⚠️ CRITICAL INSTRUCTIONS FOR TOOL USAGE:
+        1. EXECUTION ORDER MATTERS: If multiple steps are needed (e.g., get information THEN use it), you MUST output the [TOOL] blocks in the exact sequence they need to run. Output the information-gathering tool call FIRST, then the tool call that uses the information.
+        2. ONLY TOOL CALLS: When using a tool, NEVER include explanatory text before or after the tool call block. Only output the exact tool call format shown below.
+        3. USE TOOLS WHEN NEEDED: Always call the necessary tool to give the latest information, especially for time-sensitive queries.
 
         TOOL USAGE FORMAT:
         [TOOL]
         name: tool_name
-        parameters: key1=value1, key2=value2
+        parameters: {{"key1": "value1", "key2": "value2"}}
         [/TOOL]
 
         EXAMPLES:
-        ✅ CORRECT - ONLY the tool call with NOTHING else:
+
+        ✅ CORRECT - Get news THEN email (Correct Order):
         [TOOL]
         name: search_internet
-        parameters: query=latest news on Solana
+        parameters: {{"query": "latest news on Canada"}}
+        [/TOOL]
+        [TOOL]
+        name: mcp
+        parameters: {{"query": "Send an email to
+                             bob@bob.com with subject
+                             'Friendly Reminder to Clean Your Room'
+                             and body 'Hi Bob, just a friendly
+                             reminder to please clean your room
+                             when you get a chance.'"}}
+        [/TOOL]
+        (Note: The system will handle replacing placeholders like '{{output_of_search_internet}}' if possible, but the ORDER is crucial.)
+
+
+        ❌ INCORRECT - Wrong Order:
+        [TOOL]
+        name: mcp
+        parameters: {{"query": "Send an email to
+                             bob@bob.com with subject
+                             'Friendly Reminder to Clean Your Room'
+                             and body 'Hi Bob, just a friendly
+                             reminder to please clean your room
+                             when you get a chance.'"}}
         [/TOOL]
-        
-        ❌ INCORRECT - Never add explanatory text like this:
-        To get the latest news on Solana, I will search the internet.
         [TOOL]
         name: search_internet
-        parameters: query=latest news on Solana
+        parameters: {{"query": "latest news on Canada"}}
         [/TOOL]
 
-        REMEMBER:
-        1. Output ONLY the exact tool call format with NO additional text
-        2. If the query is time-sensitive (latest news, current status, etc.), ALWAYS use the tool.
-        3. After seeing your tool call, I will execute it automatically
-        4. You will receive the tool results and can then respond to the user
-        """
 
-    def _clean_for_audio(self, text: str) -> str:
-        """Remove Markdown formatting, emojis, and non-pronounceable characters from text.
+        ❌ INCORRECT - Explanatory Text:
+        To get the news, I'll search.
+        [TOOL]
+        name: search_internet
+        parameters: {{"query": "latest news on Solana"}}
+        [/TOOL]
+        Now I will email it.
+        [TOOL]
+        name: mcp
+        parameters: {{"query": "Send an email to
+                             bob@bob.com with subject
+                             'Friendly Reminder to Clean Your Room'
+                             and body 'Hi Bob, just a friendly
+                             reminder to please clean your room
+                             when you get a chance.'"}}
+        [/TOOL]
 
-        Args:
-            text: Input text with potential Markdown formatting and special characters
 
-        Returns:
-            Clean text without Markdown, emojis, and special characters
+        REMEMBER:
+        - Output ONLY the [TOOL] blocks in the correct execution order.
+        - I will execute the tools sequentially as you provide them.
+        - You will receive the results of ALL tool calls before formulating the final response.
         """
+
+    def _clean_for_audio(self, text: str) -> str:
+        """Remove Markdown formatting, emojis, and non-pronounceable characters from text."""
         import re
 
         if not text:
             return ""
-
-        # Remove Markdown links - [text](url) -> text
         text = re.sub(r"\[([^\]]+)\]\([^\)]+\)", r"\1", text)
-
-        # Remove inline code with backticks
         text = re.sub(r"`([^`]+)`", r"\1", text)
-
-        # Remove bold formatting - **text** or __text__ -> text
         text = re.sub(r"(\*\*|__)(.*?)\1", r"\2", text)
-
-        # Remove italic formatting - *text* or _text_ -> text
         text = re.sub(r"(\*|_)(.*?)\1", r"\2", text)
-
-        # Remove headers - ## Header -> Header
         text = re.sub(r"^\s*#+\s*(.*?)$", r"\1", text, flags=re.MULTILINE)
-
-        # Remove blockquotes - > Text -> Text
         text = re.sub(r"^\s*>\s*(.*?)$", r"\1", text, flags=re.MULTILINE)
-
-        # Remove horizontal rules (---, ***, ___)
         text = re.sub(r"^\s*[-*_]{3,}\s*$", "", text, flags=re.MULTILINE)
-
-        # Remove list markers - * Item or - Item or 1. Item -> Item
         text = re.sub(r"^\s*[-*+]\s+(.*?)$", r"\1", text, flags=re.MULTILINE)
         text = re.sub(r"^\s*\d+\.\s+(.*?)$", r"\1", text, flags=re.MULTILINE)
-
-        # Remove multiple consecutive newlines (keep just one)
         text = re.sub(r"\n{3,}", "\n\n", text)
-
-        # Remove emojis and other non-pronounceable characters
-        # Common emoji Unicode ranges
         emoji_pattern = re.compile(
             "["
             "\U0001f600-\U0001f64f"  # emoticons
             "\U0001f300-\U0001f5ff"  # symbols & pictographs
             "\U0001f680-\U0001f6ff"  # transport & map symbols
             "\U0001f700-\U0001f77f"  # alchemical symbols
-            "\U0001f780-\U0001f7ff"  # Geometric Shapes
+            "\U0001f780-\U0001f7ff"  # Geometric Shapes Extended
             "\U0001f800-\U0001f8ff"  # Supplemental Arrows-C
             "\U0001f900-\U0001f9ff"  # Supplemental Symbols and Pictographs
-            "\U0001fa00-\U0001fa6f"  # Chess Symbols
             "\U0001fa70-\U0001faff"  # Symbols and Pictographs Extended-A
             "\U00002702-\U000027b0"  # Dingbats
-            "\U000024c2-\U0000257f"  # Enclosed characters
+            "\U000024c2-\U0001f251"
             "\U00002600-\U000026ff"  # Miscellaneous Symbols
             "\U00002700-\U000027bf"  # Dingbats
             "\U0000fe00-\U0000fe0f"  # Variation Selectors
@@ -658,26 +896,57 @@ class AgentService(AgentServiceInterface):
             flags=re.UNICODE,
         )
         text = emoji_pattern.sub(r" ", text)
-
-        # Replace special characters that can cause issues with TTS
-        text = re.sub(r"[^\w\s\.\,\;\:\?\!\'\"\-\(\)]", " ", text)
-
-        # Replace multiple spaces with a single space
+        text = re.sub(
+            r"[^\w\s\.\,\;\:\?\!\'\"\-\(\)]", " ", text
+        )  # Keep basic punctuation
         text = re.sub(r"\s+", " ", text)
-
         return text.strip()
 
     def _clean_tool_response(self, text: str) -> str:
         """Remove any tool markers or formatting that might have leaked into the response."""
         if not text:
             return ""
+        text = text.replace("[TOOL]", "").replace("[/TOOL]", "")
+        if text.lstrip().startswith("TOOL"):
+            text = text.lstrip()[4:].lstrip()  # Remove "TOOL" and leading space
+        return text.strip()
 
-        # Remove any tool markers that might be in the response
-        text = text.replace("[TOOL]", "")
-        text = text.replace("[/TOOL]", "")
+    # --- Add methods from factory logic ---
+    def load_and_register_plugins(self):
+        """Loads plugins using the PluginManager."""
+        try:
+            self.plugin_manager.load_plugins()
+            logger.info("Plugins loaded successfully via PluginManager.")
+        except Exception as e:
+            logger.error(f"Error loading plugins: {e}", exc_info=True)
 
-        # Remove the word TOOL from start if it appears
-        if text.lstrip().startswith("TOOL"):
-            text = text.lstrip().replace("TOOL", "", 1)
+    def register_agents_from_config(self):
+        """Registers agents defined in the main configuration."""
+        agents_config = self.config.get("agents", [])
+        if not agents_config:
+            logger.warning("No agents defined in the configuration.")
+            return
 
-        return text.strip()
+        for agent_config in agents_config:
+            name = agent_config.get("name")
+            instructions = agent_config.get("instructions")
+            specialization = agent_config.get("specialization")
+            tools = agent_config.get("tools", [])
+
+            if not name or not instructions or not specialization:
+                logger.warning(
+                    f"Skipping agent due to missing name, instructions, or specialization: {agent_config}"
+                )
+                continue
+
+            self.register_ai_agent(name, instructions, specialization)
+            # logger.info(f"Registered agent: {name}") # Logging done in register_ai_agent
+
+            # Assign tools to the agent
+            for tool_name in tools:
+                if self.assign_tool_for_agent(name, tool_name):
+                    logger.info(f"Assigned tool '{tool_name}' to agent '{name}'.")
+                else:
+                    logger.warning(
+                        f"Failed to assign tool '{tool_name}' to agent '{name}' (Tool might not be registered)."
+                    )