rasa-pro 3.14.0.dev5__py3-none-any.whl → 3.14.0.dev7__py3-none-any.whl

rasa/agents/validation.py

@@ -0,0 +1,484 @@
+"""Validation functions for agent configurations with reduced redundancies."""
+
+import os
+import urllib.parse
+from collections import Counter
+from typing import Any, Dict, List, NoReturn, Set
+
+from pydantic import ValidationError as PydanticValidationError
+from ruamel import yaml
+
+from rasa.agents.exceptions import (
+    AgentNameFlowConflictException,
+    DuplicatedAgentNameException,
+)
+from rasa.core.available_agents import (
+    DEFAULT_AGENTS_CONFIG_FOLDER,
+    AgentConfig,
+    AgentConfiguration,
+    AgentConnections,
+    AgentInfo,
+    ProtocolConfig,
+)
+from rasa.core.available_endpoints import AvailableEndpoints
+from rasa.exceptions import ValidationError
+
+# Centralized allowed keys configuration to eliminate duplication
+ALLOWED_KEYS = {
+    "agent": {"name", "protocol", "description"},
+    "configuration": {
+        "llm",
+        "prompt_template",
+        "module",
+        "timeout",
+        "max_retries",
+        "agent_card",
+    },
+    "connections": {"mcp_servers"},
+}
+
+
+def validate_agent_names_unique(agents: List[AgentConfig]) -> None:
+    """Validate that agent names are unique across all loaded agents.
+
+    Args:
+        agents: List of agent configurations.
+
+    Raises:
+        DuplicatedAgentNameException: If agent names are not unique.
+    """
+    agent_names = [agent_config.agent.name for agent_config in agents]
+    name_counts = Counter(agent_names)
+
+    duplicated_names = [name for name, count in name_counts.items() if count > 1]
+
+    if duplicated_names:
+        raise DuplicatedAgentNameException(duplicated_names)
+
+
+def validate_agent_names_not_conflicting_with_flows(
+    agents: Dict[str, AgentConfig], flow_names: Set[str]
+) -> None:
+    """Validate that agent names do not conflict with flow names.
+
+    Args:
+        agents: Dictionary of agent configurations.
+        flow_names: Set of flow names to check against.
+
+    Raises:
+        AgentNameFlowConflictException: If agent names conflict with flow names.
+    """
+    conflicting_names = [
+        agent_name for agent_name in agents.keys() if agent_name in flow_names
+    ]
+
+    if conflicting_names:
+        raise AgentNameFlowConflictException(conflicting_names)
+
+
+def _validate_mcp_config(agent_config: AgentConfig) -> None:
+    """Validate MCP-specific configuration requirements."""
+    agent_name = agent_config.agent.name
+
+    # Check connections.mcp_servers exists
+    if agent_config.connections is None or agent_config.connections.mcp_servers is None:
+        raise ValidationError(
+            code="agent.validation.mcp.missing_connections",
+            event_info=f"For protocol 'MCP', agent '{agent_name}' must have "
+            "'connections.mcp_servers' configured.",
+        )
+
+    # Check mcp_servers list is not empty
+    if not agent_config.connections.mcp_servers:
+        raise ValidationError(
+            code="agent.validation.mcp.empty_servers_list",
+            event_info=f"For protocol 'MCP', agent '{agent_name}' must have "
+            "at least one MCP server configured in 'connections.mcp_servers'.",
+        )
+
+    # Validate each MCP server configuration
+    for i, server in enumerate(agent_config.connections.mcp_servers):
+        if not server.name:
+            raise ValidationError(
+                code="agent.validation.mcp.server_missing_name",
+                event_info=f"For protocol 'MCP', agent '{agent_name}' MCP server "
+                f"at index {i} must have a 'name' field.",
+            )
+
+
+def _validate_a2a_config(agent_config: AgentConfig) -> None:
+    """Validate A2A-specific configuration requirements."""
+    agent_name = agent_config.agent.name
+
+    # Check configuration.agent_card exists
+    if (
+        agent_config.configuration is None
+        or agent_config.configuration.agent_card is None
+    ):
+        raise ValidationError(
+            code="agent.validation.a2a.missing_agent_card",
+            event_info=f"For protocol 'A2A', agent '{agent_name}' must have "
+            "'configuration.agent_card' specified.",
+        )
+
+    # Validate agent_card path or URL
+    agent_card = agent_config.configuration.agent_card
+    if not agent_card:
+        raise ValidationError(
+            code="agent.validation.a2a.empty_agent_card",
+            event_info=f"Agent '{agent_name}' has empty 'agent_card' value",
+        )
+
+    # Check if it's a URL
+    parsed_url = urllib.parse.urlparse(agent_card)
+    if parsed_url.scheme and parsed_url.netloc:
+        # It's a URL, validate format
+        if parsed_url.scheme not in ["http", "https"]:
+            raise ValidationError(
+                code="agent.validation.a2a.invalid_agent_card_url",
+                event_info=f"Agent '{agent_name}' has invalid URL scheme "
+                f"'{parsed_url.scheme}' for 'agent_card'",
+            )
+    else:
+        # It's a file path, check if it exists
+        if not os.path.exists(agent_card):
+            raise ValidationError(
+                code="agent.validation.a2a.agent_card_file_not_found",
+                event_info=f"Agent '{agent_name}' has 'agent_card' file that doesn't "
+                f"exist: {agent_card}",
+            )
+
+
+def _validate_optional_keys(agent_config: AgentConfig) -> None:
+    """Validate optional keys in agent configuration."""
+    agent_name = agent_config.agent.name
+
+    # Validate prompt_template if present
+    if agent_config.configuration and agent_config.configuration.prompt_template:
+        prompt_path = agent_config.configuration.prompt_template
+        if not os.path.exists(prompt_path):
+            raise ValidationError(
+                code="agent.validation.optional.prompt_template_not_found",
+                event_info=f"Agent '{agent_name}' has prompt template that "
+                f"does not exist: {prompt_path}",
+            )
+
+    # Validate module if present
+    if agent_config.configuration and agent_config.configuration.module:
+        import importlib
+
+        module_name = agent_config.configuration.module
+        try:
+            module_path, class_name = module_name.rsplit(".", 1)
+            getattr(importlib.import_module(module_path), class_name)
+        except (ImportError, AttributeError) as e:
+            raise ValidationError(
+                code="agent.validation.optional.module_not_found",
+                event_info=f"Agent '{agent_name}' has module '{module_name}' "
+                f"that could not be imported: {e}",
+            )
+
+
+def _validate_llm_references(
+    llm_config: Dict[str, Any],
+    endpoints: "AvailableEndpoints",
+    agent_name: str,
+) -> None:
+    """Validate LLM configuration references against endpoints."""
+    if "model_group" in llm_config:
+        from rasa.engine.validation import (
+            _validate_component_model_client_config_has_references_to_endpoints,
+        )
+
+        component_config = {"llm": llm_config}
+        _validate_component_model_client_config_has_references_to_endpoints(
+            component_config, "llm", component_name=agent_name
+        )
+
+
+def _validate_mcp_server_references(
+    mcp_servers: list, endpoints: "AvailableEndpoints", agent_name: str
+) -> None:
+    """Validate MCP server references against endpoints."""
+    if not endpoints.mcp_servers:
+        raise ValidationError(
+            code="agent.validation.endpoints.no_mcp_servers",
+            event_info=(
+                f"Agent '{agent_name}' references MCP servers but no MCP "
+                "servers are defined in endpoints.yml."
+            ),
+        )
+
+    available_mcp_server_names = [server.name for server in endpoints.mcp_servers]
+
+    for i, mcp_server in enumerate(mcp_servers):
+        server_name = mcp_server.name
+        if server_name not in available_mcp_server_names:
+            raise ValidationError(
+                code="agent.validation.endpoints.invalid_mcp_server",
+                event_info=(
+                    f"MCP server '{server_name}' at index {i} for Agent "
+                    f"'{agent_name}' does not exist in endpoints.yml. Available MCP "
+                    f"servers: {', '.join(available_mcp_server_names)}"
+                ),
+            )
+
+
+def _handle_pydantic_validation_error(
+    error: PydanticValidationError, agent_name: str
+) -> NoReturn:
+    """Handle specific Pydantic validation errors that are actually possible.
+
+    Args:
+        error: The Pydantic validation error to handle
+        agent_name: Name of the agent for error messages
+    """
+    missing_fields = []
+    invalid_protocol = False
+    type_error = None
+
+    for pydantic_error in error.errors():
+        error_type = pydantic_error["type"]
+        field_path = ".".join(str(loc) for loc in pydantic_error["loc"])
+
+        if error_type == "missing":
+            for field in ["name", "protocol", "description"]:
+                if field in field_path:
+                    missing_fields.append(field)
+        elif error_type == "enum" and "protocol" in field_path:
+            invalid_protocol = True
+        elif error_type in ["string_type", "int_parsing"]:
+            type_error = (field_path, pydantic_error["msg"])
+
+    # Handle missing required fields
+    if missing_fields:
+        raise ValidationError(
+            code="agent.validation.mandatory.fields_missing",
+            event_info=(
+                f"Agent '{agent_name}' is missing required fields "
+                f"in agent section: {', '.join(missing_fields)}"
+            ),
+        )
+
+    # Handle invalid protocol
+    elif invalid_protocol:
+        raise ValidationError(
+            code="agent.validation.pydantic.invalid_protocol",
+            event_info=(
+                f"Agent '{agent_name}' has invalid protocol value. "
+                "Supported protocols: MCP, A2A"
+            ),
+        )
+
+    # Handle type errors
+    elif type_error:
+        field, msg = type_error
+        raise ValidationError(
+            code="agent.validation.pydantic.type_error",
+            event_info=(
+                f"Agent '{agent_name}' has invalid type for field " f"'{field}': {msg}"
+            ),
+        )
+
+    # Handle other Pydantic validation errors
+    else:
+        raise ValidationError(
+            code="agent.validation.pydantic.failed",
+            event_info=f"Agent '{agent_name}' validation failed: {error}",
+        )
+
+
+def _validate_endpoint_references(agent_config: AgentConfig) -> None:
+    """Validate that LLM and MCP server references in agent config are valid."""
+    agent_name = agent_config.agent.name
+
+    # Get available endpoints
+    endpoints = AvailableEndpoints.get_instance()
+
+    # Validate LLM configuration references
+    if agent_config.configuration and agent_config.configuration.llm:
+        _validate_llm_references(agent_config.configuration.llm, endpoints, agent_name)
+
+    # Validate MCP server references
+    if agent_config.connections and agent_config.connections.mcp_servers:
+        _validate_mcp_server_references(
+            agent_config.connections.mcp_servers, endpoints, agent_name
+        )
+
+
+def _validate_section_keys(
+    data: Dict[str, Any], section: str, allowed_keys: set
+) -> None:
+    """Generic function to validate keys in a specific section."""
+    if section not in data:
+        return
+
+    section_data = data[section]
+    if not isinstance(section_data, dict):
+        return
+
+    additional_keys = set(section_data.keys()) - allowed_keys
+    if additional_keys:
+        agent_name = data.get("agent", {}).get("name", "unknown")
+        raise ValidationError(
+            code=f"agent.validation.structure.additional_{section}_keys",
+            event_info=(
+                f"Agent '{agent_name}' contains additional keys in "
+                f"'{section}' section: {', '.join(sorted(additional_keys))}"
+            ),
+        )
+
+
+def _validate_mandatory_fields(data: Dict[str, Any], agent_name: str) -> None:
+    """Validate that all mandatory fields are present in the agent section."""
+    if "agent" not in data:
+        raise ValidationError(
+            code="agent.validation.mandatory.agent_section_missing",
+            event_info=f"Agent '{agent_name}' is missing 'agent' section",
+        )
+
+    agent_data = data["agent"]
+    if not isinstance(agent_data, dict):
+        raise ValidationError(
+            code="agent.validation.mandatory.agent_section_invalid",
+            event_info=(
+                f"Agent '{agent_name}' has invalid 'agent' section - "
+                "must be a dictionary"
+            ),
+        )
+
+    # Check for required fields
+    missing_fields = []
+    for field in ["name", "protocol", "description"]:
+        if field not in agent_data or not agent_data[field]:
+            missing_fields.append(field)
+
+    if missing_fields:
+        raise ValidationError(
+            code="agent.validation.mandatory.fields_missing",
+            event_info=(
+                f"Agent '{agent_name}' is missing required fields in agent section: "
+                f"{', '.join(missing_fields)}"
+            ),
+        )
+
+
+def _validate_no_additional_keys_raw_data(data: Dict[str, Any]) -> None:
+    """Validate that no additional, unexpected keys are present in the raw data."""
+    # Use the generic validation function for each section
+    _validate_section_keys(data, "agent", ALLOWED_KEYS["agent"])
+    _validate_section_keys(data, "configuration", ALLOWED_KEYS["configuration"])
+    _validate_section_keys(data, "connections", ALLOWED_KEYS["connections"])
+
+
+def _validate_folder_structure(agent_folder: str) -> None:
+    """Validate agent folder structure."""
+    if not os.path.exists(agent_folder):
+        raise ValidationError(
+            code="agent.validation.folder.not_found",
+            event_info=f"Agent folder does not exist: {agent_folder}",
+        )
+
+    if not os.path.isdir(agent_folder):
+        raise ValidationError(
+            code="agent.validation.folder.not_directory",
+            event_info=f"Agent folder is not a directory: {agent_folder}",
+        )
+
+
+def _validate_config_file_exists(config_path: str, agent_name: str) -> None:
+    """Validate config.yml file exists."""
+    if not os.path.isfile(config_path):
+        raise ValidationError(
+            code="agent.validation.folder.missing_config",
+            event_info=f"Agent '{agent_name}' is missing 'config.yml' file",
+        )
+
+
+def validate_agent_config(agent_config: AgentConfig) -> None:
+    """Validate an agent configuration using all applicable validators."""
+    protocol = agent_config.agent.protocol
+
+    # Run protocol-specific validation
+    if protocol == ProtocolConfig.MCP:
+        _validate_mcp_config(agent_config)
+    elif protocol == ProtocolConfig.A2A:
+        _validate_a2a_config(agent_config)
+
+    # Run optional keys validation
+    _validate_optional_keys(agent_config)
+
+    # Run endpoint references validation
+    _validate_endpoint_references(agent_config)
+
+
+def validate_agent_folder(agent_folder: str = DEFAULT_AGENTS_CONFIG_FOLDER) -> None:
+    """Validate all agent configurations in a folder."""
+    # Validate folder structure
+    _validate_folder_structure(agent_folder)
+
+    # Scan for agent folders
+    for agent_folder_name in os.listdir(agent_folder):
+        agent_path = os.path.join(agent_folder, agent_folder_name)
+
+        if not os.path.isdir(agent_path):
+            continue
+
+        config_path = os.path.join(agent_path, "config.yml")
+
+        # Validate config file exists
+        _validate_config_file_exists(config_path, agent_folder_name)
+
+        # Read and validate the config content
+        try:
+            # First read the raw YAML data to validate structure
+            with open(config_path, "r") as f:
+                data = yaml.safe_load(f)
+
+            # Validate no additional keys
+            _validate_no_additional_keys_raw_data(data)
+
+            # Validate mandatory fields before creating Pydantic models
+            _validate_mandatory_fields(data, agent_folder_name)
+
+            # Create the agent config using AvailableAgents
+            from rasa.core.available_agents import AvailableAgents
+
+            agent_config = AvailableAgents._read_agent_config(config_path)
+
+            # Validate the agent config (protocol-specific and endpoint references)
+            validate_agent_config(agent_config)
+        except PydanticValidationError as e:
+            _handle_pydantic_validation_error(e, agent_folder_name)
+        except Exception as e:
+            # Handle non-Pydantic exceptions
+            raise ValidationError(
+                code="agent.validation.folder.config_validation_failed",
+                event_info=f"Agent '{agent_folder_name}' validation failed: {e}",
+            )
+
+
+def validate_agent_config_data(data: Dict[str, Any]) -> "AgentConfig":
+    """Validate agent configuration data."""
+    try:
+        # Validate no additional keys before creating Pydantic models
+        _validate_no_additional_keys_raw_data(data)
+
+        # Create the agent config (this will trigger Pydantic validation)
+        agent_config = AgentConfig(
+            agent=AgentInfo(**data.get("agent", {})),
+            configuration=AgentConfiguration(**data.get("configuration", {}))
+            if data.get("configuration")
+            else None,
+            connections=AgentConnections(**data.get("connections", {}))
+            if data.get("connections")
+            else None,
+        )
+
+        return agent_config
+
+    except PydanticValidationError as e:
+        _handle_pydantic_validation_error(e, "Agent configuration")
+    except Exception:
+        # Re-raise other exceptions
+        raise

rasa/api.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
 def run(
     model: Text,
     endpoints: Text,
+    sub_agents: Text,
     connector: Optional[Text] = None,
     credentials: Optional[Text] = None,
     **kwargs: Dict[Text, Any],
@@ -29,6 +30,7 @@ def run(
     Args:
         model: Path to model archive.
         endpoints: Path to endpoints file.
+        sub_agents: Path to sub-agents directory.
         connector: Connector which should be use (overwrites `credentials`
         field).
         credentials: Path to channel credentials file.
@@ -38,11 +40,13 @@ def run(
     """
     import rasa.core.run
     import rasa.shared.utils.common
+    from rasa.core.available_agents import AvailableAgents
     from rasa.core.available_endpoints import AvailableEndpoints
     from rasa.shared.constants import DOCS_BASE_URL
     from rasa.shared.utils.cli import print_warning
 
     _endpoints = AvailableEndpoints.get_instance(endpoints)
+    _sub_agents = AvailableAgents.get_instance(sub_agents)
 
     if not connector and not credentials:
         connector = "rest"
@@ -61,27 +65,29 @@ def run(
         channel=connector,
         credentials=credentials,
         endpoints=_endpoints,
+        sub_agents=_sub_agents,
         **kwargs,
     )
 
 
 def train(
-    domain: Text,
-    config: Text,
-    training_files: "Union[Text, List[Text]]",
-    output: Text = rasa.shared.constants.DEFAULT_MODELS_PATH,
+    domain: str,
+    config: str,
+    training_files: "Union[str, List[str]]",
+    output: str = rasa.shared.constants.DEFAULT_MODELS_PATH,
     dry_run: bool = False,
     force_training: bool = False,
-    fixed_model_name: Optional[Text] = None,
+    fixed_model_name: Optional[str] = None,
     persist_nlu_training_data: bool = False,
     core_additional_arguments: Optional[Dict] = None,
     nlu_additional_arguments: Optional[Dict] = None,
-    model_to_finetune: Optional[Text] = None,
+    model_to_finetune: Optional[str] = None,
     finetuning_epoch_fraction: float = 1.0,
     remote_storage: Optional[StorageType] = None,
     file_importer: Optional["TrainingDataImporter"] = None,
     keep_local_model_copy: bool = False,
     remote_root_only: bool = False,
+    sub_agents: Optional[str] = None,
 ) -> "TrainingResult":
     """Runs Rasa Core and NLU training in `async` loop.
 
@@ -111,6 +117,7 @@ def train(
             remote storage is configured.
         remote_root_only: If `True`, the model will be stored in the root of the
             remote model storage.
+        sub_agents: Path to sub-agents directory.
 
     Returns:
         An instance of `TrainingResult`.
@@ -135,6 +142,7 @@ def train(
             file_importer=file_importer,
             keep_local_model_copy=keep_local_model_copy,
             remote_root_only=remote_root_only,
+            sub_agents=sub_agents,
         )
     )
 

rasa/cli/arguments/default_arguments.py

@@ -3,6 +3,7 @@ import logging
 from enum import Enum
 from typing import List, Optional, Text, Union
 
+from rasa.core.constants import DEFAULT_SUB_AGENTS
 from rasa.core.persistor import RemoteStorageType, StorageType, parse_remote_storage
 from rasa.shared.constants import (
     DEFAULT_CONFIG_PATH,
@@ -217,3 +218,14 @@ def add_skip_validation_flag(
         action="append",
         help="Skip YAML validation for selected parts of the training data.",
     )
+
+
+def add_sub_agents_param(
+    parser: Union[argparse.ArgumentParser, argparse._ActionsContainer],
+) -> None:
+    parser.add_argument(
+        "--sub-agents",
+        type=str,
+        default=DEFAULT_SUB_AGENTS,
+        help="Directory that specifies sub-agents to use (default: %(default)s).",
+    )

rasa/cli/arguments/run.py

@@ -7,6 +7,7 @@ from rasa.cli.arguments.default_arguments import (
     add_model_param,
     add_remote_storage_param,
     add_skip_validation_flag,
+    add_sub_agents_param,
 )
 from rasa.core import constants
 from rasa.env import (
@@ -24,6 +25,7 @@ def set_run_arguments(parser: argparse.ArgumentParser) -> None:
     add_server_arguments(parser)
     add_inspect_argument(parser)
     add_skip_validation_flag(parser)
+    add_sub_agents_param(parser)
 
 
 def set_run_action_arguments(parser: argparse.ArgumentParser) -> None:

rasa/cli/arguments/train.py

@@ -10,6 +10,7 @@ from rasa.cli.arguments.default_arguments import (
     add_remote_root_only_param,
     add_remote_storage_param,
     add_stories_param,
+    add_sub_agents_param,
 )
 from rasa.graph_components.providers.training_tracker_provider import (
     TrainingTrackerProvider,
@@ -43,6 +44,7 @@ def set_train_arguments(parser: argparse.ArgumentParser) -> None:
     )
     add_remote_storage_param(parser)
     add_remote_root_only_param(parser)
+    add_sub_agents_param(parser)
 
 
 def set_train_core_arguments(parser: argparse.ArgumentParser) -> None:

rasa/cli/dialogue_understanding_test.py

@@ -14,6 +14,7 @@ from rasa.cli.arguments.default_arguments import (
     add_endpoint_param,
     add_model_param,
     add_remote_storage_param,
+    add_sub_agents_param,
 )
 from rasa.core.agent import Agent
 from rasa.core.available_endpoints import AvailableEndpoints
@@ -174,6 +175,8 @@ def add_du_test_arguments(parser: argparse.ArgumentParser) -> None:
         ),
     )
 
+    add_sub_agents_param(du_arguments)
+
 
 def ensure_calm_only_bot(agent: Agent) -> None:
     if agent.domain is None or agent.processor is None:
@@ -218,6 +221,7 @@ def execute_dialogue_understanding_tests(args: argparse.Namespace) -> None:
             model_path=args.model,
             model_server=endpoints.model,
             remote_storage=args.remote_storage,
+            sub_agents_path=args.sub_agents,
         )
     except AgentNotReady as error:
         structlogger.error(

rasa/cli/e2e_test.py

@@ -17,6 +17,7 @@ from rasa.cli.arguments.default_arguments import (
     add_endpoint_param,
     add_model_param,
     add_remote_storage_param,
+    add_sub_agents_param,
 )
 from rasa.core.available_endpoints import AvailableEndpoints
 from rasa.core.exceptions import AgentNotReady
@@ -147,6 +148,8 @@ def add_e2e_test_arguments(parser: argparse.ArgumentParser) -> None:
         help="Directory where to save coverage report to.",
     )
 
+    add_sub_agents_param(parser)
+
 
 def execute_e2e_tests(args: argparse.Namespace) -> None:
     """Run the end-to-end tests.
@@ -192,6 +195,7 @@ def execute_e2e_tests(args: argparse.Namespace) -> None:
             model_server=endpoints.model,
             endpoints=endpoints,
             test_case_path=Path(test_case_path),
+            sub_agents_path=args.sub_agents,
         )
     except AgentNotReady as error:
         structlogger.error(

rasa/cli/inspect.py

@@ -8,6 +8,7 @@ from sanic import Sanic
 from rasa import telemetry
 from rasa.cli import SubParsersAction
 from rasa.cli.arguments import shell as arguments
+from rasa.cli.arguments.default_arguments import add_sub_agents_param
 from rasa.core import constants
 from rasa.core.available_endpoints import AvailableEndpoints
 from rasa.engine.storage.local_model_storage import LocalModelStorage
@@ -44,6 +45,8 @@ def add_subparser(
         "--voice", help="Enable voice", action="store_true", default=False
     )
 
+    add_sub_agents_param(inspect_parser)
+
     # it'd be confusing to expose those arguments to the user,
     # so we remove them
     remove_argument_from_parser(inspect_parser, "--credentials")