praisonaiagents 0.0.108__py3-none-any.whl → 0.0.110__py3-none-any.whl

praisonaiagents/__init__.py

@@ -14,6 +14,7 @@ from .mcp.mcp import MCP
 from .session import Session
 from .memory.memory import Memory
 from .guardrails import GuardrailResult, LLMGuardrail
+from .agent.handoff import Handoff, handoff, handoff_filters, RECOMMENDED_PROMPT_PREFIX, prompt_with_handoff_instructions
 from .main import (
     TaskOutput,
     ReflectionOutput,
@@ -102,6 +103,11 @@ __all__ = [
     'MCP',
     'GuardrailResult',
     'LLMGuardrail',
+    'Handoff',
+    'handoff',
+    'handoff_filters',
+    'RECOMMENDED_PROMPT_PREFIX',
+    'prompt_with_handoff_instructions',
     'get_telemetry',
     'enable_telemetry',
     'disable_telemetry',

praisonaiagents/agent/__init__.py

@@ -1,5 +1,6 @@
 """Agent module for AI agents"""
 from .agent import Agent
 from .image_agent import ImageAgent
+from .handoff import Handoff, handoff, handoff_filters, RECOMMENDED_PROMPT_PREFIX, prompt_with_handoff_instructions
 
-__all__ = ['Agent', 'ImageAgent']
+__all__ = ['Agent', 'ImageAgent', 'Handoff', 'handoff', 'handoff_filters', 'RECOMMENDED_PROMPT_PREFIX', 'prompt_with_handoff_instructions']

praisonaiagents/agent/agent.py

@@ -33,6 +33,7 @@ _shared_apps = {}  # Dict of port -> FastAPI app
 if TYPE_CHECKING:
     from ..task.task import Task
     from ..main import TaskOutput
+    from ..handoff import Handoff
 
 @dataclass
 class ChatCompletionMessage:
@@ -373,7 +374,10 @@ class Agent:
         user_id: Optional[str] = None,
         reasoning_steps: bool = False,
         guardrail: Optional[Union[Callable[['TaskOutput'], Tuple[bool, Any]], str]] = None,
-        max_guardrail_retries: int = 3
+        max_guardrail_retries: int = 3,
+        handoffs: Optional[List[Union['Agent', 'Handoff']]] = None,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None
     ):
         """Initialize an Agent instance.
 
@@ -457,6 +461,13 @@ class Agent:
                 description string for LLM-based validation. Defaults to None.
             max_guardrail_retries (int, optional): Maximum number of retry attempts when guardrail
                 validation fails before giving up. Defaults to 3.
+            handoffs (Optional[List[Union['Agent', 'Handoff']]], optional): List of agents or
+                handoff configurations that this agent can delegate tasks to. Enables agent-to-agent
+                collaboration and task specialization. Defaults to None.
+            base_url (Optional[str], optional): Base URL for custom LLM endpoints (e.g., Ollama).
+                If provided, automatically creates a custom LLM instance. Defaults to None.
+            api_key (Optional[str], optional): API key for LLM provider. If not provided,
+                falls back to environment variables. Defaults to None.
 
         Raises:
             ValueError: If all of name, role, goal, backstory, and instructions are None.
@@ -503,10 +514,40 @@ class Agent:
         # Check for model name in environment variable if not provided
         self._using_custom_llm = False
 
+        # If base_url is provided, always create a custom LLM instance
+        if base_url:
+            try:
+                from ..llm.llm import LLM
+                # Handle different llm parameter types with base_url
+                if isinstance(llm, dict):
+                    # Merge base_url and api_key into the dict
+                    llm_config = llm.copy()
+                    llm_config['base_url'] = base_url
+                    if api_key:
+                        llm_config['api_key'] = api_key
+                    self.llm_instance = LLM(**llm_config)
+                else:
+                    # Create LLM with model string and base_url
+                    model_name = llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-4o')
+                    self.llm_instance = LLM(
+                        model=model_name,
+                        base_url=base_url,
+                        api_key=api_key
+                    )
+                self._using_custom_llm = True
+            except ImportError as e:
+                raise ImportError(
+                    "LLM features requested but dependencies not installed. "
+                    "Please install with: pip install \"praisonaiagents[llm]\""
+                ) from e
         # If the user passes a dictionary (for advanced configuration)
-        if isinstance(llm, dict) and "model" in llm:
+        elif isinstance(llm, dict) and "model" in llm:
             try:
                 from ..llm.llm import LLM
+                # Add api_key if provided and not in dict
+                if api_key and 'api_key' not in llm:
+                    llm = llm.copy()
+                    llm['api_key'] = api_key
                 self.llm_instance = LLM(**llm)  # Pass all dict items as kwargs
                 self._using_custom_llm = True
             except ImportError as e:
@@ -519,7 +560,10 @@ class Agent:
             try:
                 from ..llm.llm import LLM
                 # Pass the entire string so LiteLLM can parse provider/model
-                self.llm_instance = LLM(model=llm)
+                llm_params = {'model': llm}
+                if api_key:
+                    llm_params['api_key'] = api_key
+                self.llm_instance = LLM(**llm_params)
                 self._using_custom_llm = True
                 
                 # Ensure tools are properly accessible when using custom LLM
@@ -584,6 +628,10 @@ Your Goal: {self.goal}
         self._guardrail_fn = None
         self._setup_guardrail()
 
+        # Process handoffs and convert them to tools
+        self.handoffs = handoffs if handoffs else []
+        self._process_handoffs()
+
         # Check if knowledge parameter has any values
         if not knowledge:
             self.knowledge = None
@@ -657,6 +705,34 @@ Your Goal: {self.goal}
         else:
             raise ValueError("Agent guardrail must be either a callable or a string description")
 
+    def _process_handoffs(self):
+        """Process handoffs and convert them to tools that can be used by the agent."""
+        if not self.handoffs:
+            return
+            
+        # Import here to avoid circular imports
+        from .handoff import Handoff
+        
+        for handoff_item in self.handoffs:
+            try:
+                if isinstance(handoff_item, Handoff):
+                    # Convert Handoff object to a tool function
+                    tool_func = handoff_item.to_tool_function(self)
+                    self.tools.append(tool_func)
+                elif hasattr(handoff_item, 'name') and hasattr(handoff_item, 'chat'):
+                    # Direct agent reference - create a simple handoff
+                    from .handoff import handoff
+                    handoff_obj = handoff(handoff_item)
+                    tool_func = handoff_obj.to_tool_function(self)
+                    self.tools.append(tool_func)
+                else:
+                    logging.warning(
+                        f"Invalid handoff item type: {type(handoff_item)}. "
+                        "Expected Agent or Handoff instance."
+                    )
+            except Exception as e:
+                logging.error(f"Failed to process handoff item {handoff_item}: {e}")
+
     def _process_guardrail(self, task_output):
         """Process the guardrail validation for a task output.
         

praisonaiagents/agent/handoff.py

@@ -0,0 +1,317 @@
+"""
+Handoff functionality for agent-to-agent delegation.
+
+This module provides handoff capabilities that allow agents to delegate tasks
+to other agents, similar to the OpenAI Agents SDK implementation.
+"""
+
+from typing import Optional, Any, Callable, Dict, TYPE_CHECKING
+from dataclasses import dataclass, field
+import inspect
+import logging
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HandoffInputData:
+    """Data passed to a handoff target agent."""
+    messages: list = field(default_factory=list)
+    context: Dict[str, Any] = field(default_factory=dict)
+    
+    
+class Handoff:
+    """
+    Represents a handoff configuration for delegating tasks to another agent.
+    
+    Handoffs are represented as tools to the LLM, allowing agents to transfer
+    control to specialized agents for specific tasks.
+    """
+    
+    def __init__(
+        self,
+        agent: 'Agent',
+        tool_name_override: Optional[str] = None,
+        tool_description_override: Optional[str] = None,
+        on_handoff: Optional[Callable] = None,
+        input_type: Optional[type] = None,
+        input_filter: Optional[Callable[[HandoffInputData], HandoffInputData]] = None
+    ):
+        """
+        Initialize a Handoff configuration.
+        
+        Args:
+            agent: The target agent to hand off to
+            tool_name_override: Custom tool name (defaults to transfer_to_<agent_name>)
+            tool_description_override: Custom tool description
+            on_handoff: Callback function executed when handoff is invoked
+            input_type: Type of input expected by the handoff (for structured data)
+            input_filter: Function to filter/transform input before passing to target agent
+        """
+        self.agent = agent
+        self.tool_name_override = tool_name_override
+        self.tool_description_override = tool_description_override
+        self.on_handoff = on_handoff
+        self.input_type = input_type
+        self.input_filter = input_filter
+        
+    @property
+    def tool_name(self) -> str:
+        """Get the tool name for this handoff."""
+        if self.tool_name_override:
+            return self.tool_name_override
+        return self.default_tool_name()
+        
+    @property
+    def tool_description(self) -> str:
+        """Get the tool description for this handoff."""
+        if self.tool_description_override:
+            return self.tool_description_override
+        return self.default_tool_description()
+        
+    def default_tool_name(self) -> str:
+        """Generate default tool name based on agent name."""
+        # Convert agent name to snake_case for tool name
+        agent_name = self.agent.name.lower().replace(' ', '_')
+        return f"transfer_to_{agent_name}"
+        
+    def default_tool_description(self) -> str:
+        """Generate default tool description based on agent role and goal."""
+        agent_desc = f"Transfer task to {self.agent.name}"
+        if hasattr(self.agent, 'role') and self.agent.role:
+            agent_desc += f" ({self.agent.role})"
+        if hasattr(self.agent, 'goal') and self.agent.goal:
+            agent_desc += f" - {self.agent.goal}"
+        return agent_desc
+        
+    def to_tool_function(self, source_agent: 'Agent') -> Callable:
+        """
+        Convert this handoff to a tool function that can be called by the LLM.
+        
+        Args:
+            source_agent: The agent that will be using this handoff
+            
+        Returns:
+            A callable function that performs the handoff
+        """
+        def handoff_tool(**kwargs):
+            """Execute the handoff to the target agent."""
+            try:
+                # Execute on_handoff callback if provided
+                if self.on_handoff:
+                    try:
+                        sig = inspect.signature(self.on_handoff)
+                        # Get parameters excluding those with defaults and varargs/varkwargs
+                        required_params = [
+                            p for p in sig.parameters.values()
+                            if p.default == inspect.Parameter.empty
+                            and p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD)
+                        ]
+                        num_required = len(required_params)
+                        
+                        if num_required == 0:
+                            self.on_handoff()
+                        elif num_required == 1:
+                            self.on_handoff(source_agent)
+                        elif num_required == 2:
+                            if self.input_type and kwargs:
+                                try:
+                                    input_data = self.input_type(**kwargs)
+                                    self.on_handoff(source_agent, input_data)
+                                except TypeError as e:
+                                    logger.error(f"Failed to create input_type instance: {e}")
+                                    self.on_handoff(source_agent, kwargs)
+                            else:
+                                # No input_type or no kwargs: pass raw kwargs or empty dict
+                                self.on_handoff(source_agent, kwargs or {})
+                        else:
+                            raise ValueError(
+                                f"Callback {self.on_handoff.__name__} requires {num_required} parameters, "
+                                "but only 0-2 are supported"
+                            )
+                    except Exception as e:
+                        logger.error(f"Error invoking callback {self.on_handoff.__name__}: {e}")
+                        # Continue with handoff even if callback fails
+                
+                # Prepare handoff data
+                handoff_data = HandoffInputData(
+                    messages=getattr(source_agent, 'chat_history', []),
+                    context={'source_agent': source_agent.name}
+                )
+                
+                # Apply input filter if provided
+                if self.input_filter:
+                    handoff_data = self.input_filter(handoff_data)
+                
+                # Get the last user message or context to pass to target agent
+                last_message = None
+                for msg in reversed(handoff_data.messages):
+                    if isinstance(msg, dict) and msg.get('role') == 'user':
+                        last_message = msg.get('content', '')
+                        break
+                
+                if not last_message and handoff_data.messages:
+                    # If no user message, use the last message
+                    last_msg = handoff_data.messages[-1]
+                    if isinstance(last_msg, dict):
+                        last_message = last_msg.get('content', '')
+                    else:
+                        last_message = str(last_msg)
+                
+                # Prepare context information
+                context_info = f"[Handoff from {source_agent.name}] "
+                if kwargs and self.input_type:
+                    # Include structured input data in context
+                    context_info += f"Context: {kwargs} "
+                
+                # Execute the target agent
+                if last_message:
+                    prompt = context_info + last_message
+                    logger.info(f"Handing off to {self.agent.name} with prompt: {prompt}")
+                    response = self.agent.chat(prompt)
+                    return f"Handoff successful. {self.agent.name} response: {response}"
+                return f"Handoff to {self.agent.name} completed, but no specific task was provided."
+                    
+            except Exception as e:
+                logger.error(f"Error during handoff to {self.agent.name}: {str(e)}")
+                return f"Error during handoff to {self.agent.name}: {str(e)}"
+        
+        # Set function metadata for tool definition generation
+        handoff_tool.__name__ = self.tool_name
+        handoff_tool.__doc__ = self.tool_description
+        
+        # Add input type annotations if provided
+        if self.input_type and hasattr(self.input_type, '__annotations__'):
+            sig_params = []
+            for field_name, field_type in self.input_type.__annotations__.items():
+                sig_params.append(
+                    inspect.Parameter(
+                        field_name,
+                        inspect.Parameter.KEYWORD_ONLY,
+                        annotation=field_type
+                    )
+                )
+            handoff_tool.__signature__ = inspect.Signature(sig_params)
+        
+        return handoff_tool
+
+
+def handoff(
+    agent: 'Agent',
+    tool_name_override: Optional[str] = None,
+    tool_description_override: Optional[str] = None,
+    on_handoff: Optional[Callable] = None,
+    input_type: Optional[type] = None,
+    input_filter: Optional[Callable[[HandoffInputData], HandoffInputData]] = None
+) -> Handoff:
+    """
+    Create a handoff configuration for delegating tasks to another agent.
+    
+    This is a convenience function that creates a Handoff instance with the
+    specified configuration.
+    
+    Args:
+        agent: The target agent to hand off to
+        tool_name_override: Custom tool name (defaults to transfer_to_<agent_name>)
+        tool_description_override: Custom tool description
+        on_handoff: Callback function executed when handoff is invoked
+        input_type: Type of input expected by the handoff (for structured data)
+        input_filter: Function to filter/transform input before passing to target agent
+        
+    Returns:
+        A configured Handoff instance
+        
+    Example:
+        ```python
+        from praisonaiagents import Agent, handoff
+        
+        billing_agent = Agent(name="Billing Agent")
+        refund_agent = Agent(name="Refund Agent")
+        
+        triage_agent = Agent(
+            name="Triage Agent",
+            handoffs=[billing_agent, handoff(refund_agent)]
+        )
+        ```
+    """
+    return Handoff(
+        agent=agent,
+        tool_name_override=tool_name_override,
+        tool_description_override=tool_description_override,
+        on_handoff=on_handoff,
+        input_type=input_type,
+        input_filter=input_filter
+    )
+
+
+# Handoff filters - common patterns for filtering handoff data
+class handoff_filters:
+    """Common handoff input filters."""
+    
+    @staticmethod
+    def remove_all_tools(data: HandoffInputData) -> HandoffInputData:
+        """Remove all tool calls from the message history."""
+        filtered_messages = []
+        for msg in data.messages:
+            if isinstance(msg, dict) and (msg.get('tool_calls') or msg.get('role') == 'tool'):
+                # Skip messages with tool calls
+                continue
+            filtered_messages.append(msg)
+        
+        data.messages = filtered_messages
+        return data
+    
+    @staticmethod
+    def keep_last_n_messages(n: int) -> Callable[[HandoffInputData], HandoffInputData]:
+        """Keep only the last n messages in the history."""
+        def filter_func(data: HandoffInputData) -> HandoffInputData:
+            data.messages = data.messages[-n:]
+            return data
+        return filter_func
+    
+    @staticmethod
+    def remove_system_messages(data: HandoffInputData) -> HandoffInputData:
+        """Remove all system messages from the history."""
+        filtered_messages = []
+        for msg in data.messages:
+            if (isinstance(msg, dict) and msg.get('role') != 'system') or not isinstance(msg, dict):
+                filtered_messages.append(msg)
+        
+        data.messages = filtered_messages
+        return data
+
+
+# Recommended prompt prefix for agents that use handoffs
+RECOMMENDED_PROMPT_PREFIX = """You have the ability to transfer tasks to specialized agents when appropriate. 
+When you determine that a task would be better handled by another agent with specific expertise, 
+use the transfer tool to hand off the task. The receiving agent will have the full context of 
+the conversation and will continue helping the user."""
+
+
+def prompt_with_handoff_instructions(base_prompt: str, agent: 'Agent') -> str:
+    """
+    Add handoff instructions to an agent's prompt.
+    
+    Args:
+        base_prompt: The original prompt/instructions
+        agent: The agent that will use handoffs
+        
+    Returns:
+        Updated prompt with handoff instructions
+    """
+    if not hasattr(agent, 'handoffs') or not agent.handoffs:
+        return base_prompt
+    
+    handoff_info = "\n\nAvailable handoff agents:\n"
+    for h in agent.handoffs:
+        if isinstance(h, Handoff):
+            handoff_info += f"- {h.agent.name}: {h.tool_description}\n"
+        else:
+            # Direct agent reference - create a temporary Handoff to get the default description
+            temp_handoff = Handoff(agent=h)
+            handoff_info += f"- {h.name}: {temp_handoff.tool_description}\n"
+    
+    return RECOMMENDED_PROMPT_PREFIX + handoff_info + "\n\n" + base_prompt