alita-sdk 0.3.462__py3-none-any.whl → 0.3.627__py3-none-any.whl

alita_sdk/runtime/langchain/langraph_agent.py

@@ -12,6 +12,7 @@ from langchain_core.runnables import Runnable
 from langchain_core.runnables import RunnableConfig
 from langchain_core.tools import BaseTool, ToolException
 from langgraph.channels.ephemeral_value import EphemeralValue
+from langgraph.errors import GraphRecursionError
 from langgraph.graph import StateGraph
 from langgraph.graph.graph import END, START
 from langgraph.graph.state import CompiledStateGraph
@@ -22,6 +23,7 @@ from langgraph.store.base import BaseStore
 from .constants import PRINTER_NODE_RS, PRINTER, PRINTER_COMPLETED_STATE
 from .mixedAgentRenderes import convert_message_to_json
 from .utils import create_state, propagate_the_input_mapping, safe_format
+from ..utils.constants import TOOLKIT_NAME_META, TOOL_NAME_META
 from ..tools.function import FunctionTool
 from ..tools.indexer_tool import IndexerNode
 from ..tools.llm import LLMNode
@@ -29,7 +31,7 @@ from ..tools.loop import LoopNode
 from ..tools.loop_output import LoopToolNode
 from ..tools.tool import ToolNode
 from ..utils.evaluate import EvaluateTemplate
-from ..utils.utils import clean_string, TOOLKIT_SPLITTER
+from ..utils.utils import clean_string
 from ..tools.router import RouterNode
 
 logger = logging.getLogger(__name__)
@@ -171,12 +173,13 @@ Answer only with step name, no need to add descrip in case none of the steps are
 """
 
     def __init__(self, client, steps: str, description: str = "", decisional_inputs: Optional[list[str]] = [],
-                 default_output: str = 'END'):
+                 default_output: str = 'END', is_node: bool = False):
         self.client = client
         self.steps = ",".join([clean_string(step) for step in steps])
         self.description = description
         self.decisional_inputs = decisional_inputs
         self.default_output = default_output if default_output != 'END' else END
+        self.is_node = is_node
 
     def invoke(self, state: Annotated[BaseStore, InjectedStore()], config: Optional[RunnableConfig] = None) -> str:
         additional_info = ""
@@ -186,10 +189,10 @@ Answer only with step name, no need to add descrip in case none of the steps are
                 decision_input = state.get('messages', [])[:]
             else:
                 if len(additional_info) == 0:
-                    additional_info = """### Additoinal info: """
+                    additional_info = """### Additional info: """
                 additional_info += "{field}: {value}\n".format(field=field, value=state.get(field, ""))
         decision_input.append(HumanMessage(
-            self.prompt.format(steps=self.steps, description=self.description, additional_info=additional_info)))
+            self.prompt.format(steps=self.steps, description=safe_format(self.description, state), additional_info=additional_info)))
         completion = self.client.invoke(decision_input)
         result = clean_string(completion.content.strip())
         logger.info(f"Plan to transition to: {result}")
@@ -198,7 +201,8 @@ Answer only with step name, no need to add descrip in case none of the steps are
         dispatch_custom_event(
             "on_decision_edge", {"decisional_inputs": self.decisional_inputs, "state": state}, config=config
         )
-        return result
+        # support of legacy `decision` as part of node
+        return {"router_output": result} if self.is_node else result
 
 
 class TransitionalEdge(Runnable):
@@ -226,18 +230,32 @@ class StateDefaultNode(Runnable):
         for key, value in self.default_vars.items():
             if isinstance(value, dict) and 'value' in value:
                 temp_value = value['value']
-                try:
-                    result[key] = ast.literal_eval(temp_value)
-                except:
-                    logger.debug("Unable to evaluate value, using as is")
+                declared_type = value.get('type', '').lower()
+
+                # If the declared type is 'str' or 'string', preserve the string value
+                # Don't auto-convert even if it looks like a valid Python literal
+                if declared_type in ('str', 'string'):
                     result[key] = temp_value
+                else:
+                    # For other types, try to evaluate as Python literal
+                    try:
+                        result[key] = ast.literal_eval(temp_value)
+                    except:
+                        logger.debug("Unable to evaluate value, using as is")
+                        result[key] = temp_value
         return result
 
 class PrinterNode(Runnable):
     name = "PrinterNode"
+    DEFAULT_FINAL_MSG = "How to proceed? To resume the pipeline - type anything..."
 
-    def __init__(self, input_mapping: Optional[dict[str, dict]]):
+    def __init__(self, input_mapping: Optional[dict[str, dict]], final_message: Optional[str] = None):
         self.input_mapping = input_mapping
+        # Apply fallback logic for empty/None values
+        if final_message and final_message.strip():
+            self.final_message = final_message.strip()
+        else:
+            self.final_message = self.DEFAULT_FINAL_MSG
 
     def invoke(self, state: BaseStore, config: Optional[RunnableConfig] = None) -> dict:
         logger.info(f"Printer Node - Current state variables: {state}")
@@ -254,7 +272,10 @@ class PrinterNode(Runnable):
         formatted_output = mapping[PRINTER]
         # add info label to the printer's output
         if not formatted_output == PRINTER_COMPLETED_STATE:
-            formatted_output += f"\n\n-----\n*How to proceed?*\n* *to resume the pipeline - type anything...*"
+            # convert formatted output to string if it's not
+            if not isinstance(formatted_output, str):
+                formatted_output = str(formatted_output)
+            formatted_output += f"\n\n-----\n*{self.final_message}*"
         logger.debug(f"Formatted output: {formatted_output}")
         result[PRINTER_NODE_RS] = formatted_output
         return result
@@ -441,6 +462,50 @@ def prepare_output_schema(lg_builder, memory, store, debug=False, interrupt_befo
     return compiled
 
 
+def find_tool_by_name_or_metadata(tools: list, tool_name: str, toolkit_name: Optional[str] = None) -> Optional[BaseTool]:
+    """
+    Find a tool by name or by matching metadata (toolkit_name + tool_name).
+
+    For toolkit nodes with toolkit_name specified, this function checks:
+    1. Metadata match first (toolkit_name + tool_name) - PRIORITY when toolkit_name is provided
+    2. Direct tool name match (backward compatibility fallback)
+
+    For toolkit nodes without toolkit_name, or other node types:
+    1. Direct tool name match
+
+    Args:
+        tools: List of available tools
+        tool_name: The tool name to search for
+        toolkit_name: Optional toolkit name for metadata matching
+
+    Returns:
+        The matching tool or None if not found
+    """
+    # When toolkit_name is specified, prioritize metadata matching
+    if toolkit_name:
+        for tool in tools:
+            # Check metadata match first
+            if hasattr(tool, 'metadata') and tool.metadata:
+                metadata_toolkit_name = tool.metadata.get(TOOLKIT_NAME_META)
+                metadata_tool_name = tool.metadata.get(TOOL_NAME_META)
+
+                # Match if both toolkit_name and tool_name in metadata match
+                if metadata_toolkit_name == toolkit_name and metadata_tool_name == tool_name:
+                    return tool
+
+        # Fallback to direct name match for backward compatibility
+        for tool in tools:
+            if tool.name == tool_name:
+                return tool
+    else:
+        # No toolkit_name specified, use direct name match only
+        for tool in tools:
+            if tool.name == tool_name:
+                return tool
+
+    return None
+
+
 def create_graph(
         client: Any,
         yaml_schema: str,
@@ -454,13 +519,25 @@ def create_graph(
 ):
     """ Create a message graph from a yaml schema """
 
+    # TODO: deprecate next release (1/15/2026)
     # For top-level graphs (not subgraphs), detect and flatten any subgraphs
-    if not for_subgraph:
-        flattened_yaml, additional_tools = detect_and_flatten_subgraphs(yaml_schema)
-        # Add collected tools from subgraphs to the tools list
-        tools = list(tools) + additional_tools
-        # Use the flattened YAML for building the graph
-        yaml_schema = flattened_yaml
+    # if not for_subgraph:
+    #     flattened_yaml, additional_tools = detect_and_flatten_subgraphs(yaml_schema)
+    #     # Add collected tools from subgraphs to the tools list
+    #     tools = list(tools) + additional_tools
+    #     # Use the flattened YAML for building the graph
+    #     yaml_schema = flattened_yaml
+    # else:
+    #     # For subgraphs, filter out PrinterNodes from YAML
+    #     from ..toolkits.subgraph import _filter_printer_nodes_from_yaml
+    #     yaml_schema = _filter_printer_nodes_from_yaml(yaml_schema)
+    #     logger.info("Filtered PrinterNodes from subgraph YAML in create_graph")
+
+    if for_subgraph:
+        # Sanitization for sub-graphs
+        from ..toolkits.subgraph import _filter_printer_nodes_from_yaml
+        yaml_schema = _filter_printer_nodes_from_yaml(yaml_schema)
+        logger.info("Filtered PrinterNodes from subgraph YAML in create_graph")
 
     schema = yaml.safe_load(yaml_schema)
     logger.debug(f"Schema: {schema}")
@@ -476,20 +553,37 @@ def create_graph(
             node_type = node.get('type', 'function')
             node_id = clean_string(node['id'])
             toolkit_name = node.get('toolkit_name')
-            tool_name = clean_string(node.get('tool', node_id))
-            if toolkit_name:
-                tool_name = f"{clean_string(toolkit_name)}{TOOLKIT_SPLITTER}{tool_name}"
+            tool_name = clean_string(node.get('tool', ''))
+            # Tool names are now clean (no prefix needed)
             logger.info(f"Node: {node_id} : {node_type} - {tool_name}")
             if node_type in ['function', 'toolkit', 'mcp', 'tool', 'loop', 'loop_from_tool', 'indexer', 'subgraph', 'pipeline', 'agent']:
-                if node_type == 'mcp' and tool_name not in [tool.name for tool in tools]:
-                    # MCP is not connected and node cannot be added
-                    raise ToolException(f"MCP tool '{tool_name}' not found in the provided tools. "
-                                        f"Make sure it is connected properly. Available tools: {[tool.name for tool in tools]}")
-                for tool in tools:
-                    if tool.name == tool_name:
+                if node_type in ['mcp', 'toolkit', 'agent'] and not tool_name:
+                    # tool is not specified
+                    raise ToolException(f"Tool name is required for {node_type} node with id '{node_id}'")
+
+                # Unified validation and tool finding for toolkit, mcp, and agent node types
+                matching_tool = None
+                if node_type in ['toolkit', 'mcp', 'agent']:
+                    # Use enhanced validation that checks both direct name and metadata
+                    matching_tool = find_tool_by_name_or_metadata(tools, tool_name, toolkit_name)
+                    if not matching_tool:
+                        # tool is not found in the provided tools
+                        error_msg = f"Node `{node_id}` with type `{node_type}` has tool '{tool_name}'"
+                        if toolkit_name:
+                            error_msg += f" (toolkit: '{toolkit_name}')"
+                        error_msg += f" which is not found in the provided tools. Make sure it is connected properly. Available tools: {format_tools(tools)}"
+                        raise ToolException(error_msg)
+                else:
+                    # For other node types, find tool by direct name match
+                    for tool in tools:
+                        if tool.name == tool_name:
+                            matching_tool = tool
+                            break
+
+                if matching_tool:
                         if node_type in ['function', 'toolkit', 'mcp']:
                             lg_builder.add_node(node_id, FunctionTool(
-                                tool=tool, name=node_id, return_type='dict',
+                                tool=matching_tool, name=node_id, return_type='dict',
                                 output_variables=node.get('output', []),
                                 input_mapping=node.get('input_mapping',
                                                        {'messages': {'type': 'variable', 'value': 'messages'}}),
@@ -500,7 +594,7 @@ def create_graph(
                                                      {'messages': {'type': 'variable', 'value': 'messages'}})
                             output_vars = node.get('output', [])
                             lg_builder.add_node(node_id, FunctionTool(
-                                client=client, tool=tool,
+                                client=client, tool=matching_tool,
                                 name=node_id, return_type='str',
                                 output_variables=output_vars + ['messages'] if 'messages' not in output_vars else output_vars,
                                 input_variables=input_params,
@@ -508,15 +602,15 @@ def create_graph(
                             ))
                         elif node_type == 'subgraph' or node_type == 'pipeline':
                             # assign parent memory/store
-                            # tool.checkpointer = memory
-                            # tool.store = store
+                            # matching_tool.checkpointer = memory
+                            # matching_tool.store = store
                             # wrap with mappings
                             pipeline_name = node.get('tool', None)
                             if not pipeline_name:
                                 raise ValueError(
                                     "Subgraph must have a 'tool' node: add required tool to the subgraph node")
                             node_fn = SubgraphRunnable(
-                                inner=tool.graph,
+                                inner=matching_tool.graph,
                                 name=pipeline_name,
                                 input_mapping=node.get('input_mapping', {}),
                                 output_mapping=node.get('output_mapping', {}),
@@ -525,7 +619,7 @@ def create_graph(
                             break  # skip legacy handling
                         elif node_type == 'tool':
                             lg_builder.add_node(node_id, ToolNode(
-                                client=client, tool=tool,
+                                client=client, tool=matching_tool,
                                 name=node_id, return_type='dict',
                                 output_variables=node.get('output', []),
                                 input_variables=node.get('input', ['messages']),
@@ -534,7 +628,7 @@ def create_graph(
                             ))
                         elif node_type == 'loop':
                             lg_builder.add_node(node_id, LoopNode(
-                                client=client, tool=tool,
+                                client=client, tool=matching_tool,
                                 name=node_id, return_type='dict',
                                 output_variables=node.get('output', []),
                                 input_variables=node.get('input', ['messages']),
@@ -544,15 +638,15 @@ def create_graph(
                             loop_toolkit_name = node.get('loop_toolkit_name')
                             loop_tool_name = node.get('loop_tool')
                             if (loop_toolkit_name and loop_tool_name) or loop_tool_name:
-                                loop_tool_name = f"{clean_string(loop_toolkit_name)}{TOOLKIT_SPLITTER}{loop_tool_name}" if loop_toolkit_name else clean_string(
-                                    loop_tool_name)
+                                # Use clean tool name (no prefix)
+                                loop_tool_name = clean_string(loop_tool_name)
                                 for t in tools:
                                     if t.name == loop_tool_name:
                                         logger.debug(f"Loop tool discovered: {t}")
                                         lg_builder.add_node(node_id, LoopToolNode(
                                             client=client,
                                             name=node_id, return_type='dict',
-                                            tool=tool, loop_tool=t,
+                                            tool=matching_tool, loop_tool=t,
                                             variables_mapping=node.get('variables_mapping', {}),
                                             output_variables=node.get('output', []),
                                             input_variables=node.get('input', ['messages']),
@@ -568,7 +662,7 @@ def create_graph(
                                     indexer_tool = t
                             logger.info(f"Indexer tool: {indexer_tool}")
                             lg_builder.add_node(node_id, IndexerNode(
-                                client=client, tool=tool,
+                                client=client, tool=matching_tool,
                                 index_tool=indexer_tool,
                                 input_mapping=node.get('input_mapping', {}),
                                 name=node_id, return_type='dict',
@@ -577,7 +671,6 @@ def create_graph(
                                 output_variables=node.get('output', []),
                                 input_variables=node.get('input', ['messages']),
                                 structured_output=node.get('structured_output', False)))
-                        break
             elif node_type == 'code':
                 from ..tools.sandbox import create_sandbox_tool
                 sandbox_tool = create_sandbox_tool(stateful=False, allow_net=True,
@@ -603,10 +696,10 @@ def create_graph(
                 tool_names = []
                 if isinstance(connected_tools, dict):
                     for toolkit, selected_tools in connected_tools.items():
-                        for tool in selected_tools:
-                            tool_names.append(f"{toolkit}{TOOLKIT_SPLITTER}{tool}")
+                        # Add tool names directly (no prefix)
+                        tool_names.extend(selected_tools)
                 elif isinstance(connected_tools, list):
-                    # for cases when tools are provided as a list of names with already bound toolkit_name
+                    # Use provided tool names as-is
                     tool_names = connected_tools
                 
                 if tool_names:
@@ -629,19 +722,34 @@ def create_graph(
                     output_variables=output_vars,
                     input_variables=node.get('input', ['messages']),
                     structured_output=node.get('structured_output', False),
+                    tool_execution_timeout=node.get('tool_execution_timeout', 900),
                     available_tools=available_tools,
                     tool_names=tool_names,
                     steps_limit=kwargs.get('steps_limit', 25)
                 ))
-            elif node_type == 'router':
-                # Add a RouterNode as an independent node
-                lg_builder.add_node(node_id, RouterNode(
-                    name=node_id,
-                    condition=node.get('condition', ''),
-                    routes=node.get('routes', []),
-                    default_output=node.get('default_output', 'END'),
-                    input_variables=node.get('input', ['messages'])
-                ))
+            elif node_type in ['router', 'decision']:
+                if node_type == 'router':
+                    # Add a RouterNode as an independent node
+                    lg_builder.add_node(node_id, RouterNode(
+                        name=node_id,
+                        condition=node.get('condition', ''),
+                        routes=node.get('routes', []),
+                        default_output=node.get('default_output', 'END'),
+                        input_variables=node.get('input', ['messages'])
+                    ))
+                elif node_type == 'decision':
+                    logger.info(f'Adding decision: {node["nodes"]}')
+                    # fallback to old-style decision node
+                    decisional_inputs = node.get('decisional_inputs')
+                    decisional_inputs = node.get('input', ['messages']) if not decisional_inputs else decisional_inputs
+                    lg_builder.add_node(node_id, DecisionEdge(
+                        client, node['nodes'],
+                        node.get('description', ""),
+                        decisional_inputs=decisional_inputs,
+                        default_output=node.get('default_output', 'END'),
+                        is_node=True
+                    ))
+
                 # Add a single conditional edge for all routes
                 lg_builder.add_conditional_edges(
                     node_id,
@@ -663,6 +771,7 @@ def create_graph(
             elif node_type == 'printer':
                 lg_builder.add_node(node_id, PrinterNode(
                     input_mapping=node.get('input_mapping', {'printer': {'type': 'fixed', 'value': ''}}),
+                    final_message=node.get('final_message'),
                 ))
 
                 # add interrupts after printer node if specified
@@ -732,8 +841,20 @@ def create_graph(
             debug=debug,
         )
     except ValueError as e:
-        raise ValueError(
-            f"Validation of the schema failed. {e}\n\nDEBUG INFO:**Schema Nodes:**\n\n{lg_builder.nodes}\n\n**Schema Enges:**\n\n{lg_builder.edges}\n\n**Tools Available:**\n\n{tools}")
+        # Build a clearer debug message without complex f-string expressions
+        debug_nodes = "\n*".join(lg_builder.nodes.keys()) if lg_builder and lg_builder.nodes else ""
+        debug_message = (
+            "Validation of the schema failed. {err}\n\n"
+            "DEBUG INFO:**Schema Nodes:**\n\n*{nodes}\n\n"
+            "**Schema Edges:**\n\n{edges}\n\n"
+            "**Tools Available:**\n\n{tools}"
+        ).format(
+            err=e,
+            nodes=debug_nodes,
+            edges=lg_builder.edges if lg_builder else {},
+            tools=format_tools(tools),
+        )
+        raise ValueError(debug_message)
     # If building a nested subgraph, return the raw CompiledStateGraph
     if for_subgraph:
         return graph
@@ -747,6 +868,14 @@ def create_graph(
     )
     return compiled.validate()
 
+def format_tools(tools_list: list) -> str:
+    """Format a list of tool names into a comma-separated string."""
+    try:
+        return ', '.join([tool.name for tool in tools_list])
+    except Exception as e:
+        logger.warning(f"Failed to format tools list: {e}")
+        return str(tools_list)
+
 def set_defaults(d):
     """Set default values for dictionary entries based on their type."""
     type_defaults = {
@@ -817,11 +946,19 @@ class LangGraphAgentRunnable(CompiledStateGraph):
         if not config.get("configurable", {}).get("thread_id", ""):
             config["configurable"] = {"thread_id": str(uuid4())}
         thread_id = config.get("configurable", {}).get("thread_id")
+        
+        # Check if checkpoint exists early for chat_history handling
+        checkpoint_exists = self.checkpointer and self.checkpointer.get_tuple(config)
+        
         # Handle chat history and current input properly
         if input.get('chat_history') and not input.get('messages'):
-            # Convert chat history dict messages to LangChain message objects
-            chat_history = input.pop('chat_history')
-            input['messages'] = [convert_dict_to_message(msg) for msg in chat_history]
+            if checkpoint_exists:
+                # Checkpoint already has conversation history - discard redundant chat_history
+                input.pop('chat_history', None)
+            else:
+                # No checkpoint - convert chat history dict messages to LangChain message objects
+                chat_history = input.pop('chat_history')
+                input['messages'] = [convert_dict_to_message(msg) for msg in chat_history]
 
         # handler for LLM node: if no input (Chat perspective), then take last human message
         # Track if input came from messages to handle content extraction properly
@@ -869,6 +1006,16 @@ class LangGraphAgentRunnable(CompiledStateGraph):
                         else:
                             # All content was text, remove this message from the list
                             input['messages'] = [msg for msg in input['messages'] if msg is not current_message]
+                    else:
+                        # Message came from input['input'], not from input['messages']
+                        # If there are non-text parts (images, etc.), preserve them in messages
+                        if non_text_parts:
+                            # Initialize messages if it doesn't exist or is empty
+                            if not input.get('messages'):
+                                input['messages'] = []
+                            # Create a new message with only non-text content
+                            non_text_message = HumanMessage(content=non_text_parts)
+                            input['messages'].append(non_text_message)
                 
                 elif isinstance(current_content, str):
                     # on regenerate case
@@ -902,40 +1049,99 @@ class LangGraphAgentRunnable(CompiledStateGraph):
                 "with no accompanying text."
             )
         
-        logging.info(f"Input: {thread_id} - {input}")
-        if self.checkpointer and self.checkpointer.get_tuple(config):
-            self.update_state(config, input)
-            if config.pop("should_continue", False):
-                invoke_input = input
+        logger.info(f"Input: {thread_id} - {input}")
+        try:
+            if self.checkpointer and self.checkpointer.get_tuple(config):
+                if config.pop("should_continue", False):
+                    invoke_input = input
+                else:
+                    self.update_state(config, input)
+                    invoke_input = None
+                result = super().invoke(invoke_input, config=config, *args, **kwargs)
             else:
-                invoke_input = None
-            result = super().invoke(invoke_input, config=config, *args, **kwargs)
-        else:
-            result = super().invoke(input, config=config, *args, **kwargs)
+                result = super().invoke(input, config=config, *args, **kwargs)
+        except GraphRecursionError as e:
+            current_recursion_limit = config.get("recursion_limit", 0)
+            logger.warning("ToolExecutionLimitReached caught in LangGraphAgentRunnable: %s", e)
+            return self._handle_graph_recursion_error(
+                config=config,
+                thread_id=thread_id,
+                current_recursion_limit=current_recursion_limit,
+            )
+
         try:
-            if result.get(PRINTER_NODE_RS) == PRINTER_COMPLETED_STATE:
-                output = next((msg.content for msg in reversed(result['messages']) if not isinstance(msg, HumanMessage)),
-                              result['messages'][-1].content)
+            # Check if printer node output exists
+            printer_output = result.get(PRINTER_NODE_RS)
+            if printer_output == PRINTER_COMPLETED_STATE:
+                # Printer completed, extract last AI message
+                messages = result['messages']
+                output = next(
+                    (msg.content for msg in reversed(messages)
+                     if not isinstance(msg, HumanMessage)),
+                    messages[-1].content
+                ) if messages else result.get('output')
+            elif printer_output is not None:
+                # Printer node has output (interrupted state)
+                output = printer_output
             else:
-                # used for printer node output - it will be reset by next `reset` node
-                output = result.get(PRINTER_NODE_RS)
-        except:
-            output = list(result.values())[-1]
+                # No printer node, extract last AI message from messages
+                messages = result.get('messages', [])
+                output = next(
+                    (msg.content for msg in reversed(messages)
+                     if not isinstance(msg, HumanMessage)),
+                    None
+                )
+        except Exception:
+            # Fallback: try to get last value or last message
+            output = str(list(result.values())[-1]) if result else 'Output is undefined'
         config_state = self.get_state(config)
         is_execution_finished = not config_state.next
         if is_execution_finished:
             thread_id = None
 
+        final_output = f"Assistant run has been completed, but output is None.\nAdding last message if any: {messages[-1] if messages else []}" if is_execution_finished and output is None else output
+
         result_with_state = {
-            "output": output,
+            "output": final_output,
             "thread_id": thread_id,
             "execution_finished": is_execution_finished
         }
 
         # Include all state values in the result
         if hasattr(config_state, 'values') and config_state.values:
+            # except of key = 'output' which is already included
+            for key, value in config_state.values.items():
+                if key != 'output':
+                    result_with_state[key] = value
+
+        return result_with_state
+
+    def _handle_graph_recursion_error(
+            self,
+            config: RunnableConfig,
+            thread_id: str,
+            current_recursion_limit: int,
+    ) -> dict:
+        """Handle GraphRecursionError by returning a soft-boundary response."""
+        config_state = self.get_state(config)
+        is_execution_finished = False
+
+        friendly_output = (
+            f"Tool step limit {current_recursion_limit} reached for this run. You can continue by sending another "
+            "message or refining your request."
+        )
+
+        result_with_state: dict[str, Any] = {
+            "output": friendly_output,
+            "thread_id": thread_id,
+            "execution_finished": is_execution_finished,
+            "tool_execution_limit_reached": True,
+        }
+
+        if hasattr(config_state, "values") and config_state.values:
             for key, value in config_state.values.items():
-                result_with_state[key] = value
+                if key != "output":
+                    result_with_state[key] = value
 
         return result_with_state