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

rasa/agents/agent_factory.py

@@ -0,0 +1,122 @@
+from typing import Any, ClassVar, Dict, List, Type
+
+import structlog
+
+from rasa.agents.core.agent_protocol import AgentProtocol
+from rasa.agents.core.types import ProtocolType
+from rasa.agents.protocol import A2AAgent, MCPOpenAgent, MCPTaskAgent
+from rasa.core.available_agents import AgentConfig
+from rasa.shared.utils.common import class_from_module_path
+
+structlogger = structlog.get_logger()
+
+
+class AgentFactory:
+    """Factory for creating agent instances based on the protocol type."""
+
+    _protocols: ClassVar[Dict[ProtocolType, Type[AgentProtocol]]] = {
+        ProtocolType.A2A: A2AAgent,
+        ProtocolType.MCP_OPEN: MCPOpenAgent,
+        ProtocolType.MCP_TASK: MCPTaskAgent,
+    }
+
+    @classmethod
+    def create_client(
+        cls, protocol_type: ProtocolType, config: AgentConfig
+    ) -> AgentProtocol:
+        """Create an agent instance based on the protocol type.
+
+        Args:
+            protocol_type: The protocol type of the agent.
+            config: The configuration for the agent as an AgentConfig object.
+
+        Returns:
+            An instance of the agent.
+        """
+        # If the agent is a custom agent, we need to create it from the module
+        if config.configuration and config.configuration.module:
+            agent_class: Type[AgentProtocol] = class_from_module_path(
+                config.configuration.module
+            )
+            if not cls._is_valid_custom_agent(agent_class, protocol_type):
+                raise ValueError(
+                    f"Agent class {agent_class} does not subclass the "
+                    f"{cls._get_agent_class_from_protocol(protocol_type).__name__} "
+                    f"agent class."
+                )
+            structlogger.debug(
+                "agent_factory.create_client.custom_agent",
+                event_info=(
+                    f"Initializing `{agent_class.__name__}` for agent "
+                    f"`{config.agent.name}` with protocol `{protocol_type.value}`"
+                ),
+                agent_name=config.agent.name,
+                protocol_type=protocol_type.value,
+                agent_class=agent_class.__name__,
+            )
+            return agent_class.from_config(config)
+
+        # If the agent is a built-in agent, we need to create it from the protocol class
+        protocol_class = cls._get_agent_class_from_protocol(protocol_type)
+        if protocol_class is None:
+            raise ValueError(
+                f"Unsupported protocol: {protocol_type}. "
+                f"Supported protocols: {cls.get_supported_protocols()}"
+            )
+
+        structlogger.debug(
+            "agent_factory.create_client",
+            event_info=(
+                f"Initializing `{protocol_class.__name__}` for agent "
+                f"`{config.agent.name}` with protocol `{protocol_type.value}`"
+            ),
+            agent_name=config.agent.name,
+            protocol_type=protocol_type.value,
+            agent_class=protocol_class.__name__,
+        )
+        return protocol_class.from_config(config)
+
+    @classmethod
+    def register_protocol(
+        cls, protocol_type: ProtocolType, protocol_class: Type[AgentProtocol]
+    ) -> None:
+        """Register new protocol implementation.
+
+        Args:
+            protocol_type: The protocol type of the agent.
+            protocol_class: The class that implements the protocol.
+        """
+        if cls.is_protocol_supported(protocol_type):
+            raise ValueError(f"Protocol {protocol_type} already registered.")
+        cls._protocols[protocol_type] = protocol_class
+
+    @classmethod
+    def get_supported_protocols(cls) -> List[ProtocolType]:
+        """Get all supported protocol types."""
+        return list(cls._protocols.keys())
+
+    @classmethod
+    def _get_agent_class_from_protocol(
+        cls, protocol_type: ProtocolType
+    ) -> Type[AgentProtocol]:
+        """Get the class that implements the protocol."""
+        if not cls.is_protocol_supported(protocol_type):
+            raise ValueError(
+                f"Unsupported protocol: {protocol_type}. "
+                f"Supported protocols: {cls.get_supported_protocols()}"
+            )
+        return cls._protocols[protocol_type]
+
+    @classmethod
+    def is_protocol_supported(cls, protocol_type: ProtocolType) -> bool:
+        """Check if the protocol is supported."""
+        return protocol_type in cls._protocols
+
+    @classmethod
+    def _is_valid_custom_agent(
+        cls, agent_class: Any, protocol_type: ProtocolType
+    ) -> bool:
+        """Check if the agent class is valid."""
+        return issubclass(
+            agent_class, cls._get_agent_class_from_protocol(protocol_type)
+        )

rasa/agents/agent_manager.py

@@ -0,0 +1,163 @@
+from typing import ClassVar, Dict
+
+import structlog
+
+from rasa.agents.agent_factory import AgentFactory
+from rasa.agents.core.agent_protocol import AgentProtocol
+from rasa.agents.core.types import AgentIdentifier, ProtocolType
+from rasa.agents.schemas import AgentInput, AgentOutput
+from rasa.core.available_agents import AgentConfig
+from rasa.shared.agents.utils import make_agent_identifier
+from rasa.shared.exceptions import AgentInitializationException
+from rasa.utils.singleton import Singleton
+
+structlogger = structlog.get_logger()
+
+
+class AgentManager(metaclass=Singleton):
+    """High-level agent management with protocol abstraction"""
+
+    agents: ClassVar[Dict[AgentIdentifier, AgentProtocol]] = {}
+
+    def _add_agent(
+        self, agent_identifier: AgentIdentifier, agent: AgentProtocol
+    ) -> None:
+        """Add an agent to the manager.
+
+        Args:
+            agent_identifier: The identifier of the agent.
+            agent: The agent to add.
+        """
+        if agent_identifier in self.agents:
+            raise ValueError(f"Agent {agent_identifier} already exists")
+        self.agents[agent_identifier] = agent
+
+    def _remove_agent(self, agent_identifier: AgentIdentifier) -> None:
+        """Remove an agent from the manager.
+
+        Args:
+            agent_identifier: The identifier of the agent.
+
+        Raises:
+            ValueError: If the agent is not connected.
+        """
+        if agent_identifier not in self.agents:
+            raise ValueError(f"Agent {agent_identifier} is not available")
+        del self.agents[agent_identifier]
+
+    def get_agent(self, agent_name: str, protocol_type: ProtocolType) -> AgentProtocol:
+        """Retrieve connected agent instance.
+
+        Args:
+            agent_name: The name of the agent.
+            protocol_type: The protocol type of the agent.
+
+        Returns:
+            The agent.
+
+        Raises:
+            ValueError: If the agent is not connected.
+        """
+        agent_identifier = make_agent_identifier(agent_name, protocol_type)
+        if agent_identifier not in self.agents:
+            raise ValueError(f"Agent {agent_identifier} is not available")
+        return self.agents[agent_identifier]
+
+    async def connect_agent(
+        self, agent_name: str, protocol_type: ProtocolType, config: AgentConfig
+    ) -> None:
+        """Connect to agent using specified protocol, load the default resources
+        and persist the agent to the manager in a ready-to-use state so that
+        it can be used immediately to send messages to the agent.
+
+        Args:
+            agent_name: The name of the agent.
+            protocol_type: The protocol type of the agent.
+            config: The configuration for the agent as an AgentConfig object.
+
+        Raises:
+            ConnectionError: If the agent connection fails.
+        """
+        # Add the agent to the manager
+        agent_identifier = make_agent_identifier(agent_name, protocol_type)
+        try:
+            # Create the agent client
+            client = AgentFactory.create_client(protocol_type, config)
+
+            # Connect the agent client
+            await client.connect()
+
+            self._add_agent(agent_identifier, client)
+            structlogger.info(
+                "agent_manager.connect_agent.success",
+                agent_id=str(agent_identifier),
+                agent_name=agent_name,
+                event_info=f"Connected to agent - `{agent_identifier}` successfully",
+            )
+        except Exception as e:
+            event_info = f"Failed to connect agent {agent_identifier}"
+            structlogger.error(
+                "agent_manager.connect_agent.failed_to_connect",
+                agent_id=str(agent_identifier),
+                event_info=event_info,
+            )
+            raise AgentInitializationException(e)
+
+    async def run_agent(
+        self, agent_name: str, protocol_type: ProtocolType, context: AgentInput
+    ) -> AgentOutput:
+        """Run an agent, send the input to the agent and return the agent response.
+
+        Args:
+            agent_name: The name of the agent.
+            protocol_type: The protocol type of the agent.
+            context: The input to the agent as an AgentInput object.
+
+        Returns:
+            The response from the agent.
+        """
+        agent = self.get_agent(agent_name, protocol_type)
+
+        # Process input before sending
+        processed_input = await agent.process_input(context)
+
+        # Send message to agent
+        output = await agent.run(processed_input)
+
+        # Process output before returning
+        processed_output = await agent.process_output(output)
+
+        return processed_output
+
+    async def disconnect_agent(
+        self, agent_name: str, protocol_type: ProtocolType
+    ) -> None:
+        """Disconnect agent and remove from agent manager.
+
+        Args:
+            agent_name: The name of the agent.
+            protocol_type: The protocol type of the agent.
+
+        Raises:
+            ValueError: If the agent is not available.
+            ConnectionError: If the agent disconnection fails.
+        """
+        agent_identifier = make_agent_identifier(agent_name, protocol_type)
+        if agent_identifier not in self.agents:
+            raise ValueError(f"Agent {agent_identifier} is not available")
+        try:
+            await self.get_agent(agent_name, protocol_type).disconnect()
+            self._remove_agent(agent_identifier)
+            structlogger.info(
+                "agent_manager.disconnect_agent.success",
+                agent_id=str(agent_identifier),
+                event_info=f"Disconnected from agent - {agent_identifier} successfully",
+            )
+        except Exception as e:
+            event_info = f"Failed to disconnect agent {agent_identifier}"
+            structlogger.error(
+                "agent_manager.disconnect_agent.failed_to_disconnect",
+                agent_id=str(agent_identifier),
+                event_info=event_info,
+            )
+            raise ConnectionError(e)

rasa/agents/constants.py

@@ -0,0 +1,40 @@
+# Agent configuration constants
+AGENT_DEFAULT_MAX_RETRIES = 3
+AGENT_DEFAULT_TIMEOUT_SECONDS = 30
+MAX_AGENT_RETRY_DELAY_SECONDS = 5
+
+# MCP Tool related constants (primary)
+TOOL_TYPE_KEY = "type"
+TOOL_NAME_KEY = "name"
+TOOL_DESCRIPTION_KEY = "description"
+TOOL_PARAMETERS_KEY = "parameters"
+TOOL_STRICT_KEY = "strict"
+TOOL_TYPE_FUNCTION_KEY = "function"
+TOOL_EXECUTOR_KEY = "tool_executor"
+
+# MCP Tool related constants (secondary)
+TOOL_ADDITIONAL_PROPERTIES_KEY = "additionalProperties"
+TOOL_PROPERTIES_KEY = "properties"
+TOOL_REQUIRED_KEY = "required"
+TOOL_PROPERTY_TYPE_KEY = "type"
+
+# MCP Message related constants
+KEY_ROLE = "role"
+KEY_CONTENT = "content"
+
+# MCP Tool call related constants
+KEY_TOOL_CALL_ID = "tool_call_id"
+KEY_FUNCTION = "function"
+KEY_NAME = "name"
+KEY_ARGUMENTS = "arguments"
+KEY_ID = "id"
+KEY_TYPE = "type"
+KEY_TOOL_CALLS = "tool_calls"
+
+# Agent output metadata related constants
+AGENT_METADATA_AGENT_RESPONSE_KEY = "agent_response"
+AGENT_METADATA_TOOL_RESULTS_KEY = "tool_results"
+AGENT_METADATA_EXIT_IF_KEY = "exit_if"
+# A2A-specific constants
+A2A_AGENT_CONTEXT_ID_KEY = "context_id"
+A2A_AGENT_TASK_ID_KEY = "task_id"

rasa/agents/core/agent_protocol.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from rasa.agents.core.types import ProtocolType
+    from rasa.agents.schemas.agent_input import AgentInput
+    from rasa.agents.schemas.agent_output import AgentOutput
+    from rasa.core.available_agents import AgentConfig
+
+
+@runtime_checkable
+class AgentProtocol(Protocol):
+    """
+    Python protocol for interfacing with agent clients that implement the
+    agent communication protocols like MCP, A2A, ACP, etc.
+    """
+
+    @classmethod
+    def from_config(cls, config: AgentConfig) -> AgentProtocol:
+        """Initialize the Agent with the given configuration.
+
+        This class method should be implemented to parse the given
+        configuration and create an instance of an agent.
+
+        Args:
+            config: The configuration for the agent as an AgentConfig object.
+
+        Returns:
+            An instance of the agent.
+        """
+        ...
+
+    @property
+    def protocol_type(self) -> "ProtocolType":
+        """
+        Returns the protocol type of the agent.
+
+        This property should be implemented to return the protocol type of the agent.
+        This is used to determine the type of agent to create in the AgentFactory.
+        """
+        ...
+
+    async def connect(self) -> None:
+        """
+        Establish connection to agent/server.
+
+        This method should be implemented to establish a connection to the agent/server
+        and load any necessary resources.
+        """
+        ...
+
+    async def disconnect(self) -> None:
+        """
+        Close connection to agent/server.
+
+        This method should be implemented to close the connection to the agent/server
+        and release any necessary resources.
+        """
+        ...
+
+    async def process_input(self, input: "AgentInput") -> "AgentInput":
+        """
+        Pre-process the input before sending it to the agent.
+
+        This method should be implemented to pre-process the input before sending it
+        to the agent. This can be used to add any necessary metadata or context to the
+        input, or to filter the input.
+
+        Args:
+            input: The input to the agent as an AgentInput object.
+
+        Returns:
+            The processed input to the agent as an AgentInput object.
+        """
+        ...
+
+    async def run(self, input: "AgentInput") -> "AgentOutput":
+        """
+        Send a message to Agent/server and return response.
+
+        This method should be implemented to send a message to the agent/server and
+        return the response in an AgentOutput object.
+
+        Args:
+            input: The input to the agent as an AgentInput object.
+
+        Returns:
+            The output from the agent as an AgentOutput object.
+        """
+        ...
+
+    async def process_output(self, output: "AgentOutput") -> "AgentOutput":
+        """
+        Post-process the output before returning it to Rasa.
+
+        This method should be implemented to post-process the output before returning
+        it to Rasa. This can be used to add any necessary metadata or context to the
+        output, or to filter the output.
+
+        Args:
+            output: The output from the agent as an AgentOutput object.
+
+        Returns:
+            The processed output from the agent as an AgentOutput object.
+        """
+        ...

rasa/agents/core/types.py

@@ -0,0 +1,70 @@
+"""Fundamental types for the agent protocol."""
+
+from enum import Enum
+
+
+class ProtocolType(Enum):
+    """An Enum class that represents the supported protocol types."""
+
+    MCP_OPEN = "mcp_open"
+    MCP_TASK = "mcp_task"
+    A2A = "a2a"
+
+
+class AgentIdentifier:
+    """Represents a unique agent identifier combining agent_id and protocol_type."""
+
+    SEPARATOR = "::"
+
+    def __init__(self, agent_name: str, protocol_type: ProtocolType):
+        self.agent_name = agent_name
+        self.protocol_type = protocol_type
+
+    def __str__(self) -> str:
+        return f"{self.agent_name}{self.SEPARATOR}{self.protocol_type.value}"
+
+    def __repr__(self) -> str:
+        return (
+            f"AgentIdentifier(agent_name='{self.agent_name}', "
+            f"protocol_type='{self.protocol_type.value}')"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, AgentIdentifier):
+            return (
+                self.agent_name == other.agent_name
+                and self.protocol_type == other.protocol_type
+            )
+        elif isinstance(other, str):
+            return str(self) == other
+        return False
+
+    def __hash__(self) -> int:
+        return hash((self.agent_name, self.protocol_type))
+
+    @classmethod
+    def from_string(cls, identifier: str) -> "AgentIdentifier":
+        """Create an AgentIdentifier from a string representation."""
+        if cls.SEPARATOR not in identifier:
+            raise ValueError(f"Invalid agent identifier format: {identifier}")
+
+        parts = identifier.split(cls.SEPARATOR, 1)
+        if len(parts) != 2:
+            raise ValueError(f"Invalid agent identifier format: {identifier}")
+
+        agent_name, protocol_str = parts
+        try:
+            protocol_type = ProtocolType(protocol_str)
+        except ValueError:
+            raise ValueError(f"Invalid protocol type: {protocol_str}")
+
+        return cls(agent_name, protocol_type)
+
+
+class AgentStatus(Enum):
+    """A Enum class that represents the status of the agent."""
+
+    COMPLETED = "completed"
+    INPUT_REQUIRED = "input_required"
+    FATAL_ERROR = "fatal_error"
+    RECOVERABLE_ERROR = "recoverable_error"

rasa/agents/exceptions.py

@@ -0,0 +1,38 @@
+from rasa.exceptions import RasaException, ValidationError
+
+
+class AgentNotFoundException(RasaException):
+    """Raised when an agent is not found."""
+
+    def __init__(self, agent_name: str):
+        super().__init__(f"The agent {agent_name} is not defined.")
+
+
+class DuplicatedAgentNameException(ValidationError):
+    """Raised when agent names are duplicated."""
+
+    def __init__(self, duplicated_names: list[str]) -> None:
+        """Initialize the exception."""
+        event_info = f"Agent names are duplicated: {', '.join(duplicated_names)}"
+
+        super().__init__(
+            code="agent.duplicated_name",
+            event_info=event_info,
+            duplicated_names=duplicated_names,
+        )
+
+
+class AgentNameFlowConflictException(ValidationError):
+    """Raised when agent names conflict with flow names."""
+
+    def __init__(self, conflicting_names: list[str]) -> None:
+        """Initialize the exception."""
+        event_info = (
+            f"Agent names conflict with flow names: {', '.join(conflicting_names)}"
+        )
+
+        super().__init__(
+            code="agent.flow_name_conflict",
+            event_info=event_info,
+            conflicting_names=conflicting_names,
+        )

rasa/agents/protocol/__init__.py

@@ -0,0 +1,5 @@
+from rasa.agents.protocol.a2a.a2a_agent import A2AAgent
+from rasa.agents.protocol.mcp.mcp_open_agent import MCPOpenAgent
+from rasa.agents.protocol.mcp.mcp_task_agent import MCPTaskAgent
+
+__all__ = ["A2AAgent", "MCPOpenAgent", "MCPTaskAgent"]