webagents 0.1.12__py3-none-any.whl

webagents/agents/core/handoffs.py

@@ -0,0 +1,293 @@
+"""
+Agent Handoffs - Robutler V2.0
+
+LocalAgentHandoff implementation for same-instance agent transfers.
+Provides basic agent-to-agent handoff functionality within a single server instance.
+"""
+
+import asyncio
+import time
+from typing import Dict, Any, List, Optional, Union
+from dataclasses import dataclass
+from datetime import datetime
+
+from ..skills.base import HandoffResult
+from ...server.context.context_vars import get_context, create_context, set_context
+
+
+@dataclass
+class HandoffExecution:
+    """Record of handoff execution"""
+    timestamp: datetime
+    source_agent: str
+    target_agent: str
+    handoff_type: str
+    context_data: Dict[str, Any]
+    result: Any
+    duration_ms: float
+    success: bool
+    error: Optional[str] = None
+
+
+class LocalAgentHandoff:
+    """
+    LocalAgentHandoff - Same-instance agent handoff system
+    
+    Features:
+    - Agent-to-agent transfers within the same server instance
+    - Context preservation and transfer
+    - Handoff execution tracking and history
+    - Automatic context cleanup and management
+    """
+    
+    def __init__(self, agents: Dict[str, 'BaseAgent']):
+        """
+        Initialize LocalAgentHandoff with available agents
+        
+        Args:
+            agents: Dictionary of agent_name -> BaseAgent instances
+        """
+        self.agents = agents
+        self.handoff_history: List[HandoffExecution] = []
+        self.active_handoffs: Dict[str, str] = {}  # handoff_id -> target_agent
+        
+    def register_agent(self, agent_name: str, agent: 'BaseAgent') -> None:
+        """Register an agent for handoffs"""
+        self.agents[agent_name] = agent
+        
+    def unregister_agent(self, agent_name: str) -> None:
+        """Unregister an agent"""
+        if agent_name in self.agents:
+            del self.agents[agent_name]
+    
+    def get_available_agents(self) -> List[str]:
+        """Get list of available agents for handoff"""
+        return list(self.agents.keys())
+    
+    async def execute_handoff(
+        self,
+        source_agent: str,
+        target_agent: str,
+        handoff_data: Dict[str, Any] = None,
+        preserve_context: bool = True
+    ) -> HandoffResult:
+        """
+        Execute handoff from source agent to target agent
+        
+        Args:
+            source_agent: Name of the source agent
+            target_agent: Name of the target agent
+            handoff_data: Additional data to pass to target agent
+            preserve_context: Whether to preserve request context
+            
+        Returns:
+            HandoffResult with execution details
+        """
+        start_time = datetime.utcnow()
+        handoff_id = f"handoff_{int(time.time())}_{source_agent}_to_{target_agent}"
+        
+        try:
+            # Validate agents exist
+            if source_agent not in self.agents:
+                raise ValueError(f"Source agent '{source_agent}' not found")
+            if target_agent not in self.agents:
+                raise ValueError(f"Target agent '{target_agent}' not found")
+            
+            source = self.agents[source_agent]
+            target = self.agents[target_agent]
+            
+            # Get current context
+            current_context = get_context()
+            if not current_context:
+                raise ValueError("No active context for handoff")
+            
+            # Prepare handoff context data
+            context_data = {
+                'source_agent': source_agent,
+                'target_agent': target_agent,
+                'handoff_id': handoff_id,
+                'handoff_timestamp': start_time.isoformat(),
+                'handoff_data': handoff_data or {}
+            }
+            
+            # Create new context for target agent if preserving context
+            if preserve_context:
+                target_context = create_context(
+                    request_id=current_context.request_id,
+                    peer_user_id=current_context.peer_user_id,
+                    payment_user_id=current_context.payment_user_id,
+                    origin_user_id=current_context.origin_user_id,
+                    agent_owner_user_id=current_context.agent_owner_user_id,
+                    messages=current_context.messages.copy(),
+                    stream=current_context.stream
+                )
+                
+                # Add handoff context data
+                target_context.set("handoff_context", context_data)
+                target_context.update_agent_context(target, target_agent)
+                set_context(target_context)
+            
+            # Track active handoff
+            self.active_handoffs[handoff_id] = target_agent
+            
+            # Execute source agent's handoff hooks (if any)
+            if hasattr(source, '_execute_hooks'):
+                current_context.set("handoff_data", context_data)
+                await source._execute_hooks("before_handoff", current_context)
+            
+            # Create handoff message for target agent
+            handoff_message = {
+                "role": "system",
+                "content": f"Handoff from {source_agent}: {handoff_data.get('reason', 'Agent transfer requested')}"
+            }
+            
+            # Add handoff context to messages
+            messages_with_handoff = current_context.messages + [handoff_message]
+            if handoff_data and handoff_data.get('user_message'):
+                messages_with_handoff.append({
+                    "role": "user", 
+                    "content": handoff_data['user_message']
+                })
+            
+            # Execute target agent with handoff context
+            # Note: This is a basic implementation - could be enhanced with specific handoff methods
+            response = await target.run(
+                messages=messages_with_handoff,
+                tools=handoff_data.get('tools', []),
+                stream=False
+            )
+            
+            # Execute target agent's handoff hooks (if any)
+            if hasattr(target, '_execute_hooks'):
+                if preserve_context:
+                    target_context.set("handoff_result", response)
+                    await target._execute_hooks("after_handoff", target_context)
+            
+            # Calculate duration
+            duration_ms = (datetime.utcnow() - start_time).total_seconds() * 1000
+            
+            # Record successful handoff
+            execution = HandoffExecution(
+                timestamp=start_time,
+                source_agent=source_agent,
+                target_agent=target_agent,
+                handoff_type="local_agent",
+                context_data=context_data,
+                result=response,
+                duration_ms=duration_ms,
+                success=True
+            )
+            self.handoff_history.append(execution)
+            
+            # Remove from active handoffs
+            if handoff_id in self.active_handoffs:
+                del self.active_handoffs[handoff_id]
+            
+            # Return handoff result
+            return HandoffResult(
+                result=response,
+                handoff_type="local_agent",
+                success=True,
+                metadata={
+                    'handoff_id': handoff_id,
+                    'source_agent': source_agent,
+                    'target_agent': target_agent,
+                    'duration_ms': duration_ms,
+                    'context_preserved': preserve_context
+                }
+            )
+            
+        except Exception as e:
+            # Calculate duration
+            duration_ms = (datetime.utcnow() - start_time).total_seconds() * 1000
+            
+            # Record failed handoff
+            execution = HandoffExecution(
+                timestamp=start_time,
+                source_agent=source_agent,
+                target_agent=target_agent,
+                handoff_type="local_agent",
+                context_data=context_data if 'context_data' in locals() else {},
+                result=None,
+                duration_ms=duration_ms,
+                success=False,
+                error=str(e)
+            )
+            self.handoff_history.append(execution)
+            
+            # Clean up active handoff
+            if handoff_id in self.active_handoffs:
+                del self.active_handoffs[handoff_id]
+            
+            # Return error result
+            return HandoffResult(
+                result=None,
+                handoff_type="local_agent",
+                success=False,
+                metadata={
+                    'handoff_id': handoff_id if 'handoff_id' in locals() else 'unknown',
+                    'error': str(e),
+                    'duration_ms': duration_ms
+                }
+            )
+    
+    def get_handoff_history(self, limit: Optional[int] = None) -> List[HandoffExecution]:
+        """Get handoff execution history"""
+        history = sorted(self.handoff_history, key=lambda x: x.timestamp, reverse=True)
+        if limit:
+            history = history[:limit]
+        return history
+    
+    def get_active_handoffs(self) -> Dict[str, str]:
+        """Get currently active handoffs"""
+        return self.active_handoffs.copy()
+    
+    def get_handoff_stats(self) -> Dict[str, Any]:
+        """Get handoff statistics"""
+        if not self.handoff_history:
+            return {
+                'total_handoffs': 0,
+                'success_rate': 0.0,
+                'average_duration_ms': 0.0,
+                'most_common_source': None,
+                'most_common_target': None
+            }
+        
+        successful = [h for h in self.handoff_history if h.success]
+        failed = [h for h in self.handoff_history if not h.success]
+        
+        # Calculate statistics
+        total = len(self.handoff_history)
+        success_rate = len(successful) / total if total > 0 else 0.0
+        avg_duration = sum(h.duration_ms for h in successful) / len(successful) if successful else 0.0
+        
+        # Most common source and target
+        sources = [h.source_agent for h in self.handoff_history]
+        targets = [h.target_agent for h in self.handoff_history]
+        
+        most_common_source = max(set(sources), key=sources.count) if sources else None
+        most_common_target = max(set(targets), key=targets.count) if targets else None
+        
+        return {
+            'total_handoffs': total,
+            'successful_handoffs': len(successful),
+            'failed_handoffs': len(failed),
+            'success_rate': success_rate,
+            'average_duration_ms': avg_duration,
+            'most_common_source': most_common_source,
+            'most_common_target': most_common_target
+        }
+
+
+# Factory function for easy creation
+def create_local_handoff_system(agents: Dict[str, 'BaseAgent']) -> LocalAgentHandoff:
+    """
+    Factory function to create LocalAgentHandoff system
+    
+    Args:
+        agents: Dictionary of agent_name -> BaseAgent instances
+        
+    Returns:
+        Configured LocalAgentHandoff instance
+    """
+    return LocalAgentHandoff(agents) 

webagents/agents/skills/__init__.py

@@ -0,0 +1,109 @@
+"""
+Robutler Agents Skills
+
+This module provides the skill system for Robutler agents, including core skills,
+platform skills, and ecosystem skills. Skills are modular components that provide
+specific functionality to agents.
+"""
+
+from .base import Skill, Handoff, HandoffResult
+
+# Import all core skills that are always available
+from .core.llm.litellm import LiteLLMSkill
+
+# Core skills - these are fundamental and always available
+CORE_SKILLS = {
+    "litellm": LiteLLMSkill,
+}
+
+# Import Robutler platform skills
+from .robutler.crm import CRMAnalyticsSkill
+
+# Robutler platform skills - these integrate with Robutler services
+ROBUTLER_SKILLS = {
+    "crm": CRMAnalyticsSkill,
+    "analytics": CRMAnalyticsSkill,  # Alias for convenience
+}
+
+# Ecosystem skills - these integrate with external services
+ECOSYSTEM_SKILLS = {
+    # Will be populated as ecosystem integrations are implemented
+}
+
+# Combined skills registry
+ALL_SKILLS = {
+    **CORE_SKILLS,
+    **ROBUTLER_SKILLS, 
+    **ECOSYSTEM_SKILLS
+}
+
+# Export main classes and registries
+__all__ = [
+    # Base classes
+    'Skill',
+    'Handoff', 
+    'HandoffResult',
+    
+    # Skill registries
+    'CORE_SKILLS',
+    'ROBUTLER_SKILLS',
+    'ECOSYSTEM_SKILLS', 
+    'ALL_SKILLS',
+    
+    # Core skills
+    'LiteLLMSkill',
+]
+
+# Lazy loading for ecosystem skills to avoid heavy imports
+def get_skill(skill_name: str):
+    """Get a skill class by name, with lazy loading for ecosystem skills
+    
+    Args:
+        skill_name: Name of the skill to load
+        
+    Returns:
+        Skill class if found, None otherwise
+    """
+    # Check core skills first
+    if skill_name in CORE_SKILLS:
+        return CORE_SKILLS[skill_name]
+    
+    # Check platform skills
+    if skill_name in ROBUTLER_SKILLS:
+        return ROBUTLER_SKILLS[skill_name]
+    
+    # Lazy load ecosystem skills
+    ecosystem_imports = {
+        "google": ("robutler.agents.skills.ecosystem.google", "GoogleSkill"),
+        "database": ("robutler.agents.skills.ecosystem.database", "DatabaseSkill"),
+        "filesystem": ("robutler.agents.skills.ecosystem.filesystem", "FilesystemSkill"),
+        "web": ("robutler.agents.skills.ecosystem.web", "WebSkill"),
+        "crewai": ("robutler.agents.skills.ecosystem.crewai", "CrewAISkill"),
+        "n8n": ("robutler.agents.skills.ecosystem.n8n", "N8nSkill"),
+        "zapier": ("robutler.agents.skills.ecosystem.zapier", "ZapierSkill"),
+    }
+    
+    if skill_name in ecosystem_imports:
+        try:
+            module_path, class_name = ecosystem_imports[skill_name]
+            module = __import__(module_path, fromlist=[class_name])
+            skill_class = getattr(module, class_name)
+            ECOSYSTEM_SKILLS[skill_name] = skill_class
+            return skill_class
+        except ImportError:
+            # Ecosystem skill not available
+            return None
+    
+    return None
+
+def list_available_skills() -> dict:
+    """List all available skills by category
+    
+    Returns:
+        Dict with skill categories and their available skills
+    """
+    return {
+        "core": list(CORE_SKILLS.keys()),
+        "webagents": list(ROBUTLER_SKILLS.keys()),
+        "ecosystem": list(ECOSYSTEM_SKILLS.keys())
+    }

webagents/agents/skills/base.py

@@ -0,0 +1,136 @@
+"""
+Base Skill Interface - Robutler V2.0
+
+Core skill interface with unified context access, automatic registration support,
+and dependency resolution.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional, Callable, Union, TYPE_CHECKING
+from dataclasses import dataclass
+
+if TYPE_CHECKING:
+    from ..core.base_agent import BaseAgent
+
+
+class Skill(ABC):
+    """Base interface for agent skills with unified context access
+    
+    Skills have access to everything through a single Context object:
+    - During initialization: Basic agent reference for registration
+    - During request processing: Full Context via get_context()
+    
+    The Context contains BOTH request data AND agent capabilities:
+    - Request: messages, user, streaming, usage, etc.  
+    - Agent: skills, tools, hooks, capabilities, etc.
+    """
+    
+    def __init__(self, config: Dict[str, Any] = None, scope: str = "all", dependencies: List[str] = None):
+        self.config = config or {}
+        self.scope = scope  # "all", "owner", "admin" - controls skill availability  
+        self.dependencies = dependencies or []  # List of skill names this skill depends on
+        self.skill_name = self.__class__.__name__  # For tracking registration source
+        self.agent = None  # BaseAgent reference - set during initialization
+    
+    async def initialize(self, agent: 'BaseAgent') -> None:
+        """
+        Initialize skill with agent reference.
+        Skills should register their tools, hooks, and handoffs here.
+        
+        Args:
+            agent: The BaseAgent instance (for registration only)
+        """
+        self.agent = agent
+        # Subclasses implement their registration logic here
+    
+    def get_tools(self) -> List[Callable]:
+        """Return tools that this skill provides (from agent's central registry)"""
+        if not self.agent:
+            return []
+        return [tool['function'] for tool in self.agent.get_all_tools() 
+                if tool.get('source') == self.skill_name]
+    
+    def register_tool(self, tool_func: Callable, scope: str = None) -> None:
+        """Register a tool with the agent (central registration)
+        
+        Can be called during initialization or at runtime from hooks/tools.
+        """
+        if not self.agent:
+            raise RuntimeError("Cannot register tool: skill not initialized")
+        
+        # Use provided scope or fall back to skill's default scope
+        effective_scope = scope if scope is not None else self.scope
+        
+        # Allow skill to override tool scope if provided
+        if scope and hasattr(tool_func, '_tool_scope'):
+            tool_func._tool_scope = scope
+            
+        # Register with agent's central registry
+        self.agent.register_tool(tool_func, source=self.skill_name, scope=effective_scope)
+    
+    def register_hook(self, event: str, handler: Callable, priority: int = 50) -> None:
+        """Register a hook for lifecycle events (central registration)
+        
+        Hooks receive and return the unified Context object containing everything.
+        """
+        if not self.agent:
+            raise RuntimeError("Cannot register hook: skill not initialized")
+            
+        # Register with agent's central registry
+        self.agent.register_hook(event, handler, priority, source=self.skill_name)
+    
+    def register_handoff(self, handoff_config: 'Handoff') -> None:
+        """Register a handoff configuration"""
+        if not self.agent:
+            raise RuntimeError("Cannot register handoff: skill not initialized")
+            
+        # Register with agent's central registry
+        self.agent.register_handoff(handoff_config, source=self.skill_name)
+    
+    # Everything accessible via unified Context during request processing
+    def get_context(self) -> Optional['Context']:
+        """
+        Get unified Context containing EVERYTHING:
+        
+        Request data:
+        - context.messages, context.user, context.stream
+        - context.track_usage(), context.get()/set()
+        
+        Agent capabilities:
+        - context.agent_skills, context.agent_tools, context.agent_handoffs
+        - context.agent (BaseAgent instance)
+        """
+        from ...server.context.context_vars import get_context
+        return get_context()
+    
+    def get_dependencies(self) -> List[str]:
+        """Return list of skill dependencies"""
+        return self.dependencies.copy()
+
+
+# Base dataclasses for handoffs and other components
+@dataclass
+class Handoff:
+    """Configuration for handoff operations"""
+    target: str
+    handoff_type: str
+    description: str = ""
+    scope: Union[str, List[str]] = "all"
+    metadata: Dict[str, Any] = None
+
+    def __post_init__(self):
+        if self.metadata is None:
+            self.metadata = {}
+
+
+@dataclass  
+class HandoffResult:
+    """Result from handoff execution"""
+    result: Any
+    handoff_type: str
+    metadata: Dict[str, Any] = None
+    success: bool = True
+    
+    def __post_init__(self):
+        if self.metadata is None:
+            self.metadata = {} 

webagents/agents/skills/core/__init__.py

@@ -0,0 +1,8 @@
+"""
+Core Skills Package - Essential agent capabilities
+"""
+
+from .planning import PlannerSkill
+from .memory import ShortTermMemorySkill, LongTermMemorySkill, MemoryItem
+
+__all__ = ['PlannerSkill', 'ShortTermMemorySkill', 'LongTermMemorySkill', 'MemoryItem']

webagents/agents/skills/core/llm/anthropic/__init__.py

@@ -0,0 +1 @@
+# TODO: Implement dedicated Anthropic skill, currently using litellm

webagents/agents/skills/core/llm/litellm/__init__.py

@@ -0,0 +1,10 @@
+"""
+LiteLLM Skill Package - Robutler V2.0
+
+Cross-provider LLM routing with support for OpenAI, Anthropic, XAI/Grok, and more.
+Provides unified interface for multiple LLM providers with automatic fallbacks.
+"""
+
+from .skill import LiteLLMSkill
+
+__all__ = ["LiteLLMSkill"]