rasa-pro 3.14.0.dev20250922__py3-none-any.whl → 3.14.0rc2__py3-none-any.whl

rasa/agents/schemas/agent_tool_schema.py

@@ -0,0 +1,186 @@
+from typing import Any, Callable, Dict, Optional
+
+from mcp import Tool
+from pydantic import BaseModel
+
+from rasa.agents.constants import (
+    TOOL_ADDITIONAL_PROPERTIES_KEY,
+    TOOL_DESCRIPTION_KEY,
+    TOOL_EXECUTOR_KEY,
+    TOOL_INPUT_SCHEMA_KEY,
+    TOOL_NAME_KEY,
+    TOOL_PARAMETERS_KEY,
+    TOOL_PROPERTIES_KEY,
+    TOOL_PROPERTY_TYPE_KEY,
+    TOOL_REQUIRED_KEY,
+    TOOL_STRICT_KEY,
+    TOOL_TYPE_FUNCTION_KEY,
+    TOOL_TYPE_KEY,
+)
+
+
+class AgentToolSchema(BaseModel):
+    name: str
+    parameters: dict[str, Any]
+    strict: bool
+    description: Optional[str] = None
+    type: str = "function"
+
+    @classmethod
+    def from_mcp_tool(cls, tool: Tool) -> "AgentToolSchema":
+        """Convert MCP Tool to AgentToolSchema."""
+        parameters = tool.inputSchema.copy() if tool.inputSchema else {}
+
+        if parameters:
+            cls._validate_and_fix_parameters(parameters)
+
+        return cls(
+            name=tool.name,
+            description=tool.description,
+            parameters=parameters,
+            strict=False,
+            type=TOOL_TYPE_FUNCTION_KEY,
+        )
+
+    @classmethod
+    def from_litellm_json_format(cls, tool: Dict[str, Any]) -> "AgentToolSchema":
+        """Convert OpenAI dict format to AgentToolSchema."""
+        references = (
+            "Refer: \n"
+            "- LiteLLM JSON Format - https://docs.litellm.ai/docs/completion/function_call#full-code---parallel-function-calling-with-gpt-35-turbo-1106\n"
+            "- OpenAI Tool JSON Format - https://platform.openai.com/docs/guides/tools?tool-type=function-calling\n"
+        )
+        expected_structure = (
+            "{\n"
+            "    'type': 'function',\n"
+            "    'function': {\n"
+            "        'name': 'string',\n"
+            "        'description': 'string',\n"
+            "        'parameters': {\n"
+            "            'type': 'object',\n"
+            "            'properties': {'string': 'string'},\n"
+            "            'required': ['string']\n"
+            "        }\n"
+            "    }\n"
+            "}"
+        )
+        if (
+            TOOL_NAME_KEY in tool
+            and TOOL_DESCRIPTION_KEY in tool
+            and TOOL_INPUT_SCHEMA_KEY in tool
+        ):
+            raise ValueError(
+                "Anthropic Tool format is not supported yet. Please use the LiteLLM "
+                "Tool format, which is based on OpenAI's format.\n"
+                "The expected structure is:\n"
+                f"{expected_structure}\n"
+                f"{references}"
+            )
+        if not (TOOL_TYPE_FUNCTION_KEY in tool and TOOL_TYPE_KEY in tool):
+            raise ValueError(
+                "Invalid tool format. Expected a dictionary with 'type' and "
+                "'function' keys. Expected LiteLLM Tool format that is based on OpenAI "
+                "format which has the following structure: \n"
+                f"{expected_structure}\n"
+                f"{references}"
+            )
+
+        function_data = tool[TOOL_TYPE_FUNCTION_KEY]
+
+        if not (
+            TOOL_NAME_KEY in function_data and TOOL_DESCRIPTION_KEY in function_data
+        ):
+            raise ValueError(
+                "Invalid tool format. 'function' must contain 'name' and "
+                "'description' keys. Expected LiteLLM Tool format that is based on "
+                "OpenAI format which has the following structure: \n"
+                f"{expected_structure}\n"
+                f"{references}"
+            )
+        parameters = function_data.get(TOOL_PARAMETERS_KEY, {})
+
+        if parameters:
+            cls._validate_and_fix_parameters(parameters)
+
+        return cls(
+            name=function_data[TOOL_NAME_KEY],
+            description=function_data[TOOL_DESCRIPTION_KEY],
+            parameters=parameters,
+            strict=function_data.get(TOOL_STRICT_KEY, False),
+            type=tool[TOOL_TYPE_KEY],
+        )
+
+    @staticmethod
+    def _validate_and_fix_parameters(parameters: Dict[str, Any]) -> None:
+        """Validate and fix parameters to ensure they meet OpenAI function calling
+        requirements."""
+        if not parameters:
+            return
+
+        # Ensure additionalProperties is set at the top level
+        if TOOL_ADDITIONAL_PROPERTIES_KEY not in parameters:
+            parameters[TOOL_ADDITIONAL_PROPERTIES_KEY] = False
+
+        # Ensure required is set at the top level
+        if TOOL_REQUIRED_KEY not in parameters:
+            parameters[TOOL_REQUIRED_KEY] = []
+
+        # Ensure all properties have types, required field and additionalProperties
+        if TOOL_PROPERTIES_KEY in parameters:
+            AgentToolSchema._ensure_property_types(parameters)
+
+    @staticmethod
+    def _ensure_property_types(parameters: Dict[str, Any]) -> None:
+        """Ensure all properties in parameters have a type defined and
+        additionalProperties is set."""
+        properties = parameters[TOOL_PROPERTIES_KEY]
+
+        if not properties:
+            return
+
+        for _, prop_schema in properties.items():
+            if not isinstance(prop_schema, dict):
+                continue
+
+            # Ensure the property has a type
+            if TOOL_PROPERTY_TYPE_KEY not in prop_schema:
+                prop_schema[TOOL_PROPERTY_TYPE_KEY] = "string"
+
+            # If it's an object type, ensure additionalProperties and required
+            # fields are set
+            if prop_schema[TOOL_PROPERTY_TYPE_KEY] == "object":
+                if TOOL_ADDITIONAL_PROPERTIES_KEY not in prop_schema:
+                    prop_schema[TOOL_ADDITIONAL_PROPERTIES_KEY] = False
+
+                # Ensure required key exists for object properties
+                if TOOL_REQUIRED_KEY not in prop_schema:
+                    prop_schema[TOOL_REQUIRED_KEY] = []
+
+    def to_litellm_json_format(self) -> Dict[str, Any]:
+        """Convert AgentToolSchema to OpenAI format."""
+        # Ensure the schema is valid before conversion
+        return {
+            TOOL_TYPE_KEY: TOOL_TYPE_FUNCTION_KEY,
+            TOOL_TYPE_FUNCTION_KEY: self.model_dump(exclude={TOOL_TYPE_KEY}),
+        }
+
+
+class CustomToolSchema(BaseModel):
+    """A class that represents the schema of a custom agent tool."""
+
+    tool_name: str
+    tool_definition: AgentToolSchema
+    tool_executor: Callable
+
+    @classmethod
+    def from_dict(cls, config: Dict[str, Any]) -> "CustomToolSchema":
+        """Convert a custom tool config to CustomToolSchema."""
+        agent_tool_schema = AgentToolSchema.from_litellm_json_format(config)
+        if TOOL_EXECUTOR_KEY not in config:
+            raise ValueError("Custom tool executor is required.")
+
+        return cls(
+            tool_name=agent_tool_schema.name,
+            tool_definition=agent_tool_schema,
+            tool_executor=config[TOOL_EXECUTOR_KEY],
+        )

rasa/agents/templates/mcp_open_agent_prompt_template.jinja2

@@ -0,0 +1,20 @@
+You are a helpful assistant that should assist the user in the best possible way.
+
+### Primary Task
+{{ description }}
+
+### Instructions
+* Always make sure to output responses to the user in a clear, helpful format.
+* Always avoid asking multiple questions at once. Ask questions sequentially one at a time and wait for the user's response before proceeding to next question.
+* Always avoid making assumptions about what values to pass into tools. Ask for clarification if a user's request is ambiguous.
+* Once your primary task, described above, is completed, you must call the `task_completed` tool to signal that you have finished assisting the user. Do not end the conversation or indicate completion without the `task_completed` tool call.
+* Do NOT call the `task_completed` tool unless you're absolutely certain that your primary task (NOT the slot corrections, updates, etc), described above, is fully completed. Focus on the task given in the task description above.
+* Strictly avoid making up information or ability to take some action which is not available in `tool` provided.
+
+### Context
+- Current date: {{ current_date }}   (YYYY-MM-DD)
+- Current time: {{ current_time }}   (HH:MM:SS, 24-hour format)
+- Current day: {{ current_day }}     (Day of week)
+
+### Conversation history
+{{ conversation_history }}

rasa/agents/templates/mcp_task_agent_prompt_template.jinja2

@@ -0,0 +1,22 @@
+You are a helpful assistant that should assist the user in the best possible way.
+
+### Description of your capabilities
+{{ description }}
+
+### Task
+* Use the tools available to gather the required information to set the following slots: {{ slot_names }}.
+* In order to set the slot values, use the `set_slot_<slot_name>` tool.
+
+### Instructions
+* Always make sure to output responses to the user in a clear, helpful format.
+* Always avoid asking multiple questions at once. Ask questions sequentially one at a time and wait for the user's response before proceeding to next question.
+* Always avoid making assumptions about what values to pass into tools. Ask for clarification if a user's request is ambiguous.
+* Strictly avoid making up information or ability to take some action which is not available in `tool` provided.
+
+### Context
+- Current date: {{ current_date }}   (YYYY-MM-DD)
+- Current time: {{ current_time }}   (HH:MM:SS, 24-hour format)
+- Current day: {{ current_day }}     (Day of week)
+
+### Conversation history
+{{ conversation_history }}

rasa/agents/utils.py

@@ -0,0 +1,206 @@
+from typing import Dict, List, Optional
+
+import structlog
+
+from rasa.agents.agent_manager import AgentManager
+from rasa.agents.exceptions import AgentNotFoundException
+from rasa.agents.validation import validate_agent_names_not_conflicting_with_flows
+from rasa.core.available_agents import (
+    AgentConfig,
+    AgentMCPServerConfig,
+    AvailableAgents,
+)
+from rasa.core.config.available_endpoints import AvailableEndpoints
+from rasa.core.config.configuration import Configuration
+from rasa.shared.agents.utils import get_protocol_type
+from rasa.shared.core.events import AgentCompleted, AgentStarted
+from rasa.shared.core.flows import FlowsList
+from rasa.shared.core.flows.steps import CallFlowStep
+from rasa.shared.core.trackers import DialogueStateTracker
+
+structlogger = structlog.get_logger()
+
+
+def resolve_agent_config(
+    agent_config: AgentConfig,
+    available_endpoints: AvailableEndpoints,
+) -> Optional[AgentConfig]:
+    if agent_config is None:
+        return None
+
+    connections = agent_config.connections
+    mcp_connections: List[AgentMCPServerConfig] = (
+        connections.mcp_servers
+        if connections and connections.mcp_servers is not None
+        else []
+    )
+
+    for mcp_server in mcp_connections:
+        for mcp_server_endpoint in available_endpoints.mcp_servers or []:
+            if mcp_server_endpoint.name == mcp_server.name:
+                mcp_server.url = mcp_server_endpoint.url
+                mcp_server.type = mcp_server_endpoint.type
+                mcp_server.additional_params = mcp_server_endpoint.additional_params
+
+    return agent_config
+
+
+async def initialize_agents(
+    flows: FlowsList,
+    sub_agents: AvailableAgents,
+) -> None:
+    """Iterate over flows and create/connect the referenced agents."""
+    agent_manager: AgentManager = AgentManager()
+    endpoints = Configuration.get_instance().endpoints
+
+    agent_used = False
+    mcp_tool_used = False
+
+    # Validate agent names don't conflict with flow names
+    flow_names = {flow.id for flow in flows.underlying_flows}
+    validate_agent_names_not_conflicting_with_flows(sub_agents.agents, flow_names)
+
+    for flow in flows.underlying_flows:
+        for step in flow.steps:
+            if isinstance(step, CallFlowStep):
+                if flows.flow_by_id(step.call) is not None:
+                    continue
+
+                if step.is_calling_mcp_tool():
+                    # The call step is calling an MCP tool, so we don't need to
+                    # initialize any agent.
+                    mcp_tool_used = True
+                    continue
+
+                if not step.is_calling_agent():
+                    raise AgentNotFoundException(step.call)
+
+                agent_used = True
+
+                agent_name = step.call
+                agent_config = sub_agents.get_agent_config(agent_name)
+                resolved_agent_config = resolve_agent_config(agent_config, endpoints)
+                protocol_type = get_protocol_type(step, agent_config)
+
+                await agent_manager.connect_agent(
+                    agent_name,
+                    protocol_type,
+                    resolved_agent_config,
+                )
+
+    _log_beta_feature_warning(mcp_tool_used, agent_used)
+
+
+def _log_beta_feature_warning(mcp_tool_used: bool, agent_used: bool) -> None:
+    """Log a warning if an agent or MCP tool is used in the flow(s)."""
+    if mcp_tool_used:
+        structlogger.info(
+            "rasa.agents.utils.initialize_agents",
+            event_info="Beta Feature",
+            message=(
+                "An MCP tool is being called in at least one of the flows. "
+                "This feature is currently under beta development. "
+                "It might undergo upgrades / breaking changes in future "
+                "releases to graduate it to GA."
+            ),
+        )
+
+    if agent_used:
+        structlogger.info(
+            "rasa.agents.utils.initialize_agents",
+            event_info="Beta Feature",
+            message=(
+                "A sub-agent is being called from a flow. "
+                "This feature is currently under beta development. "
+                "It might undergo upgrades / breaking changes in future "
+                "releases to graduate it to GA."
+            ),
+        )
+
+
+def is_agent_valid(agent_id: str) -> bool:
+    """Check if an agent ID references a valid agent.
+
+    Args:
+        agent_id: The agent ID to validate.
+
+    Returns:
+        True if the agent exists, False otherwise.
+    """
+    agent_config = AvailableAgents.get_agent_config(agent_id)
+    return agent_config is not None
+
+
+def is_agent_completed(tracker: DialogueStateTracker, agent_id: str) -> bool:
+    """Check if an agent has been completed.
+
+    Args:
+        tracker: The dialogue state tracker.
+        agent_id: The agent ID to check.
+
+    Returns:
+        True if the agent has been completed, False otherwise.
+    """
+    # Look for AgentCompleted events for this agent
+    for event in reversed(tracker.events):
+        if isinstance(event, AgentCompleted) and event.agent_id == agent_id:
+            return True
+        elif isinstance(event, AgentStarted) and event.agent_id == agent_id:
+            return False
+    return False
+
+
+def get_agent_info(agent_id: str) -> Optional[Dict[str, str]]:
+    """Get basic agent information (name and description).
+
+    Args:
+        agent_id: The agent ID to get information for.
+
+    Returns:
+        Dictionary with agent name and description if found, None otherwise.
+    """
+    agent_config = AvailableAgents.get_agent_config(agent_id)
+    if agent_config is None:
+        return None
+
+    return {
+        "name": agent_config.agent.name,
+        "description": agent_config.agent.description,
+    }
+
+
+def get_completed_agents_info(tracker: DialogueStateTracker) -> List[Dict[str, str]]:
+    """Get information for all completed agents.
+
+    Args:
+        tracker: The dialogue state tracker.
+
+    Returns:
+        List of dictionaries containing agent information for completed agents.
+    """
+    completed_agents = []
+    for event in reversed(tracker.events):
+        if isinstance(event, AgentCompleted):
+            agent_info = get_agent_info(event.agent_id)
+            if agent_info:
+                completed_agents.append(agent_info)
+    return completed_agents
+
+
+def get_active_agent_info(
+    tracker: DialogueStateTracker, flow_id: str
+) -> Optional[Dict[str, str]]:
+    """Get information for the active agent in a specific flow.
+
+    Args:
+        tracker: The dialogue state tracker.
+        flow_id: The flow ID to get the active agent for.
+
+    Returns:
+        Dictionary with agent name and description if an agent is active,
+        None otherwise.
+    """
+    agent_frame = tracker.stack.find_active_agent_stack_frame_for_flow(flow_id)
+    if agent_frame:
+        return get_agent_info(agent_frame.agent_id)
+    return None