rasa-pro 3.13.6__py3-none-any.whl → 3.14.0.dev1__py3-none-any.whl

rasa/shared/core/flows/flows_yaml_schema.json

@@ -1,20 +1,12 @@
 {
     "type": "object",
-    "required": [
-        "flows"
-    ],
+    "required": ["flows"],
     "properties": {
-        "version": {
-            "type": "string"
-        },
+        "version": {"type": "string"},
         "flows": {
             "type": "object",
             "schema_name": "dictionary of flows",
-            "patternProperties": {
-                "^[A-Za-z_][A-Za-z0-9_]*$": {
-                    "$ref": "#/$defs/flow"
-                }
-            }
+            "patternProperties": {"^[A-Za-z_][A-Za-z0-9_]*$": {"$ref": "#/$defs/flow"}}
         }
     },
     "$defs": {
@@ -28,34 +20,22 @@
                     {
                         "schema_name": "intent trigger",
                         "type": "object",
-                        "required": [
-                            "intent"
-                        ],
+                        "required": ["intent"],
                         "additionalProperties": false,
                         "properties": {
                             "intent": {
                                 "type": "object",
                                 "properties": {
-                                    "confidence_threshold": {
-                                        "type": "number"
-                                    },
-                                    "name": {
-                                        "type": "string"
-                                    }
+                                    "confidence_threshold": {"type": "number"},
+                                    "name": {"type": "string"}
                                 },
-                                "required": [
-                                    "name"
-                                ]
+                                "required": ["name"]
                             }
                         }
                     },
                     {
                         "schema_name": "simple intent trigger",
-                        "properties": {
-                            "intent": {
-                                "type": "string"
-                            }
-                        }
+                        "properties": {"intent": {"type": "string"}}
                     }
                 ]
             }
@@ -66,9 +46,7 @@
             "items": {
                 "type": "object",
                 "properties": {
-                    "id": {
-                        "type": "string"
-                    },
+                    "id": {"type": "string"},
                     "next": {
                         "anyOf": [
                             {
@@ -79,16 +57,11 @@
                                     "oneOf": [
                                         {
                                             "schema_name": "if-then block",
-                                            "required": [
-                                                "if",
-                                                "then"
-                                            ]
+                                            "required": ["if", "then"]
                                         },
                                         {
                                             "schema_name": "else block",
-                                            "required": [
-                                                "else"
-                                            ]
+                                            "required": ["else"]
                                         }
                                     ],
                                     "properties": {
@@ -104,12 +77,7 @@
                                                 }
                                             ]
                                         },
-                                        "if": {
-                                            "type": [
-                                                "boolean",
-                                                "string"
-                                            ]
-                                        },
+                                        "if": {"type": ["boolean", "string"]},
                                         "then": {
                                             "oneOf": [
                                                 {
@@ -125,66 +93,25 @@
                                     }
                                 }
                             },
-                            {
-                                "type": "string",
-                                "schema_name": "step id"
-                            }
+                            {"type": "string", "schema_name": "step id"}
                         ]
                     },
-                    "action": {
-                        "type": "string"
-                    },
-                    "collect": {
-                        "type": "string"
-                    },
-                    "link": {
-                        "type": "string"
-                    },
-                    "call": {
-                        "type": "string"
-                    },
+                    "action": {"type": "string"},
+                    "collect": {"type": "string"},
+                    "link": {"type": "string"},
+                    "call": {"type": "string"},
                     "set_slots": {
                         "$ref": "#/$defs/set_slots",
                         "schema_name": "slot set"
                     }
                 },
                 "oneOf": [
-                    {
-                        "required": [
-                            "action"
-                        ],
-                        "schema_name": "action step"
-                    },
-                    {
-                        "required": [
-                            "collect"
-                        ],
-                        "schema_name": "collect step"
-                    },
-                    {
-                        "required": [
-                            "link"
-                        ],
-                        "schema_name": "link step"
-                    },
-                    {
-                        "required": [
-                            "call"
-                        ],
-                        "schema_name": "call step"
-                    },
-                    {
-                        "required": [
-                            "set_slots"
-                        ],
-                        "schema_name": "slot set step"
-                    },
-                    {
-                        "required": [
-                            "noop"
-                        ],
-                        "schema_name": ""
-                    }
+                    {"required": ["action"], "schema_name": "action step"},
+                    {"required": ["collect"], "schema_name": "collect step"},
+                    {"required": ["link"], "schema_name": "link step"},
+                    {"required": ["call"], "schema_name": "call step"},
+                    {"required": ["set_slots"], "schema_name": "slot set step"},
+                    {"required": ["noop"], "schema_name": ""}
                 ],
                 "dependentSchemas": {
                     "action": {
@@ -196,10 +123,23 @@
                             "metadata": {}
                         }
                     },
-                    "noop": {
-                        "required": [
-                            "next"
-                        ]
+                    "noop": {"required": ["next"]},
+                    "call": {
+                        "additionalProperties": false,
+                        "properties": {
+                            "call": {"type": "string"},
+                            "id": {},
+                            "next": {},
+                            "metadata": {},
+                            "description": {"type": "string"},
+                            "mcp_server": {"type": "string"},
+                            "mapping": {"$ref": "#/$defs/call_step/properties/mapping"},
+                            "exit_if": {"$ref": "#/$defs/call_step/properties/exit_if"}
+                        },
+                        "dependentSchemas": {
+                            "mcp_server": {"required": ["mapping"]},
+                            "mapping": {"required": ["mcp_server"]}
+                        }
                     },
                     "collect": {
                         "additionalProperties": false,
@@ -208,130 +148,105 @@
                             "id": {},
                             "next": {},
                             "metadata": {},
-                            "description": {
-                                "type": "string"
-                            },
-                            "ask_before_filling": {
-                                "type": "boolean"
-                            },
-                            "reset_after_flow_ends": {
-                                "type": "boolean"
-                            },
-                            "utter": {
-                                "type": "string"
-                            },
-                            "force_slot_filling": {
-                                "type": "boolean"
-                            },
+                            "description": {"type": "string"},
+                            "ask_before_filling": {"type": "boolean"},
+                            "reset_after_flow_ends": {"type": "boolean"},
+                            "utter": {"type": "string"},
+                            "force_slot_filling": {"type": "boolean"},
                             "rejections": {
                                 "type": "array",
                                 "schema_name": "list of rejections",
                                 "items": {
                                     "type": "object",
-                                    "required": [
-                                        "if",
-                                        "utter"
-                                    ],
+                                    "required": ["if", "utter"],
                                     "properties": {
-                                        "if": {
-                                            "type": [
-                                                "boolean",
-                                                "string"
-                                            ]
-                                        },
-                                        "utter": {
-                                            "type": "string"
-                                        }
+                                        "if": {"type": ["boolean", "string"]},
+                                        "utter": {"type": "string"}
                                     }
                                 }
                             },
-                            "silence_timeout": {
-                                "type": "number"
-                            }
+                            "silence_timeout": {"type": "number"}
                         }
                     }
                 }
             }
         },
         "flow": {
-            "required": [
-                "steps",
-                "description"
-            ],
+            "required": ["steps", "description"],
             "type": "object",
             "additionalProperties": false,
             "schema_name": "dictionary with flow properties",
             "properties": {
-                "name": {
-                    "type": "string"
-                },
-                "description": {
-                    "type": "string"
-                },
+                "name": {"type": "string"},
+                "description": {"type": "string"},
                 "translation": {
                     "type": "object",
+                    "additionalProperties": false,
                     "schema_name": "flow translation mapping",
-                    "properties": {
-                        "metadata": {
-                            "type": "object"
-                        }
-                    },
+                    "properties": {"metadata": {"type": "object"}},
                     "patternProperties": {
                         "^(?!metadata$).+": {
                             "type": "object",
                             "additionalProperties": false,
-                            "required": [
-                                "name"
-                            ],
-                            "properties": {
-                                "name": {
-                                    "type": "string"
-                                },
-                                "metadata": {}
-                            }
+                            "required": ["name"],
+                            "properties": {"name": {"type": "string"}, "metadata": {}}
                         }
-                    },
-                    "additionalProperties": false
-                },
-                "if": {
-                    "type": [
-                        "string",
-                        "boolean"
-                    ]
-                },
-                "always_include_in_prompt": {
-                    "type": "boolean"
-                },
-                "nlu_trigger": {
-                    "$ref": "#/$defs/nlu_trigger"
-                },
-                "file_path": {
-                    "type": "string"
-                },
-                "steps": {
-                    "$ref": "#/$defs/steps"
-                },
-                "persisted_slots": {
-                    "$ref": "#/$defs/persisted_slots"
+                    }
                 },
-                "run_pattern_completed": {
-                    "type": "boolean"
-                }
+                "if": {"type": ["string", "boolean"]},
+                "always_include_in_prompt": {"type": "boolean"},
+                "nlu_trigger": {"$ref": "#/$defs/nlu_trigger"},
+                "file_path": {"type": "string"},
+                "steps": {"$ref": "#/$defs/steps"},
+                "persisted_slots": {"$ref": "#/$defs/persisted_slots"},
+                "run_pattern_completed": {"type": "boolean"}
             }
         },
         "set_slots": {
             "type": "array",
             "schema_name": "list of slot sets",
-            "items": {
-                "type": "object"
+            "items": {"type": "object"}
+        },
+        "call_step": {
+            "type": "object",
+            "additionalProperties": false,
+            "schema_name": "dictionary with call properties",
+            "required": ["call"],
+            "properties": {
+                "call": {"type": "string"},
+                "mcp_server": {"type": "string"},
+                "mapping": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "schema_name": "input and output mapping for a MCP tool call",
+                    "required": ["input", "output"],
+                    "properties": {
+                        "input": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "additionalProperties": false,
+                                "required": ["slot", "param"],
+                                "properties": {
+                                    "slot": {"type": "string"},
+                                    "param": {"type": "string"}
+                                }
+                            }
+                        },
+                        "output": {"type": "string"}
+                    }
+                },
+                "exit_if": {
+                    "type": "array",
+                    "schema_name": "list of slot predicates to exit agent call",
+                    "items": {"type": ["string"]}
+                }
             }
         },
         "persisted_slots": {
             "type": "array",
             "schema_name": "list of slots",
-            "items": {
-                "type": "string"
-            }
+            "items": {"type": "string"}
         }
     }
 }

rasa/shared/core/flows/steps/call.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Dict, Generator, Optional, Text
+from typing import TYPE_CHECKING, Any, Dict, Generator, List, Optional, Text
 
+from rasa.core.available_agents import AvailableAgents
+from rasa.core.available_endpoints import AvailableEndpoints
 from rasa.shared.core.flows.flow_step import FlowStep
 
 if TYPE_CHECKING:
@@ -11,11 +13,19 @@ if TYPE_CHECKING:
 
 @dataclass
 class CallFlowStep(FlowStep):
-    """Represents the configuration of an call flow step."""
+    """Represents the configuration of a call flow/agent step."""
 
     call: Text
-    """The flow to be called."""
+    """The flow to be called or the ID of the agent to be called."""
     called_flow_reference: Optional["Flow"] = None
+    # MCP Tool calling
+    """The MCP server that hosts the tool to be called."""
+    mcp_server: Optional[str] = None
+    """The input and output mapping for the MCP tool."""
+    mapping: Optional[Dict[str, Any]] = None
+    # Call agent exit condition
+    """A list of slot predicates that determine when to exit the agent loop."""
+    exit_if: Optional[List[str]] = None
 
     @classmethod
     def from_json(cls, flow_id: Text, data: Dict[Text, Any]) -> CallFlowStep:
@@ -31,6 +41,9 @@ class CallFlowStep(FlowStep):
         base = super().from_json(flow_id, data)
         return CallFlowStep(
             call=data.get("call", ""),
+            mcp_server=data.get("mcp_server", None),
+            mapping=data.get("mapping", None),
+            exit_if=data.get("exit_if", None),
             **base.__dict__,
         )
 
@@ -40,7 +53,16 @@ class CallFlowStep(FlowStep):
         Returns:
             The flow step as a dictionary.
         """
-        return super().as_json(step_properties={"call": self.call})
+        step_properties: Dict[str, Any] = {
+            "call": self.call,
+        }
+        if self.is_calling_mcp_tool():
+            step_properties["mcp_server"] = self.mcp_server
+            step_properties["mapping"] = self.mapping
+        if self.exit_if:
+            step_properties["exit_if"] = self.exit_if
+
+        return super().as_json(step_properties=step_properties)
 
     def steps_in_tree(
         self, should_resolve_calls: bool = True
@@ -48,7 +70,7 @@ class CallFlowStep(FlowStep):
         """Returns the steps in the tree of the flow step."""
         yield self
 
-        if should_resolve_calls:
+        if should_resolve_calls and self.is_calling_flow():
             if not self.called_flow_reference:
                 raise ValueError("Call flow reference not set.")
 
@@ -56,6 +78,27 @@ class CallFlowStep(FlowStep):
 
         yield from self.next.steps_in_tree(should_resolve_calls)
 
+    def is_calling_flow(self) -> bool:
+        """Returns True if the call references a flow."""
+        return not self.is_calling_mcp_tool() and not self.is_calling_agent()
+
+    def is_calling_mcp_tool(self) -> bool:
+        """Returns True if the call references an MCP tool of an existing MCP server."""
+        mcp_server_list = AvailableEndpoints.get_instance().mcp_servers
+        if mcp_server_list is None:
+            return False
+
+        mcp_server_names = [server.name for server in mcp_server_list]
+        return (
+            self.mcp_server is not None
+            and self.mapping is not None
+            and self.mcp_server in mcp_server_names
+        )
+
+    def is_calling_agent(self) -> bool:
+        """Returns True if the call references an agent."""
+        return self.call in AvailableAgents.get_instance().agents
+
     @property
     def default_id_postfix(self) -> str:
         """Returns the default id postfix of the flow step."""
@@ -66,6 +109,9 @@ class CallFlowStep(FlowStep):
             return (
                 self.call == other.call
                 and self.called_flow_reference == other.called_flow_reference
+                and self.mcp_server == other.mcp_server
+                and self.mapping == other.mapping
+                and self.exit_if == other.exit_if
                 and super().__eq__(other)
             )
         return False

rasa/shared/core/flows/validation.py

@@ -261,7 +261,7 @@ class NoLinkAllowedInCalledFlowException(RasaException):
         )
 
 
-class UnresolvedFlowException(RasaException):
+class UnresolvedLinkFlowException(RasaException):
     """Raised when a flow is called or linked from another flow but doesn't exist."""
 
     def __init__(self, flow_id: str, calling_flow_id: str, step_id: str) -> None:
@@ -273,13 +273,37 @@ class UnresolvedFlowException(RasaException):
     def __str__(self) -> str:
         """Return a string representation of the exception."""
         return (
-            f"Flow '{self.flow_id}' is called or linked from flow "
+            f"Flow '{self.flow_id}' is linked from flow "
             f"'{self.calling_flow_id}' in step '{self.step_id}', "
             f"but it doesn't exist. "
             f"Please make sure that a flow with id '{self.flow_id}' exists."
         )
 
 
+class UnresolvedCallStepException(RasaException):
+    """Valid call step should have a reference to an existing flow or agent.
+    Raised when it does not.
+    """
+
+    def __init__(
+        self, call_step_argument: str, calling_flow_id: str, step_id: str
+    ) -> None:
+        """Initializes the exception."""
+        self.call_step_argument = call_step_argument
+        self.calling_flow_id = calling_flow_id
+        self.step_id = step_id
+
+    def __str__(self) -> str:
+        """Return a string representation of the exception."""
+        return (
+            f"The call step '{self.step_id}' in flow '{self.calling_flow_id}' "
+            f"is invalid: there is no flow or agent with the "
+            f"id '{self.call_step_argument}'. "
+            f"Please make sure that the call step argument is a valid flow id "
+            f"or an agent id."
+        )
+
+
 class UnresolvedFlowStepIdException(RasaException):
     """Raised when a flow step is referenced, but its id can not be resolved."""
 
@@ -562,15 +586,29 @@ def validate_link_in_call_restriction(flows: "FlowsList") -> None:
                 raise NoLinkAllowedInCalledFlowException(step.id, flow.id, step.call)
 
 
-def validate_called_flows_exists(flows: "FlowsList") -> None:
-    """Validates that all called flows exist."""
+def validate_call_steps(flows: "FlowsList") -> None:
+    """Validates that all called flows/agents exist and additional properties
+    are valid.
+    """
     for flow in flows.underlying_flows:
         for step in flow.steps:
             if not isinstance(step, CallFlowStep):
                 continue
 
-            if flows.flow_by_id(step.call) is None:
-                raise UnresolvedFlowException(step.call, flow.id, step.id)
+            if (
+                not step.is_calling_agent()
+                and flows.flow_by_id(step.call) is None
+                and not step.is_calling_mcp_tool()
+            ):
+                raise UnresolvedCallStepException(step.call, flow.id, step.id)
+
+            if step.exit_if and not step.is_calling_agent():
+                # exit_if is only allowed for call steps that call an agent
+                raise RasaException(
+                    f"Call step '{step.id}' in flow '{flow.id}' has an 'exit_if' "
+                    f"condition, but it is not calling an agent. "
+                    f"'exit_if' is only allowed for call steps that call an agent."
+                )
 
 
 def validate_linked_flows_exists(flows: "FlowsList") -> None:
@@ -594,7 +632,7 @@ def validate_linked_flows_exists(flows: "FlowsList") -> None:
                     flow.is_rasa_default_flow and step.link == RASA_PATTERN_CHITCHAT
                 )
             ):
-                raise UnresolvedFlowException(step.link, flow.id, step.id)
+                raise UnresolvedLinkFlowException(step.link, flow.id, step.id)
 
 
 def validate_patterns_are_not_called_or_linked(flows: "FlowsList") -> None:

rasa/shared/core/flows/yaml_flows_io.py

@@ -418,15 +418,15 @@ def process_yaml_content(yaml_content: Dict[str, Any]) -> Dict[str, Any]:
 
     # Under the "flows" key certain keys cannot have metadata
     _process_keys_recursively(
-        yaml_content["flows"], ["nlu_trigger", "set_slots", "metadata"]
+        yaml_content["flows"],
+        ["nlu_trigger", "set_slots", "metadata", "mapping", "exit_if"],
     )
 
     return yaml_content
 
 
 def get_flow_as_json(flow: Flow, should_clean_json: bool = False) -> Dict[str, Any]:
-    """
-    Clean the Flow JSON by removing default values and empty fields.
+    """Clean the Flow JSON by removing default values and empty fields.
 
     Args:
         flow: The Flow object to clean.