fastworkflow 2.13.5__py3-none-any.whl → 2.14.1__py3-none-any.whl

fastworkflow/run_agent/__main__.py

@@ -9,6 +9,9 @@ from typing import Optional
 from dotenv import dotenv_values
 from queue import Empty
 
+import dspy
+
+
 # Instantiate a global console for consistent styling
 console = None
 
@@ -44,6 +47,7 @@ def main():
 
 
     import fastworkflow
+    from fastworkflow.utils import dspy_utils
     from fastworkflow.command_executor import CommandExecutor
     from .agent_module import initialize_dspy_agent
 
@@ -174,7 +178,7 @@ def main():
         exit(1)
 
     # this could be None
-    LITELLM_API_KEY_AGENT = fastworkflow.get_env_var("LITELLM_API_KEY_AGENT")
+    lm = dspy_utils.get_lm("LLM_AGENT", "LITELLM_API_KEY_AGENT")
 
     startup_action: Optional[fastworkflow.Action] = None
     if args.startup_action:
@@ -204,12 +208,7 @@ def main():
     StartupProgress.end()
 
     try:
-        react_agent = initialize_dspy_agent(
-            fastworkflow.chat_session, 
-            LLM_AGENT, 
-            LITELLM_API_KEY_AGENT,
-            clear_cache=True
-        )
+        react_agent = initialize_dspy_agent(fastworkflow.chat_session)
     except (EnvironmentError, RuntimeError) as e:
         console.print(f"[bold red]Failed to initialize DSPy agent:[/bold red] {e}")
         exit(1)
@@ -240,7 +239,8 @@ def main():
             # Function to run agent processing in a separate thread
             def process_agent_query():
                 try:
-                    agent_response_container["response"] = react_agent(user_query=user_input_str)
+                    with dspy.context(lm=lm):
+                        agent_response_container["response"] = react_agent(user_query=user_input_str)
                 except Exception as e:
                     agent_response_container["error"] = e
 

fastworkflow/run_agent/agent_module.py

@@ -23,7 +23,9 @@ clarification_response_queue: Queue[str] = Queue()
 # DSPy Signature for the High-Level Planning Agent
 class PlanningAgentSignature(dspy.Signature):
     """
-    Prepare and execute a plan for building the final answer using the WorkflowAssistant tool.
+    Create a minimal step based todo list based only on the commands in the user query
+    Then, execute the plan for building the final answer using the WorkflowAssistant tool.
+    Double-check that all the tasks in the todo list have been completed before returning the final answer.
     """
     user_query = dspy.InputField(desc="The user's full input or question.")
     final_answer = dspy.OutputField(desc="The agent's comprehensive response to the user after interacting with the workflow.")
@@ -76,7 +78,7 @@ def _format_mcp_result_for_agent(mcp_result) -> str:
 
 def _build_assistant_tool_documentation(available_tools: List[Dict]) -> str:
     """Build simplified tool documentation for the main agent's WorkflowAssistant tool."""
-    
+
     # Guidance for the MAIN AGENT on how to call WorkflowAssistant
     main_agent_guidance = """
     Use the WorkflowAssistant to interact with a suite of underlying tools to assist the user.
@@ -91,7 +93,7 @@ def _build_assistant_tool_documentation(available_tools: List[Dict]) -> str:
     tool_docs = []
     for tool_def in available_tools:
         tool_name = tool_def['name']
-        tool_desc = tool_def['description']
+        tool_desc = tool_def['description'].split("\n")[0]
 
         # Main agent does not need the detailed input schema, only name, description and parameters.
         tool_docs.append(
@@ -144,30 +146,18 @@ def _ask_user_tool(prompt: str) -> str:
     return clarification_response_queue.get()
 
 
-def initialize_dspy_agent(chat_session: fastworkflow.ChatSession, LLM_AGENT: str, LITELLM_API_KEY_AGENT: Optional[str] = None, max_iters: int = 25, clear_cache: bool = False):
+def initialize_dspy_agent(chat_session: fastworkflow.ChatSession, max_iters: int = 25):
     """
     Configures and returns a high-level DSPy ReAct planning agent.
     The workflow tool agent is already integrated in the ChatSession.
     
     Args:
         chat_session: ChatSession instance (should be in agent mode)
-        LLM_AGENT: Language model name
-        LITELLM_API_KEY_AGENT: API key for the language model
         max_iters: Maximum iterations for the ReAct agent
-        clear_cache: If True, clears DSPy cache before initialization
     
     Raises:
         EnvironmentError: If LLM_AGENT is not set.
-        RuntimeError: If there's an error configuring the DSPy LM.
     """
-    if not LLM_AGENT:
-        print(f"{Fore.RED}Error: DSPy Language Model name not provided.{Style.RESET_ALL}")
-        raise EnvironmentError("DSPy Language Model name not provided.")
-
-    # Configure DSPy LM for the high-level agent
-    lm = dspy.LM(model=LLM_AGENT, api_key=LITELLM_API_KEY_AGENT)
-    dspy.settings.configure(lm=lm)
-
     # Get available tools for documentation
     mcp_server = FastWorkflowMCPServer(chat_session)
     available_tools = mcp_server.list_tools()

fastworkflow/utils/command_dependency_graph.py

@@ -1,16 +1,17 @@
 import json
 import os
 from dataclasses import dataclass
-from typing import Dict, List, Any, Optional
+from typing import Dict, List, Any
 
 from sentence_transformers import SentenceTransformer, util as st_util
 
-import dspy  # type: ignore
+# import dspy  # type: ignore
 
-import fastworkflow  # For env configuration when using DSPy
+# import fastworkflow  # For env configuration when using DSPy
 from fastworkflow.command_directory import CommandDirectory
 from fastworkflow.command_routing import RoutingDefinition
 from fastworkflow.utils import python_utils
+from fastworkflow.command_metadata_api import CommandMetadataAPI
 
 
 @dataclass
@@ -27,53 +28,39 @@ class CommandParams:
     outputs: List[ParamMeta]
 
 
-def _serialize_type_str(t: Any) -> str:
-    try:
-        # Basic serialization for common typing and classes
-        return t.__name__ if hasattr(t, "__name__") else str(t)
-    except Exception:
-        return str(t)
+# def _serialize_type_str(t: Any) -> str:
+#     try:
+#         # Basic serialization for common typing and classes
+#         return t.__name__ if hasattr(t, "__name__") else str(t)
+#     except Exception:
+#         return str(t)
 
 
 def _collect_command_params(workflow_path: str) -> Dict[str, CommandParams]:
-    directory = CommandDirectory.load(workflow_path)
-    routing = RoutingDefinition.build(workflow_path)
+    params_map = CommandMetadataAPI.get_params_for_all_commands(workflow_path)
 
     results: Dict[str, CommandParams] = {}
-
-    for qualified_name in directory.get_commands():
-        # Hydrate metadata and import module
-        directory.ensure_command_hydrated(qualified_name)
-        metadata = directory.get_command_metadata(qualified_name)
-        module_path = metadata.parameter_extraction_signature_module_path or metadata.response_generation_module_path
-        if not module_path:
-            continue
-        module = python_utils.get_module(str(module_path), workflow_path)
-        signature_cls = getattr(module, "Signature", None)
-        if not signature_cls:
-            continue
-
-        inputs: List[ParamMeta] = []
-        outputs: List[ParamMeta] = []
-
-        InputModel = getattr(signature_cls, "Input", None)
-        if InputModel is not None and hasattr(InputModel, "model_fields"):
-            for name, field in InputModel.model_fields.items():
-                desc = getattr(field, "description", "") or ""
-                examples = getattr(field, "examples", []) or []
-                type_str = _serialize_type_str(field.annotation)
-                inputs.append(ParamMeta(name=name, type_str=type_str, description=str(desc), examples=list(examples)))
-
-        OutputModel = getattr(signature_cls, "Output", None)
-        if OutputModel is not None and hasattr(OutputModel, "model_fields"):
-            for name, field in OutputModel.model_fields.items():
-                desc = getattr(field, "description", "") or ""
-                examples = getattr(field, "examples", []) or []
-                type_str = _serialize_type_str(field.annotation)
-                outputs.append(ParamMeta(name=name, type_str=type_str, description=str(desc), examples=list(examples)))
-
-        if contexts := routing.get_contexts_for_command(qualified_name):
-            results[qualified_name] = CommandParams(inputs=inputs, outputs=outputs)
+    for qualified_name, io in params_map.items():
+        inputs = [
+            ParamMeta(
+                name=p.get("name", ""),
+                type_str=str(p.get("type_str", "")),
+                description=str(p.get("description", "")),
+                examples=list(p.get("examples", []) or []),
+            )
+            for p in io.get("inputs", [])
+        ]
+        outputs = [
+            ParamMeta(
+                name=p.get("name", ""),
+                type_str=str(p.get("type_str", "")),
+                description=str(p.get("description", "")),
+                examples=list(p.get("examples", []) or []),
+            )
+            for p in io.get("outputs", [])
+        ]
+        # Include all discovered commands; context overlap is handled later
+        results[qualified_name] = CommandParams(inputs=inputs, outputs=outputs)
 
     return results
 
@@ -129,112 +116,112 @@ def _semantic_match(out_param: ParamMeta, in_param: ParamMeta, threshold: float
 # ----------------------------------------------------------------------------
 
 # Lazy singletons
-_llm_initialized: bool = False  # type: ignore
-_llm_module: Optional["CommandDependencyModule"] = None  # type: ignore
+# _llm_initialized: bool = False  # type: ignore
+# _llm_module: Optional["CommandDependencyModule"] = None  # type: ignore
 
 
-def _initialize_dspy_llm_if_needed() -> None:
-    """Initialize DSPy LM once using FastWorkflow environment.
+# def _initialize_dspy_llm_if_needed() -> None:
+#     """Initialize DSPy LM once using FastWorkflow environment.
 
-    Controlled by env vars:
-      - LLM_COMMAND_METADATA_GEN (model id for LiteLLM via DSPy)
-      - LITELLM_API_KEY_COMMANDMETADATA_GEN (API key)
-    """
-    global _llm_initialized, _llm_module
-    if _llm_initialized:
-        return
-
-    model = fastworkflow.get_env_var("LLM_COMMAND_METADATA_GEN")
-    api_key = fastworkflow.get_env_var("LITELLM_API_KEY_COMMANDMETADATA_GEN")
-    lm = dspy.LM(model=model, api_key=api_key, max_tokens=1000)
-    dspy.settings.configure(lm=lm)
-
-    # Define signature and module only if dspy is available
-    class CommandDependencySignature(dspy.Signature):  # type: ignore
-        """Analyze if two commands have a dependency relationship.
-
-        There is a dependency relationship if and only if the outputs from one command can be used directly as inputs of the other.
-        Tip for figuring out dependency direction: Commands with hard-to-remember inputs (such as id) typically depend on commands with easy to remember inputs (such as name, email).
-        """
-
-        cmd_x_name: str = dspy.InputField(desc="Name of command X")
-        cmd_x_inputs: str = dspy.InputField(desc="Input parameters of command X (name:type)")
-        cmd_x_outputs: str = dspy.InputField(desc="Output parameters of command X (name:type)")
-        
-        cmd_y_name: str = dspy.InputField(desc="Name of command Y")
-        cmd_y_inputs: str = dspy.InputField(desc="Input parameters of command Y (name:type)")
-        cmd_y_outputs: str = dspy.InputField(desc="Output parameters of command Y (name:type)")
-
-        has_dependency: bool = dspy.OutputField(
-            desc="True if there's a dependency between the commands"
-        )
-        direction: str = dspy.OutputField(
-            desc="Direction: 'x_depends_on_y', 'y_depends_on_x', or 'none'"
-        )
+#     Controlled by env vars:
+#       - LLM_COMMAND_METADATA_GEN (model id for LiteLLM via DSPy)
+#       - LITELLM_API_KEY_COMMANDMETADATA_GEN (API key)
+#     """
+#     global _llm_initialized, _llm_module
+#     if _llm_initialized:
+#         return
 
-    class CommandDependencyModule(dspy.Module):  # type: ignore
-        def __init__(self):
-            super().__init__()
-            self.generate = dspy.ChainOfThought(CommandDependencySignature)
-
-        def forward(
-            self,
-            cmd_x_name: str,
-            cmd_x_inputs: str,
-            cmd_x_outputs: str,
-            cmd_y_name: str,
-            cmd_y_inputs: str,
-            cmd_y_outputs: str,
-        ) -> tuple[bool, str]:
-            prediction = self.generate(
-                cmd_x_name=cmd_x_name,
-                cmd_x_inputs=cmd_x_inputs,
-                cmd_x_outputs=cmd_x_outputs,
-                cmd_y_name=cmd_y_name,
-                cmd_y_inputs=cmd_y_inputs,
-                cmd_y_outputs=cmd_y_outputs,
-            )
-            return prediction.has_dependency, prediction.direction
+#     model = fastworkflow.get_env_var("LLM_COMMAND_METADATA_GEN")
+#     api_key = fastworkflow.get_env_var("LITELLM_API_KEY_COMMANDMETADATA_GEN")
+#     lm = dspy.LM(model=model, api_key=api_key, max_tokens=1000)
 
-    _llm_module = CommandDependencyModule()
-    _llm_initialized = True
+#     # Define signature and module only if dspy is available
+#     class CommandDependencySignature(dspy.Signature):  # type: ignore
+#         """Analyze if two commands have a dependency relationship.
 
+#         There is a dependency relationship if and only if the outputs from one command can be used directly as inputs of the other.
+#         Tip for figuring out dependency direction: Commands with hard-to-remember inputs (such as id) typically depend on commands with easy to remember inputs (such as name, email).
+#         """
 
-def _llm_command_dependency(
-    cmd_x_name: str, 
-    cmd_x_params: CommandParams,
-    cmd_y_name: str,
-    cmd_y_params: CommandParams
-) -> Optional[str]:
-    """Check if two commands have a dependency using LLM.
+#         cmd_x_name: str = dspy.InputField(desc="Name of command X")
+#         cmd_x_inputs: str = dspy.InputField(desc="Input parameters of command X (name:type)")
+#         cmd_x_outputs: str = dspy.InputField(desc="Output parameters of command X (name:type)")
+        
+#         cmd_y_name: str = dspy.InputField(desc="Name of command Y")
+#         cmd_y_inputs: str = dspy.InputField(desc="Input parameters of command Y (name:type)")
+#         cmd_y_outputs: str = dspy.InputField(desc="Output parameters of command Y (name:type)")
+
+#         has_dependency: bool = dspy.OutputField(
+#             desc="True if there's a dependency between the commands"
+#         )
+#         direction: str = dspy.OutputField(
+#             desc="Direction: 'x_depends_on_y', 'y_depends_on_x', or 'none'"
+#         )
+
+#     class CommandDependencyModule(dspy.Module):  # type: ignore
+#         def __init__(self):
+#             super().__init__()
+#             self.generate = dspy.ChainOfThought(CommandDependencySignature)
+
+#         def forward(
+#             self,
+#             cmd_x_name: str,
+#             cmd_x_inputs: str,
+#             cmd_x_outputs: str,
+#             cmd_y_name: str,
+#             cmd_y_inputs: str,
+#             cmd_y_outputs: str,
+#         ) -> tuple[bool, str]:
+#             with dspy.context(lm=lm):
+#                 prediction = self.generate(
+#                     cmd_x_name=cmd_x_name,
+#                     cmd_x_inputs=cmd_x_inputs,
+#                     cmd_x_outputs=cmd_x_outputs,
+#                     cmd_y_name=cmd_y_name,
+#                     cmd_y_inputs=cmd_y_inputs,
+#                     cmd_y_outputs=cmd_y_outputs,
+#                 )
+#                 return prediction.has_dependency, prediction.direction
+
+#     _llm_module = CommandDependencyModule()
+#     _llm_initialized = True
+
+
+# def _llm_command_dependency(
+#     cmd_x_name: str, 
+#     cmd_x_params: CommandParams,
+#     cmd_y_name: str,
+#     cmd_y_params: CommandParams
+# ) -> Optional[str]:
+#     """Check if two commands have a dependency using LLM.
     
-    Returns:
-        - "x_to_y" if Y depends on X (X's outputs feed Y's inputs)
-        - "y_to_x" if X depends on Y (Y's outputs feed X's inputs)  
-        - None if no dependency
-    """
-    _initialize_dspy_llm_if_needed()
-
-    # Format parameters for LLM
-    x_inputs = ", ".join([f"{p.name}:{p.type_str}" for p in cmd_x_params.inputs])
-    x_outputs = ", ".join([f"{p.name}:{p.type_str}" for p in cmd_x_params.outputs])
-    y_inputs = ", ".join([f"{p.name}:{p.type_str}" for p in cmd_y_params.inputs])
-    y_outputs = ", ".join([f"{p.name}:{p.type_str}" for p in cmd_y_params.outputs])
-
-    has_dep, direction = _llm_module(
-        cmd_x_name=cmd_x_name,
-        cmd_x_inputs=x_inputs or "none",
-        cmd_x_outputs=x_outputs or "none",
-        cmd_y_name=cmd_y_name,
-        cmd_y_inputs=y_inputs or "none",
-        cmd_y_outputs=y_outputs or "none",
-    )
-
-    if not has_dep or direction == "none":
-        return None
-    if direction == "x_depends_on_y":
-        return "y_to_x"  # Y's outputs -> X's inputs
-    return "x_to_y" if direction == "y_depends_on_x" else None
+#     Returns:
+#         - "x_to_y" if Y depends on X (X's outputs feed Y's inputs)
+#         - "y_to_x" if X depends on Y (Y's outputs feed X's inputs)  
+#         - None if no dependency
+#     """
+#     _initialize_dspy_llm_if_needed()
+
+#     # Format parameters for LLM
+#     x_inputs = ", ".join([f"{p.name}:{p.type_str}" for p in cmd_x_params.inputs])
+#     x_outputs = ", ".join([f"{p.name}:{p.type_str}" for p in cmd_x_params.outputs])
+#     y_inputs = ", ".join([f"{p.name}:{p.type_str}" for p in cmd_y_params.inputs])
+#     y_outputs = ", ".join([f"{p.name}:{p.type_str}" for p in cmd_y_params.outputs])
+
+#     has_dep, direction = _llm_module(
+#         cmd_x_name=cmd_x_name,
+#         cmd_x_inputs=x_inputs or "none",
+#         cmd_x_outputs=x_outputs or "none",
+#         cmd_y_name=cmd_y_name,
+#         cmd_y_inputs=y_inputs or "none",
+#         cmd_y_outputs=y_outputs or "none",
+#     )
+
+#     if not has_dep or direction == "none":
+#         return None
+#     if direction == "x_depends_on_y":
+#         return "y_to_x"  # Y's outputs -> X's inputs
+#     return "x_to_y" if direction == "y_depends_on_x" else None
 
 
 def _contexts_overlap(routing: RoutingDefinition, cmd_x: str, cmd_y: str) -> bool:

fastworkflow/utils/dspy_utils.py

@@ -2,6 +2,17 @@ import dspy
 from pydantic import BaseModel, Field
 from typing import Type, Optional, Dict, Any, Union, get_args, get_origin, Tuple, List
 
+import fastworkflow
+from fastworkflow.utils.logging import logger
+
+def get_lm(model_env_var: str, api_key_env_var: Optional[str] = None, **kwargs):
+    """get the dspy lm object"""
+    model = fastworkflow.get_env_var(model_env_var)
+    if not model:
+        logger.critical(f"Critical Error:DSPy Language Model not provided. Set {model_env_var} environment variable.")
+        raise ValueError(f"DSPy Language Model not provided. Set {model_env_var} environment variable.")
+    api_key = fastworkflow.get_env_var(api_key_env_var) if api_key_env_var else None
+    return dspy.LM(model=model, api_key=api_key, **kwargs) if api_key else dspy.LM(model=model, **kwargs)
 
 def _process_field(field_info, is_input: bool) -> Tuple[Any, Any, bool]:
     """Process a single field and return its type, DSPy field, and optional status."""

fastworkflow/utils/signatures.py

@@ -417,6 +417,13 @@ Today's date is {today}.
         if missing_fields:
             message += f"{MISSING_INFORMATION_ERRMSG}" + ", ".join(missing_fields) + "\n"
 
+            for missing_field in missing_fields:
+                is_available_from = None
+                if hasattr(type(cmd_parameters).model_fields.get(missing_field), "json_schema_extra") and type(cmd_parameters).model_fields.get(missing_field).json_schema_extra:
+                    is_available_from = type(cmd_parameters).model_fields.get(missing_field).json_schema_extra.get("available_from")
+                if is_available_from:
+                    message += f"abort and use the {' or '.join(is_available_from)} command(s) to get {missing_field} information\n"
+
         if invalid_fields:
             message += f"{INVALID_INFORMATION_ERRMSG}" + ", ".join(invalid_fields) + "\n"
 

fastworkflow/workflow_agent.py

@@ -0,0 +1,186 @@
+"""
+Agent integration module for fastWorkflow.
+Provides workflow tool agent functionality for intelligent tool selection.
+"""
+
+import dspy
+
+import fastworkflow
+from fastworkflow.utils import dspy_utils
+from fastworkflow.command_metadata_api import CommandMetadataAPI
+from fastworkflow.mcp_server import FastWorkflowMCPServer
+
+
+class WorkflowAgentSignature(dspy.Signature):
+    """
+    Carefully review the user request and execute the todo list using available tools for building the final answer.
+    All the tasks in the todo list must be completed before returning the final answer.
+    """
+    user_query = dspy.InputField(desc="The natural language user query.")
+    final_answer = dspy.OutputField(desc="Comprehensive final answer with supporting evidence to demonstrate that all the tasks in the todo list have been completed.")
+
+def _what_can_i_do(chat_session_obj: fastworkflow.ChatSession) -> str:
+    """
+    Returns a list of available commands, including their names and parameters.
+    """
+    current_workflow = chat_session_obj.get_active_workflow()
+    return CommandMetadataAPI.get_command_display_text(
+        subject_workflow_path=current_workflow.folderpath,
+        cme_workflow_path=fastworkflow.get_internal_workflow_path("command_metadata_extraction"),
+        active_context_name=current_workflow.current_command_context_name,
+    )
+
+def _provide_missing_or_corrected_parameters(
+        missing_or_corrected_parameter_values: list[str|int|float|bool],
+        chat_session_obj: fastworkflow.ChatSession) -> str:
+    """
+    Call this tool ONLY in the parameter extraction error state to provide missing or corrected parameter values.
+    Missing parameter values may be found in the user query, or information already available, or by executing a different command (refer to the optional 'available_from' hint for guidance on appropriate commands to use to get the information).
+    If the error message indicates parameter values are improperly formatted, correct using your internal knowledge.
+    """
+    if missing_or_corrected_parameter_values:
+        command = ', '.join(missing_or_corrected_parameter_values)
+    else:
+        return "Provide missing or corrected parameter values or abort"
+    
+    return _execute_workflow_query(command, chat_session_obj = chat_session_obj)
+
+def _abort_current_command_to_exit_parameter_extraction_error_state(
+        chat_session_obj: fastworkflow.ChatSession) -> str:
+    """
+    Call this tool ONLY in the parameter extraction error state when you want to get out of the parameter extraction error state and execute a different command.
+    """
+    return _execute_workflow_query('abort', chat_session_obj = chat_session_obj)
+
+def _execute_workflow_query(command: str, chat_session_obj: fastworkflow.ChatSession) -> str:
+    """
+    Executes the command and returns either a response, or a clarification request.
+    Use the "what_can_i_do" tool to get details on available commands, including their names and parameters. Fyi, values in the 'examples' field are fake and for illustration purposes only.
+    Commands must be formatted as follows: command_name <param1_name>param1_value</param1_name> <param2_name>param2_value</param2_name> ...
+    Don't use this tool to respond to a clarification requests in PARAMETER EXTRACTION ERROR state
+    """
+    # Directly invoke the command without going through queues
+    # This allows the agent to synchronously call workflow tools
+    from fastworkflow.command_executor import CommandExecutor
+    command_output = CommandExecutor.invoke_command(chat_session_obj, command)
+
+    # Format output - extract text from command response
+    if hasattr(command_output, 'command_responses') and command_output.command_responses:
+        response_parts = []
+        response_parts.extend(
+            cmd_response.response
+            for cmd_response in command_output.command_responses
+            if hasattr(cmd_response, 'response') and cmd_response.response
+        )
+        return "\n".join(response_parts) if response_parts else "Command executed successfully."
+
+    return "Command executed but produced no output."
+
+def _missing_information_guidance_tool(
+        how_to_find_request: str, 
+        chat_session_obj: fastworkflow.ChatSession) -> str:
+    """
+    Request guidance on finding missing information. 
+    The how_to_find_request must be plain text without any formatting.
+    """
+    lm = dspy_utils.get_lm("LLM_AGENT", "LITELLM_API_KEY_AGENT")
+    with dspy.context(lm=lm):
+        guidance_func = dspy.ChainOfThought(
+            "command_info, missing_information_guidance_request -> guidance: str")
+        prediction = guidance_func(
+            command_info=_what_can_i_do(chat_session_obj), 
+            missing_information_guidance_request=how_to_find_request)
+        return prediction.guidance
+
+def _ask_user_tool(clarification_request: str, chat_session_obj: fastworkflow.ChatSession) -> str:
+    """
+    As a last resort, request clarification for missing information (only after using the missing_information_guidance_tool) or error correction from the human user. 
+    The clarification_request must be plain text without any formatting.
+    """
+    command_output = fastworkflow.CommandOutput(
+        command_responses=[fastworkflow.CommandResponse(response=clarification_request)]
+    )
+    chat_session_obj.command_output_queue.put(command_output)
+    return chat_session_obj.user_message_queue.get()
+
+def initialize_workflow_tool_agent(mcp_server: FastWorkflowMCPServer, max_iters: int = 25):
+    """
+    Initialize and return a DSPy ReAct agent that exposes individual MCP tools.
+    Each tool expects a single query string for its specific tool.
+    
+    Args:
+        mcp_server: FastWorkflowMCPServer instance
+        max_iters: Maximum iterations for the ReAct agent
+        
+    Returns:
+        DSPy ReAct agent configured with workflow tools
+    """
+    # available_tools = mcp_server.list_tools()
+
+    # if not available_tools:
+    #     return None
+
+    chat_session_obj = mcp_server.chat_session
+    if not chat_session_obj:
+        return None
+
+    def what_can_i_do() -> str:
+        """
+        Returns a list of available commands, including their names and parameters
+        """
+        return _what_can_i_do(chat_session_obj=chat_session_obj)
+
+    def provide_missing_or_corrected_parameters(
+            missing_or_corrected_parameter_values: list[str|int|float|bool]) -> str:
+        """
+        Call this tool ONLY in the parameter extraction error state to provide missing or corrected parameter values.
+        Missing parameter values may be found in the user query, or information already available, or by executing a different command (refer to the optional 'available_from' hint for guidance on appropriate commands to use to get the information).
+        If the error message indicates parameter values are improperly formatted, correct using your internal knowledge.
+        """
+        return _provide_missing_or_corrected_parameters(missing_or_corrected_parameter_values, chat_session_obj=chat_session_obj)
+
+
+    def abort_current_command_to_exit_parameter_extraction_error_state() -> str:
+        """
+        Call this tool ONLY in the parameter extraction error state when you want to get out of the parameter extraction error state and execute a different command.
+        """
+        return _abort_current_command_to_exit_parameter_extraction_error_state(
+            chat_session_obj=chat_session_obj)
+
+    def execute_workflow_query(command: str) -> str:
+        """
+        Executes the command and returns either a response, or a clarification request.
+        Use the "what_can_i_do" tool to get details on available commands, including their names and parameters. Fyi, values in the 'examples' field are fake and for illustration purposes only.
+        Commands must be formatted as follows: command_name <param1_name>param1_value</param1_name> <param2_name>param2_value</param2_name> ...
+        Don't use this tool to respond to a clarification requests in PARAMETER EXTRACTION ERROR state
+        """
+        return _execute_workflow_query(command, chat_session_obj=chat_session_obj)
+
+    def missing_information_guidance(how_to_find_request: str) -> str:
+        """
+        Request guidance on finding missing information. 
+        The how_to_find_request must be plain text without any formatting.
+        """
+        return _missing_information_guidance_tool(how_to_find_request, chat_session_obj=chat_session_obj)
+
+    def ask_user(clarification_request: str) -> str:
+        """
+        As a last resort, request clarification for missing information (only after using the missing_information_guidance_tool) or error correction from the human user. 
+        The clarification_request must be plain text without any formatting.
+        """
+        return _ask_user_tool(clarification_request, chat_session_obj=chat_session_obj)
+
+    tools = [
+        what_can_i_do,
+        execute_workflow_query,
+        missing_information_guidance,
+        ask_user,
+        provide_missing_or_corrected_parameters,
+        abort_current_command_to_exit_parameter_extraction_error_state,
+    ]
+
+    return dspy.ReAct(
+        WorkflowAgentSignature,
+        tools=tools,
+        max_iters=max_iters,
+    )