aiecs 1.7.6__py3-none-any.whl → 1.8.4__py3-none-any.whl

aiecs/domain/agent/hybrid_agent.py

@@ -43,6 +43,67 @@ class HybridAgent(BaseAIAgent):
     - BaseLLMClient: Standard LLM clients (OpenAI, xAI, etc.)
     - Custom clients: Any object implementing LLMClientProtocol (duck typing)
 
+    **ReAct Format Reference (for callers to include in their prompts):**
+    
+    The caller is responsible for ensuring the LLM follows the correct format.
+    Below are the standard formats that HybridAgent expects:
+
+    CORRECT FORMAT EXAMPLE::
+
+        <THOUGHT>
+        I need to search for information about the weather. Let me use the search tool.
+        </THOUGHT>
+
+        TOOL: search
+        OPERATION: query
+        PARAMETERS: {"q": "weather today"}
+
+        <OBSERVATION>
+        The search tool returned: Today's weather is sunny, 72°F.
+        </OBSERVATION>
+
+        <THOUGHT>
+        I have the weather information. Now I can provide the final response.
+        </THOUGHT>
+
+        FINAL RESPONSE: Today's weather is sunny, 72°F. finish
+
+    INCORRECT FORMAT (DO NOT DO THIS)::
+
+        <THOUGHT>
+        I need to search.
+        TOOL: search
+        OPERATION: query
+        </THOUGHT>
+        ❌ Tool calls must be OUTSIDE the <THOUGHT> and <OBSERVATION> tags
+
+        <THOUGHT>
+        I know the answer.
+        FINAL RESPONSE: The answer is... finish
+        </THOUGHT>
+        ❌ Final responses must be OUTSIDE the <THOUGHT> and <OBSERVATION> tags
+        ❌ FINAL RESPONSE must end with 'finish' suffix to indicate completion
+
+    TOOL CALL FORMAT::
+
+        TOOL: <tool_name>
+        OPERATION: <operation_name>
+        PARAMETERS: <json_parameters>
+
+    FINAL RESPONSE FORMAT::
+
+        FINAL RESPONSE: <your_response> finish
+
+    **Important Notes for Callers:**
+
+    - FINAL RESPONSE MUST end with 'finish' to indicate completion
+    - If no 'finish' suffix, the system assumes response is incomplete and will continue iteration
+    - LLM can output JSON or any text format - it will be passed through unchanged
+    - Each iteration will inform LLM of current iteration number and remaining iterations
+    - If LLM generation is incomplete, it will be asked to continue from where it left off
+    - Callers can customize max_iterations to control loop behavior
+    - Callers are responsible for parsing and handling LLM output format
+
     Examples:
         # Example 1: Basic usage with tool names (backward compatible)
         agent = HybridAgent(
@@ -181,7 +242,7 @@ class HybridAgent(BaseAIAgent):
         config: AgentConfiguration,
         description: Optional[str] = None,
         version: str = "1.0.0",
-        max_iterations: int = 10,
+        max_iterations: Optional[int] = None,
         config_manager: Optional["ConfigManagerProtocol"] = None,
         checkpointer: Optional["CheckpointerProtocol"] = None,
         context_engine: Optional[Any] = None,
@@ -201,7 +262,7 @@ class HybridAgent(BaseAIAgent):
             config: Agent configuration
             description: Optional description
             version: Agent version
-            max_iterations: Maximum ReAct iterations
+            max_iterations: Maximum ReAct iterations (if None, uses config.max_iterations)
             config_manager: Optional configuration manager for dynamic config
             checkpointer: Optional checkpointer for state persistence
             context_engine: Optional context engine for persistent storage
@@ -255,7 +316,17 @@ class HybridAgent(BaseAIAgent):
 
         # Store LLM client reference (from BaseAIAgent or local)
         self.llm_client = self._llm_client if self._llm_client else llm_client
-        self._max_iterations = max_iterations
+        
+        # Use config.max_iterations if constructor parameter is None
+        # This makes max_iterations consistent with max_tokens (both configurable via config)
+        # If max_iterations is explicitly provided, it takes precedence over config
+        if max_iterations is None:
+            # Use config value (defaults to 10 if not set in config)
+            self._max_iterations = config.max_iterations
+        else:
+            # Constructor parameter explicitly provided, use it
+            self._max_iterations = max_iterations
+        
         self._system_prompt: Optional[str] = None
         self._conversation_history: List[LLMMessage] = []
         self._tool_schemas: List[Dict[str, Any]] = []
@@ -339,17 +410,29 @@ class HybridAgent(BaseAIAgent):
 
         # Add ReAct instructions (always required for HybridAgent)
         parts.append(
-            "You are a reasoning agent that can use tools to complete tasks. "
-            "Follow the ReAct pattern:\n"
+            "Within the given identity framework, you are also a highly intelligent, responsive, and accurate reasoning agent. that can use tools to complete tasks. "
+            "Follow the ReAct (Reasoning + Acting) pattern to achieve best results:\n"
             "1. THOUGHT: Analyze the task and decide what to do\n"
             "2. ACTION: Use a tool if needed, or provide final answer\n"
             "3. OBSERVATION: Review the tool result and continue reasoning\n\n"
-            "When you need to use a tool, respond with:\n"
-            "TOOL: <tool_name>\n"
-            "OPERATION: <operation_name>\n"
-            "PARAMETERS: <json_parameters>\n\n"
-            "When you have the final answer, respond with:\n"
-            "FINAL ANSWER: <your_answer>"
+            "RESPONSE FORMAT REQUIREMENTS:\n"
+            "- Wrap your thinking process in <THOUGHT>...</THOUGHT> tags\n"
+            "- Wrap your insight about tool result in <OBSERVATION>...</OBSERVATION> tags\n"
+            "- Tool calls (TOOL:, OPERATION:, PARAMETERS:) MUST be OUTSIDE <THOUGHT> and <OBSERVATION> tags\n"
+            "- Final responses (FINAL RESPONSE:) MUST be OUTSIDE <THOUGHT> and <OBSERVATION> tags\n\n"
+            "THINKING GUIDANCE:\n"
+            "When writing <THOUGHT> sections, consider:\n"
+            "- What is the core thing to do?\n"
+            "- What information do I already have?\n"
+            "- What information do I need to gather?\n"
+            "- Which tools would be most helpful?\n"
+            "- What action should I take?\n\n"
+            "OBSERVATION GUIDANCE:\n"
+            "When writing <OBSERVATION> sections, consider:\n"
+            "- What did I learn from the tool results?\n"
+            "- How does this information inform my next work?\n"
+            "- Do I need additional information?\n"
+            "- Am I ready to provide a final response?"
         )
 
         # Add available tools (always required for HybridAgent)
@@ -383,6 +466,24 @@ class HybridAgent(BaseAIAgent):
                     agent_id=self.agent_id,
                 )
 
+            # Extract images from task dict and merge into context
+            task_images = task.get("images")
+            if task_images:
+                # Merge images from task into context
+                # If context already has images, combine them
+                if "images" in context:
+                    existing_images = context["images"]
+                    if isinstance(existing_images, list) and isinstance(task_images, list):
+                        context["images"] = existing_images + task_images
+                    elif isinstance(existing_images, list):
+                        context["images"] = existing_images + [task_images]
+                    elif isinstance(task_images, list):
+                        context["images"] = [existing_images] + task_images
+                    else:
+                        context["images"] = [existing_images, task_images]
+                else:
+                    context["images"] = task_images
+
             # Transition to busy state
             self._transition_state(self.state.__class__.BUSY)
             self._current_task_id = task.get("task_id")
@@ -408,7 +509,7 @@ class HybridAgent(BaseAIAgent):
 
             return {
                 "success": True,
-                "output": result.get("final_answer"),
+                "output": result.get("final_response"),  # Changed from final_answer
                 "reasoning_steps": result.get("steps"),
                 "tool_calls_count": result.get("tool_calls_count"),
                 "iterations": result.get("iterations"),
@@ -499,6 +600,24 @@ class HybridAgent(BaseAIAgent):
                 }
                 return
 
+            # Extract images from task dict and merge into context
+            task_images = task.get("images")
+            if task_images:
+                # Merge images from task into context
+                # If context already has images, combine them
+                if "images" in context:
+                    existing_images = context["images"]
+                    if isinstance(existing_images, list) and isinstance(task_images, list):
+                        context["images"] = existing_images + task_images
+                    elif isinstance(existing_images, list):
+                        context["images"] = existing_images + [task_images]
+                    elif isinstance(task_images, list):
+                        context["images"] = [existing_images] + task_images
+                    else:
+                        context["images"] = [existing_images, task_images]
+                else:
+                    context["images"] = task_images
+
             # Transition to busy state
             self._transition_state(self.state.__class__.BUSY)
             self._current_task_id = task.get("task_id")
@@ -605,11 +724,23 @@ class HybridAgent(BaseAIAgent):
         for iteration in range(self._max_iterations):
             logger.debug(f"HybridAgent {self.agent_id} - ReAct iteration {iteration + 1}")
 
+            # Add iteration info to messages (except first iteration which has task context)
+            if iteration > 0:
+                iteration_info = (
+                    f"[Iteration {iteration + 1}/{self._max_iterations}, "
+                    f"remaining: {self._max_iterations - iteration - 1}]"
+                )
+                # Only add if the last message is not already an iteration info
+                if messages and not messages[-1].content.startswith("[Iteration"):
+                    messages.append(LLMMessage(role="user", content=iteration_info))
+
             # Yield iteration status
             yield {
                 "type": "status",
                 "status": "thinking",
                 "iteration": iteration + 1,
+                "max_iterations": self._max_iterations,
+                "remaining": self._max_iterations - iteration - 1,
                 "timestamp": datetime.utcnow().isoformat(),
             }
 
@@ -627,6 +758,7 @@ class HybridAgent(BaseAIAgent):
                     model=self._config.llm_model,
                     temperature=self._config.temperature,
                     max_tokens=self._config.max_tokens,
+                    context=context,
                     tools=tools,
                     tool_choice="auto",
                     return_chunks=True,  # Enable tool_calls accumulation
@@ -638,6 +770,7 @@ class HybridAgent(BaseAIAgent):
                     model=self._config.llm_model,
                     temperature=self._config.temperature,
                     max_tokens=self._config.max_tokens,
+                    context=context,
                 )
 
             # Stream tokens and collect tool calls
@@ -677,7 +810,16 @@ class HybridAgent(BaseAIAgent):
                         "timestamp": datetime.utcnow().isoformat(),
                     }
 
-            thought = "".join(thought_tokens)
+            thought_raw = "".join(thought_tokens)
+            
+            # Store raw output in steps (no format processing)
+            steps.append(
+                {
+                    "type": "thought",
+                    "content": thought_raw.strip(),  # Return raw output without processing
+                    "iteration": iteration + 1,
+                }
+            )
             
             # Process tool_calls if received from stream
             if tool_calls_from_stream:
@@ -688,19 +830,30 @@ class HybridAgent(BaseAIAgent):
                         func_args = tool_call["function"]["arguments"]
 
                         # Parse function name to extract tool and operation
-                        parts = func_name.split("_", 1)
-                        if len(parts) == 2:
-                            tool_name, operation = parts
-                        else:
-                            tool_name = parts[0]
+                        # CRITICAL: Try exact match first, then fall back to underscore parsing
+                        if self._tool_instances and func_name in self._tool_instances:
+                            # Exact match found - use full function name as tool name
+                            tool_name = func_name
                             operation = None
+                        elif self._available_tools and func_name in self._available_tools:
+                            # Exact match in available tools list
+                            tool_name = func_name
+                            operation = None
+                        else:
+                            # Fallback: try underscore parsing for legacy compatibility
+                            parts = func_name.split("_", 1)
+                            if len(parts) == 2:
+                                tool_name, operation = parts
+                            else:
+                                tool_name = parts[0]
+                                operation = None
 
                         # Parse arguments JSON
                         import json
                         if isinstance(func_args, str):
                             parameters = json.loads(func_args)
                         else:
-                            parameters = func_args
+                            parameters = func_args if func_args else {}
 
                         # Yield tool call event
                         yield {
@@ -715,17 +868,19 @@ class HybridAgent(BaseAIAgent):
                         tool_result = await self._execute_tool(tool_name, operation, parameters)
                         tool_calls_count += 1
 
+                        # Wrap tool call and result in step
                         steps.append(
                             {
                                 "type": "action",
                                 "tool": tool_name,
                                 "operation": operation,
                                 "parameters": parameters,
+                                "result": str(tool_result),  # Include result in step
                                 "iteration": iteration + 1,
                             }
                         )
 
-                        # Yield tool result event
+                        # Yield tool result event (streaming)
                         yield {
                             "type": "tool_result",
                             "tool_name": tool_name,
@@ -733,15 +888,9 @@ class HybridAgent(BaseAIAgent):
                             "timestamp": datetime.utcnow().isoformat(),
                         }
 
-                        # Add tool result to messages
-                        observation = f"Tool '{tool_name}' returned: {tool_result}"
-                        steps.append(
-                            {
-                                "type": "observation",
-                                "content": observation,
-                                "iteration": iteration + 1,
-                            }
-                        )
+                        # Add tool result to messages (for LLM consumption)
+                        observation_content = f"Tool '{tool_name}' returned: {tool_result}"
+                        observation = f"<OBSERVATION>\n{observation_content}\n</OBSERVATION>"
 
                         # Add assistant message with tool call and tool result
                         messages.append(
@@ -760,13 +909,14 @@ class HybridAgent(BaseAIAgent):
                         )
 
                     except Exception as e:
-                        error_msg = f"Tool execution failed: {str(e)}"
+                        error_content = f"Tool execution failed: {str(e)}"
+                        error_msg = f"<OBSERVATION>\n{error_content}\n</OBSERVATION>"
                         steps.append(
                             {
                                 "type": "observation",
                                 "content": error_msg,
                                 "iteration": iteration + 1,
-                                "error": True,
+                                "has_error": True,
                             }
                         )
                         yield {
@@ -786,21 +936,13 @@ class HybridAgent(BaseAIAgent):
                 # Continue to next iteration
                 continue
 
-            steps.append(
-                {
-                    "type": "thought",
-                    "content": thought,
-                    "iteration": iteration + 1,
-                }
-            )
-
-            # Check if final answer
-            if "FINAL ANSWER:" in thought:
-                final_answer = self._extract_final_answer(thought)
+            # Check for final response (outside tags only)
+            if self._has_final_response(thought_raw):
+                final_response = self._extract_final_response(thought_raw)
                 yield {
                     "type": "result",
                     "success": True,
-                    "output": final_answer,
+                    "output": final_response,  # Return raw output without processing
                     "reasoning_steps": steps,
                     "tool_calls_count": tool_calls_count,
                     "iterations": iteration + 1,
@@ -809,11 +951,11 @@ class HybridAgent(BaseAIAgent):
                 }
                 return
 
-            # Check if tool call
-            if "TOOL:" in thought:
+            # Check if tool call (ReAct mode, outside tags only)
+            if self._has_tool_call(thought_raw):
                 # ACT: Execute tool
                 try:
-                    tool_info = self._parse_tool_call(thought)
+                    tool_info = self._parse_tool_call(thought_raw)  # Parse from raw text
                     tool_name = tool_info.get("tool", "")
                     if not tool_name:
                         raise ValueError("Tool name not found in tool call")
@@ -834,27 +976,19 @@ class HybridAgent(BaseAIAgent):
                     )
                     tool_calls_count += 1
 
+                    # Wrap tool call and result in step
                     steps.append(
                         {
                             "type": "action",
                             "tool": tool_info["tool"],
                             "operation": tool_info.get("operation"),
                             "parameters": tool_info.get("parameters"),
+                            "result": str(tool_result),  # Include result in step
                             "iteration": iteration + 1,
                         }
                     )
 
-                    # OBSERVE: Add tool result to conversation
-                    observation = f"OBSERVATION: Tool '{tool_info['tool']}' returned: {tool_result}"
-                    steps.append(
-                        {
-                            "type": "observation",
-                            "content": observation,
-                            "iteration": iteration + 1,
-                        }
-                    )
-
-                    # Yield tool result event
+                    # Yield tool result event (streaming)
                     yield {
                         "type": "tool_result",
                         "tool_name": tool_name,
@@ -862,16 +996,22 @@ class HybridAgent(BaseAIAgent):
                         "timestamp": datetime.utcnow().isoformat(),
                     }
 
+                    # OBSERVE: Add tool result to conversation (for LLM consumption)
+                    observation_content = f"Tool '{tool_info['tool']}' returned: {tool_result}"
+                    observation = f"<OBSERVATION>\n{observation_content}\n</OBSERVATION>"
+
                     # Add to messages for next iteration
-                    messages.append(LLMMessage(role="assistant", content=thought))
+                    messages.append(LLMMessage(role="assistant", content=thought_raw))
                     messages.append(LLMMessage(role="user", content=observation))
 
                 except Exception as e:
-                    error_msg = f"OBSERVATION: Tool execution failed: {str(e)}"
+                    error_content = f"Tool execution failed: {str(e)}"
+                    error_msg = f"<OBSERVATION>\n{error_content}\n</OBSERVATION>"
                     steps.append(
                         {
-                            "type": "observation",
-                            "content": error_msg,
+                            "type": "action",
+                            "tool": tool_name if "tool_name" in locals() else "unknown",
+                            "error": str(e),
                             "iteration": iteration + 1,
                             "error": True,
                         }
@@ -885,22 +1025,37 @@ class HybridAgent(BaseAIAgent):
                         "timestamp": datetime.utcnow().isoformat(),
                     }
 
-                    messages.append(LLMMessage(role="assistant", content=thought))
+                    messages.append(LLMMessage(role="assistant", content=thought_raw))
                     messages.append(LLMMessage(role="user", content=error_msg))
 
             else:
-                # LLM didn't provide clear action - treat as final answer
-                yield {
-                    "type": "result",
-                    "success": True,
-                    "output": thought,
-                    "reasoning_steps": steps,
-                    "tool_calls_count": tool_calls_count,
-                    "iterations": iteration + 1,
-                    "total_tokens": total_tokens,
-                    "timestamp": datetime.utcnow().isoformat(),
-                }
-                return
+                # Check if there's an incomplete final response (has FINAL RESPONSE but no finish)
+                if self._has_incomplete_final_response(thought_raw):
+                    # Incomplete final response - ask LLM to continue
+                    continue_message = (
+                        f"[Iteration {iteration + 1}/{self._max_iterations}, "
+                        f"remaining: {self._max_iterations - iteration - 1}]\n"
+                        "Your FINAL RESPONSE appears incomplete (missing 'finish' suffix). "
+                        "Please continue your response from where you left off and end with 'finish' "
+                        "to indicate completion. If no 'finish' suffix, the system will continue iteration."
+                    )
+                    messages.append(LLMMessage(role="assistant", content=thought_raw))
+                    messages.append(LLMMessage(role="user", content=continue_message))
+                else:
+                    # No tool call or final response detected - ask LLM to continue
+                    continue_message = (
+                        f"[Iteration {iteration + 1}/{self._max_iterations}, "
+                        f"remaining: {self._max_iterations - iteration - 1}]\n"
+                        "Continuing from your previous output. "
+                        "If your generation is incomplete, please continue from where you left off. "
+                        "If you decide to take action, ensure proper format:\n"
+                        "- Tool call: TOOL:, OPERATION:, PARAMETERS: (outside tags)\n"
+                        "- Final response: FINAL RESPONSE: <content> finish (outside tags)"
+                    )
+                    messages.append(LLMMessage(role="assistant", content=thought_raw))
+                    messages.append(LLMMessage(role="user", content=continue_message))
+                # Continue to next iteration
+                continue
 
         # Max iterations reached
         logger.warning(f"HybridAgent {self.agent_id} reached max iterations")
@@ -937,6 +1092,16 @@ class HybridAgent(BaseAIAgent):
         for iteration in range(self._max_iterations):
             logger.debug(f"HybridAgent {self.agent_id} - ReAct iteration {iteration + 1}")
 
+            # Add iteration info to messages (except first iteration which has task context)
+            if iteration > 0:
+                iteration_info = (
+                    f"[Iteration {iteration + 1}/{self._max_iterations}, "
+                    f"remaining: {self._max_iterations - iteration - 1}]"
+                )
+                # Only add if the last message is not already an iteration info
+                if messages and not messages[-1].content.startswith("[Iteration"):
+                    messages.append(LLMMessage(role="user", content=iteration_info))
+
             # THINK: LLM reasons about next action
             # Use Function Calling if supported, otherwise use ReAct mode
             if self._use_function_calling and self._tool_schemas:
@@ -947,6 +1112,7 @@ class HybridAgent(BaseAIAgent):
                     model=self._config.llm_model,
                     temperature=self._config.temperature,
                     max_tokens=self._config.max_tokens,
+                    context=context,
                     tools=tools,
                     tool_choice="auto",
                 )
@@ -957,11 +1123,32 @@ class HybridAgent(BaseAIAgent):
                     model=self._config.llm_model,
                     temperature=self._config.temperature,
                     max_tokens=self._config.max_tokens,
+                    context=context,
                 )
 
-            thought = response.content or ""
+            thought_raw = response.content or ""
             total_tokens += getattr(response, "total_tokens", 0)
 
+            # Update prompt cache metrics from LLM response
+            cache_read_tokens = getattr(response, "cache_read_tokens", None)
+            cache_creation_tokens = getattr(response, "cache_creation_tokens", None)
+            cache_hit = getattr(response, "cache_hit", None)
+            if cache_read_tokens is not None or cache_creation_tokens is not None or cache_hit is not None:
+                self.update_cache_metrics(
+                    cache_read_tokens=cache_read_tokens,
+                    cache_creation_tokens=cache_creation_tokens,
+                    cache_hit=cache_hit,
+                )
+
+            # Store raw output in steps (no format processing)
+            steps.append(
+                {
+                    "type": "thought",
+                    "content": thought_raw.strip(),  # Return raw output without processing
+                    "iteration": iteration + 1,
+                }
+            )
+
             # Check for Function Calling response
             tool_calls = getattr(response, "tool_calls", None)
             function_call = getattr(response, "function_call", None)
@@ -989,52 +1176,50 @@ class HybridAgent(BaseAIAgent):
                         func_args = tool_call["function"]["arguments"]
 
                         # Parse function name to extract tool and operation
-                        # Format: tool_name_operation or tool_name
-                        parts = func_name.split("_", 1)
-                        if len(parts) == 2:
-                            tool_name, operation = parts
-                        else:
-                            tool_name = parts[0]
+                        # CRITICAL: Try exact match first, then fall back to underscore parsing
+                        if self._tool_instances and func_name in self._tool_instances:
+                            # Exact match found - use full function name as tool name
+                            tool_name = func_name
                             operation = None
+                        elif self._available_tools and func_name in self._available_tools:
+                            # Exact match in available tools list
+                            tool_name = func_name
+                            operation = None
+                        else:
+                            # Fallback: try underscore parsing for legacy compatibility
+                            parts = func_name.split("_", 1)
+                            if len(parts) == 2:
+                                tool_name, operation = parts
+                            else:
+                                tool_name = parts[0]
+                                operation = None
 
                         # Parse arguments JSON
                         import json
                         if isinstance(func_args, str):
                             parameters = json.loads(func_args)
                         else:
-                            parameters = func_args
-
-                        steps.append(
-                            {
-                                "type": "thought",
-                                "content": f"Calling tool {func_name}",
-                                "iteration": iteration + 1,
-                            }
-                        )
+                            parameters = func_args if func_args else {}
 
                         # Execute tool
                         tool_result = await self._execute_tool(tool_name, operation, parameters)
                         tool_calls_count += 1
 
+                        # Wrap tool call and result in step
                         steps.append(
                             {
                                 "type": "action",
                                 "tool": tool_name,
                                 "operation": operation,
                                 "parameters": parameters,
+                                "result": str(tool_result),  # Include result in step
                                 "iteration": iteration + 1,
                             }
                         )
 
-                        # Add tool result to messages
-                        observation = f"Tool '{tool_name}' returned: {tool_result}"
-                        steps.append(
-                            {
-                                "type": "observation",
-                                "content": observation,
-                                "iteration": iteration + 1,
-                            }
-                        )
+                        # Add tool result to messages (for LLM consumption)
+                        observation_content = f"Tool '{tool_name}' returned: {tool_result}"
+                        observation = f"<OBSERVATION>\n{observation_content}\n</OBSERVATION>"
 
                         # Add assistant message with tool call and tool result
                         messages.append(
@@ -1053,13 +1238,14 @@ class HybridAgent(BaseAIAgent):
                         )
 
                     except Exception as e:
-                        error_msg = f"Tool execution failed: {str(e)}"
+                        error_content = f"Tool execution failed: {str(e)}"
+                        error_msg = f"<OBSERVATION>\n{error_content}\n</OBSERVATION>"
                         steps.append(
                             {
                                 "type": "observation",
                                 "content": error_msg,
                                 "iteration": iteration + 1,
-                                "error": True,
+                                "has_error": True,
                             }
                         )
                         # Add error to messages
@@ -1074,41 +1260,22 @@ class HybridAgent(BaseAIAgent):
                 # Continue to next iteration
                 continue
 
-            # If using Function Calling and no tool calls, check if we have a final answer
-            if self._use_function_calling and thought:
-                # LLM provided a text response without tool calls - treat as final answer
+            # Check for final response (outside tags only)
+            if self._has_final_response(thought_raw):
+                final_response = self._extract_final_response(thought_raw)
                 return {
-                    "final_answer": thought,
+                    "final_response": final_response,  # Return raw output without processing
                     "steps": steps,
                     "iterations": iteration + 1,
                     "tool_calls_count": tool_calls_count,
                     "total_tokens": total_tokens,
                 }
 
-            steps.append(
-                {
-                    "type": "thought",
-                    "content": thought,
-                    "iteration": iteration + 1,
-                }
-            )
-
-            # Check if final answer (ReAct mode)
-            if "FINAL ANSWER:" in thought:
-                final_answer = self._extract_final_answer(thought)
-                return {
-                    "final_answer": final_answer,
-                    "steps": steps,
-                    "iterations": iteration + 1,
-                    "tool_calls_count": tool_calls_count,
-                    "total_tokens": total_tokens,
-                }
-
-            # Check if tool call (ReAct mode)
-            if "TOOL:" in thought:
+            # Check if tool call (ReAct mode, outside tags only)
+            if self._has_tool_call(thought_raw):
                 # ACT: Execute tool
                 try:
-                    tool_info = self._parse_tool_call(thought)
+                    tool_info = self._parse_tool_call(thought_raw)  # Parse from raw text
                     tool_name = tool_info.get("tool", "")
                     if not tool_name:
                         raise ValueError("Tool name not found in tool call")
@@ -1119,57 +1286,74 @@ class HybridAgent(BaseAIAgent):
                     )
                     tool_calls_count += 1
 
+                    # Wrap tool call and result in step
                     steps.append(
                         {
                             "type": "action",
                             "tool": tool_info["tool"],
                             "operation": tool_info.get("operation"),
                             "parameters": tool_info.get("parameters"),
+                            "result": str(tool_result),  # Include result in step
                             "iteration": iteration + 1,
                         }
                     )
 
-                    # OBSERVE: Add tool result to conversation
-                    observation = f"OBSERVATION: Tool '{tool_info['tool']}' returned: {tool_result}"
-                    steps.append(
-                        {
-                            "type": "observation",
-                            "content": observation,
-                            "iteration": iteration + 1,
-                        }
-                    )
+                    # OBSERVE: Add tool result to conversation (for LLM consumption)
+                    observation_content = f"Tool '{tool_info['tool']}' returned: {tool_result}"
+                    observation = f"<OBSERVATION>\n{observation_content}\n</OBSERVATION>"
 
                     # Add to messages for next iteration
-                    messages.append(LLMMessage(role="assistant", content=thought))
+                    messages.append(LLMMessage(role="assistant", content=thought_raw))
                     messages.append(LLMMessage(role="user", content=observation))
 
                 except Exception as e:
-                    error_msg = f"OBSERVATION: Tool execution failed: {str(e)}"
+                    error_content = f"Tool execution failed: {str(e)}"
+                    error_msg = f"<OBSERVATION>\n{error_content}\n</OBSERVATION>"
                     steps.append(
                         {
-                            "type": "observation",
-                            "content": error_msg,
+                            "type": "action",
+                            "tool": tool_name if "tool_name" in locals() else "unknown",
+                            "error": str(e),
                             "iteration": iteration + 1,
-                            "error": True,
+                            "has_error": True,
                         }
                     )
-                    messages.append(LLMMessage(role="assistant", content=thought))
+                    messages.append(LLMMessage(role="assistant", content=thought_raw))
                     messages.append(LLMMessage(role="user", content=error_msg))
 
             else:
-                # LLM didn't provide clear action - treat as final answer
-                return {
-                    "final_answer": thought,
-                    "steps": steps,
-                    "iterations": iteration + 1,
-                    "tool_calls_count": tool_calls_count,
-                    "total_tokens": total_tokens,
-                }
+                # Check if there's an incomplete final response (has FINAL RESPONSE but no finish)
+                if self._has_incomplete_final_response(thought_raw):
+                    # Incomplete final response - ask LLM to continue
+                    continue_message = (
+                        f"[Iteration {iteration + 1}/{self._max_iterations}, "
+                        f"remaining: {self._max_iterations - iteration - 1}]\n"
+                        "Your FINAL RESPONSE appears incomplete (missing 'finish' suffix). "
+                        "Please continue your response from where you left off and end with 'finish' "
+                        "to indicate completion. If no 'finish' suffix, the system will continue iteration."
+                    )
+                    messages.append(LLMMessage(role="assistant", content=thought_raw))
+                    messages.append(LLMMessage(role="user", content=continue_message))
+                else:
+                    # No tool call or final response detected - ask LLM to continue
+                    continue_message = (
+                        f"[Iteration {iteration + 1}/{self._max_iterations}, "
+                        f"remaining: {self._max_iterations - iteration - 1}]\n"
+                        "Continuing from your previous output. "
+                        "If your generation is incomplete, please continue from where you left off. "
+                        "If you decide to take action, ensure proper format:\n"
+                        "- Tool call: TOOL:, OPERATION:, PARAMETERS: (outside tags)\n"
+                        "- Final response: FINAL RESPONSE: <content> finish (outside tags)"
+                    )
+                    messages.append(LLMMessage(role="assistant", content=thought_raw))
+                    messages.append(LLMMessage(role="user", content=continue_message))
+                # Continue to next iteration
+                continue
 
         # Max iterations reached
         logger.warning(f"HybridAgent {self.agent_id} reached max iterations")
         return {
-            "final_answer": "Max iterations reached. Unable to complete task fully.",
+            "final_response": "Max iterations reached. Unable to complete task fully.",
             "steps": steps,
             "iterations": self._max_iterations,
             "tool_calls_count": tool_calls_count,
@@ -1196,19 +1380,75 @@ class HybridAgent(BaseAIAgent):
                 )
             )
 
+        # Collect images from context to attach to task message
+        task_images = []
+
         # Add context if provided
         if context:
-            context_str = self._format_context(context)
-            if context_str:
-                messages.append(
-                    LLMMessage(
-                        role="system",
-                        content=f"Additional Context:\n{context_str}",
+            # Special handling: if context contains 'history' as a list of messages,
+            # add them as separate user/assistant messages instead of formatting
+            history = context.get("history")
+            if isinstance(history, list) and len(history) > 0:
+                # Check if history contains message-like dictionaries
+                for msg in history:
+                    if isinstance(msg, dict) and "role" in msg and "content" in msg:
+                        # Valid message format - add as separate message
+                        # Extract images if present
+                        msg_images = msg.get("images", [])
+                        if msg_images:
+                            messages.append(
+                                LLMMessage(
+                                    role=msg["role"],
+                                    content=msg["content"],
+                                    images=msg_images if isinstance(msg_images, list) else [msg_images],
+                                )
+                            )
+                        else:
+                            messages.append(
+                                LLMMessage(
+                                    role=msg["role"],
+                                    content=msg["content"],
+                                )
+                            )
+                    elif isinstance(msg, LLMMessage):
+                        # Already an LLMMessage instance (may already have images)
+                        messages.append(msg)
+            
+            # Extract images from context if present
+            context_images = context.get("images")
+            if context_images:
+                if isinstance(context_images, list):
+                    task_images.extend(context_images)
+                else:
+                    task_images.append(context_images)
+            
+            # Format remaining context fields (excluding history and images) as Additional Context
+            context_without_history = {
+                k: v for k, v in context.items() 
+                if k not in ("history", "images")
+            }
+            if context_without_history:
+                context_str = self._format_context(context_without_history)
+                if context_str:
+                    messages.append(
+                        LLMMessage(
+                            role="user",
+                            content=f"Additional Context:\n{context_str}",
+                        )
                     )
-                )
 
-        # Add task
-        messages.append(LLMMessage(role="user", content=f"Task: {task}"))
+        # Add task with iteration info
+        task_message = (
+            f"Task: {task}\n\n"
+            f"[Iteration 1/{self._max_iterations}, remaining: {self._max_iterations - 1}]"
+        )
+        messages.append(
+            LLMMessage(
+                role="user",
+                content=task_message,
+                images=task_images if task_images else [],
+            )
+        )
 
         return messages
 
@@ -1220,15 +1460,147 @@ class HybridAgent(BaseAIAgent):
                 relevant_fields.append(f"{key}: {value}")
         return "\n".join(relevant_fields) if relevant_fields else ""
 
-    def _extract_final_answer(self, thought: str) -> str:
-        """Extract final answer from thought."""
-        if "FINAL ANSWER:" in thought:
-            return thought.split("FINAL ANSWER:", 1)[1].strip()
-        return thought
+    def _extract_thought_content(self, text: str) -> str:
+        """
+        Extract content from <THOUGHT>...</THOUGHT> tags.
+        
+        DEPRECATED: This method is kept for backward compatibility but no longer
+        extracts content. Returns original text as-is per new design.
+        
+        Args:
+            text: Text that may contain THOUGHT tags
+            
+        Returns:
+            Original text (no extraction performed)
+        """
+        # Return original text without processing (new design)
+        return text.strip()
+    
+    def _extract_observation_content(self, text: str) -> str:
+        """
+        Extract content from <OBSERVATION>...</OBSERVATION> tags.
+        
+        DEPRECATED: This method is kept for backward compatibility but no longer
+        extracts content. Returns original text as-is per new design.
+        
+        Args:
+            text: Text that may contain OBSERVATION tags
+            
+        Returns:
+            Original text (no extraction performed)
+        """
+        # Return original text without processing (new design)
+        return text.strip()
+
+    def _has_final_response(self, text: str) -> bool:
+        """
+        Check if text contains complete FINAL RESPONSE with 'finish' suffix.
+        
+        The FINAL RESPONSE must end with 'finish' to be considered complete.
+        If FINAL RESPONSE is present but without 'finish', it's considered incomplete
+        and the loop will continue to let LLM complete the response.
+        
+        Args:
+            text: Text to check
+            
+        Returns:
+            True if complete FINAL RESPONSE (with finish suffix) found outside tags
+        """
+        import re
+        
+        # Remove content inside THOUGHT and OBSERVATION tags
+        text_without_tags = re.sub(r'<THOUGHT>.*?</THOUGHT>', '', text, flags=re.DOTALL)
+        text_without_tags = re.sub(r'<OBSERVATION>.*?</OBSERVATION>', '', text_without_tags, flags=re.DOTALL)
+        
+        # Check for FINAL RESPONSE marker with 'finish' suffix in remaining text
+        # The 'finish' must appear after FINAL RESPONSE: content
+        if "FINAL RESPONSE:" not in text_without_tags:
+            return False
+        
+        # Check if 'finish' appears after FINAL RESPONSE:
+        # Use case-insensitive search for 'finish' at the end
+        text_lower = text_without_tags.lower()
+        final_response_idx = text_lower.find("final response:")
+        if final_response_idx == -1:
+            return False
+        
+        # Check if 'finish' appears after the FINAL RESPONSE marker
+        remaining_text = text_without_tags[final_response_idx:]
+        return "finish" in remaining_text.lower()
+    
+    def _has_incomplete_final_response(self, text: str) -> bool:
+        """
+        Check if text contains FINAL RESPONSE marker but without 'finish' suffix.
+        
+        Args:
+            text: Text to check
+            
+        Returns:
+            True if FINAL RESPONSE marker found but without finish suffix
+        """
+        import re
+        
+        # Remove content inside THOUGHT and OBSERVATION tags
+        text_without_tags = re.sub(r'<THOUGHT>.*?</THOUGHT>', '', text, flags=re.DOTALL)
+        text_without_tags = re.sub(r'<OBSERVATION>.*?</OBSERVATION>', '', text_without_tags, flags=re.DOTALL)
+        
+        # Check for FINAL RESPONSE marker without 'finish' suffix
+        if "FINAL RESPONSE:" not in text_without_tags:
+            return False
+        
+        # Check if 'finish' is missing
+        text_lower = text_without_tags.lower()
+        final_response_idx = text_lower.find("final response:")
+        remaining_text = text_without_tags[final_response_idx:]
+        return "finish" not in remaining_text.lower()
+    
+    def _extract_final_response(self, text: str) -> str:
+        """
+        Extract final response from text, preserving original format.
+        Only extracts from outside THOUGHT/OBSERVATION tags.
+        
+        Args:
+            text: Text that may contain FINAL RESPONSE marker
+            
+        Returns:
+            Original text if FINAL RESPONSE found, otherwise empty string
+        """
+        import re
+        
+        # Remove content inside THOUGHT and OBSERVATION tags
+        text_without_tags = re.sub(r'<THOUGHT>.*?</THOUGHT>', '', text, flags=re.DOTALL)
+        text_without_tags = re.sub(r'<OBSERVATION>.*?</OBSERVATION>', '', text_without_tags, flags=re.DOTALL)
+        
+        # Check for FINAL RESPONSE marker
+        if "FINAL RESPONSE:" in text_without_tags:
+            # Return original text without any processing
+            return text.strip()
+        
+        return ""
 
-    def _parse_tool_call(self, thought: str) -> Dict[str, Any]:
+    def _has_tool_call(self, text: str) -> bool:
+        """
+        Check if text contains TOOL call marker outside of THOUGHT/OBSERVATION tags.
+        
+        Args:
+            text: Text to check
+            
+        Returns:
+            True if TOOL marker found outside tags
+        """
+        import re
+        
+        # Remove content inside THOUGHT and OBSERVATION tags
+        text_without_tags = re.sub(r'<THOUGHT>.*?</THOUGHT>', '', text, flags=re.DOTALL)
+        text_without_tags = re.sub(r'<OBSERVATION>.*?</OBSERVATION>', '', text_without_tags, flags=re.DOTALL)
+        
+        # Check for TOOL marker in remaining text
+        return "TOOL:" in text_without_tags
+    
+    def _parse_tool_call(self, text: str) -> Dict[str, Any]:
         """
-        Parse tool call from LLM thought.
+        Parse tool call from LLM output.
+        Only parses from outside THOUGHT/OBSERVATION tags.
 
         Expected format:
         TOOL: <tool_name>
@@ -1236,28 +1608,33 @@ class HybridAgent(BaseAIAgent):
         PARAMETERS: <json_parameters>
 
         Args:
-            thought: LLM thought containing tool call
+            text: LLM output that may contain tool call
 
         Returns:
             Dictionary with 'tool', 'operation', 'parameters'
         """
         import json
+        import re
 
         result = {}
+        
+        # Remove content inside THOUGHT and OBSERVATION tags
+        text_without_tags = re.sub(r'<THOUGHT>.*?</THOUGHT>', '', text, flags=re.DOTALL)
+        text_without_tags = re.sub(r'<OBSERVATION>.*?</OBSERVATION>', '', text_without_tags, flags=re.DOTALL)
 
-        # Extract tool
-        if "TOOL:" in thought:
-            tool_line = [line for line in thought.split("\n") if line.startswith("TOOL:")][0]
+        # Extract tool from text outside tags
+        if "TOOL:" in text_without_tags:
+            tool_line = [line for line in text_without_tags.split("\n") if line.strip().startswith("TOOL:")][0]
             result["tool"] = tool_line.split("TOOL:", 1)[1].strip()
 
         # Extract operation (optional)
-        if "OPERATION:" in thought:
-            op_line = [line for line in thought.split("\n") if line.startswith("OPERATION:")][0]
+        if "OPERATION:" in text_without_tags:
+            op_line = [line for line in text_without_tags.split("\n") if line.strip().startswith("OPERATION:")][0]
             result["operation"] = op_line.split("OPERATION:", 1)[1].strip()
 
         # Extract parameters (optional)
-        if "PARAMETERS:" in thought:
-            param_line = [line for line in thought.split("\n") if line.startswith("PARAMETERS:")][0]
+        if "PARAMETERS:" in text_without_tags:
+            param_line = [line for line in text_without_tags.split("\n") if line.strip().startswith("PARAMETERS:")][0]
             param_str = param_line.split("PARAMETERS:", 1)[1].strip()
             try:
                 result["parameters"] = json.loads(param_str)