mbxai 2.2.0__py3-none-any.whl → 2.3.1__py3-none-any.whl

mbxai/agent/models.py

@@ -2,8 +2,10 @@
 Pydantic models for the agent client.
 """
 
-from typing import Any, Optional
+from typing import Any, Optional, Union, Callable, Protocol, Dict
 from pydantic import BaseModel, Field, field_validator
+from enum import Enum
+from abc import ABC, abstractmethod
 import uuid
 import re
 
@@ -41,20 +43,6 @@ class Result(BaseModel):
     result: str = Field(description="The result text from the AI")
 
 
-class AgentResponse(BaseModel):
-    """Response from the agent that can contain questions or a final result."""
-    agent_id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="Unique identifier for this agent session")
-    questions: list[Question] = Field(default_factory=list, description="List of questions for the user")
-    final_response: Optional[Any] = Field(default=None, description="The final response if processing is complete")
-    token_summary: Optional["TokenSummary"] = Field(default=None, description="Summary of token usage for this agent process")
-    
-    def has_questions(self) -> bool:
-        """Check if this response has questions that need to be answered."""
-        return len(self.questions) > 0
-    
-    def is_complete(self) -> bool:
-        """Check if this response contains a final result."""
-        return self.final_response is not None
 
 
 class QuestionList(BaseModel):
@@ -88,20 +76,24 @@ class TokenUsage(BaseModel):
 
 class TokenSummary(BaseModel):
     """Summary of token usage across all API calls in an agent process."""
-    question_generation: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for question generation")
-    thinking_process: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for thinking/processing")
-    quality_checks: list[TokenUsage] = Field(default_factory=list, description="Tokens used for each quality check iteration")
-    improvements: list[TokenUsage] = Field(default_factory=list, description="Tokens used for each improvement iteration")
+    requirement_analysis: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for requirement analysis")
+    tool_analysis: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for tool analysis")
+    todo_generation: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for todo list generation")
+    task_execution: list[TokenUsage] = Field(default_factory=list, description="Tokens used for each task execution")
+    dialog_interactions: list[TokenUsage] = Field(default_factory=list, description="Tokens used for human-in-the-loop interactions")
+    goal_evaluation: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for goal evaluation")
     final_response: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for final response generation")
     
     @property
     def total_tokens(self) -> int:
         """Calculate total tokens used across all operations."""
         total = (
-            self.question_generation.total_tokens +
-            self.thinking_process.total_tokens +
-            sum(usage.total_tokens for usage in self.quality_checks) +
-            sum(usage.total_tokens for usage in self.improvements) +
+            self.requirement_analysis.total_tokens +
+            self.tool_analysis.total_tokens +
+            self.todo_generation.total_tokens +
+            sum(usage.total_tokens for usage in self.task_execution) +
+            sum(usage.total_tokens for usage in self.dialog_interactions) +
+            self.goal_evaluation.total_tokens +
             self.final_response.total_tokens
         )
         return total
@@ -110,10 +102,12 @@ class TokenSummary(BaseModel):
     def total_prompt_tokens(self) -> int:
         """Calculate total prompt tokens used across all operations."""
         total = (
-            self.question_generation.prompt_tokens +
-            self.thinking_process.prompt_tokens +
-            sum(usage.prompt_tokens for usage in self.quality_checks) +
-            sum(usage.prompt_tokens for usage in self.improvements) +
+            self.requirement_analysis.prompt_tokens +
+            self.tool_analysis.prompt_tokens +
+            self.todo_generation.prompt_tokens +
+            sum(usage.prompt_tokens for usage in self.task_execution) +
+            sum(usage.prompt_tokens for usage in self.dialog_interactions) +
+            self.goal_evaluation.prompt_tokens +
             self.final_response.prompt_tokens
         )
         return total
@@ -122,10 +116,249 @@ class TokenSummary(BaseModel):
     def total_completion_tokens(self) -> int:
         """Calculate total completion tokens used across all operations."""
         total = (
-            self.question_generation.completion_tokens +
-            self.thinking_process.completion_tokens +
-            sum(usage.completion_tokens for usage in self.quality_checks) +
-            sum(usage.completion_tokens for usage in self.improvements) +
+            self.requirement_analysis.completion_tokens +
+            self.tool_analysis.completion_tokens +
+            self.todo_generation.completion_tokens +
+            sum(usage.completion_tokens for usage in self.task_execution) +
+            sum(usage.completion_tokens for usage in self.dialog_interactions) +
+            self.goal_evaluation.completion_tokens +
             self.final_response.completion_tokens
         )
         return total
+
+
+# New models for the enhanced agent architecture
+
+class TaskStatus(str, Enum):
+    """Status of a task in the todo list."""
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class Task(BaseModel):
+    """A task in the agent's todo list."""
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="Unique identifier for the task")
+    title: str = Field(description="Short title of the task")
+    description: str = Field(description="Detailed description of what needs to be done")
+    status: TaskStatus = Field(default=TaskStatus.PENDING, description="Current status of the task")
+    dependencies: list[str] = Field(default_factory=list, description="List of task IDs that must be completed before this task")
+    tools_needed: list[str] = Field(default_factory=list, description="List of tool names needed for this task")
+    estimated_complexity: int = Field(default=1, ge=1, le=5, description="Complexity rating from 1-5")
+    result: Optional[str] = Field(default=None, description="Result of the task execution")
+    error_message: Optional[str] = Field(default=None, description="Error message if task failed")
+
+
+class TodoList(BaseModel):
+    """A list of tasks to complete the user's goal."""
+    tasks: list[Task] = Field(description="List of tasks to complete")
+    estimated_total_time: Optional[str] = Field(default=None, description="Estimated total time to complete all tasks")
+    
+    def get_next_task(self) -> Optional[Task]:
+        """Get the next pending task that has all dependencies completed."""
+        completed_task_ids = {task.id for task in self.tasks if task.status == TaskStatus.COMPLETED}
+        
+        for task in self.tasks:
+            if task.status == TaskStatus.PENDING:
+                # Check if all dependencies are completed
+                if all(dep_id in completed_task_ids for dep_id in task.dependencies):
+                    return task
+        return None
+    
+    def get_task_by_id(self, task_id: str) -> Optional[Task]:
+        """Get a task by its ID."""
+        for task in self.tasks:
+            if task.id == task_id:
+                return task
+        return None
+
+
+class HumanInteractionType(str, Enum):
+    """Type of human interaction needed."""
+    DECISION = "decision"
+    QUESTION = "question"
+    DIALOG_OPTION = "dialog_option"
+
+
+class DialogOption(BaseModel):
+    """A dialog option for structured human-in-the-loop communication.
+    
+    Dialog options are UI-aware patterns that tell the frontend how to handle
+    specific interactions (authentication, approvals, integrations, etc.).
+    They are NOT functions executed by the agent - they're instructions for the UI.
+    """
+    id: str = Field(description="Unique identifier for the dialog option")
+    title: str = Field(description="Short title of the dialog option")
+    description: str = Field(description="Description of what this option does")
+    function: Optional[Callable[..., Any]] = Field(default=None, description="Optional function for backwards compatibility - prefer UI handling")
+    parameters: dict[str, Any] = Field(default_factory=dict, description="Parameters to help the UI handle this dialog (URLs, scopes, etc.)")
+    
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class HumanInLoopRequest(BaseModel):
+    """A request for human interaction."""
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="Unique identifier for this interaction")
+    interaction_type: HumanInteractionType = Field(description="Type of interaction needed")
+    prompt: str = Field(description="The prompt/question for the human")
+    options: list[str] = Field(default_factory=list, description="Available options for decisions")
+    dialog_options: list[DialogOption] = Field(default_factory=list, description="Available dialog options")
+    context: str = Field(default="", description="Additional context for the interaction")
+    required: bool = Field(default=True, description="Whether this interaction is required")
+
+
+class HumanInLoopResponse(BaseModel):
+    """Response from human interaction."""
+    interaction_id: str = Field(description="ID of the interaction being responded to")
+    response_type: HumanInteractionType = Field(description="Type of response")
+    decision: Optional[str] = Field(default=None, description="Selected decision option")
+    answer: Optional[str] = Field(default=None, description="Answer to a question")
+    dialog_option_id: Optional[str] = Field(default=None, description="Selected dialog option ID")
+    additional_context: str = Field(default="", description="Additional context from the user")
+
+
+class HumanInLoopResponseBatch(BaseModel):
+    """Batch of human responses for multiple interactions."""
+    responses: list[HumanInLoopResponse] = Field(description="List of human responses")
+    
+    def get_response_by_id(self, interaction_id: str) -> Optional[HumanInLoopResponse]:
+        """Get a response by interaction ID."""
+        for response in self.responses:
+            if response.interaction_id == interaction_id:
+                return response
+        return None
+
+
+# Session Handler Interface
+class SessionHandler(Protocol):
+    """Protocol for custom session storage implementations."""
+    
+    def get_session(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """Retrieve a session by agent ID."""
+        ...
+    
+    def set_session(self, agent_id: str, session_data: Dict[str, Any]) -> None:
+        """Store session data for an agent ID."""
+        ...
+    
+    def delete_session(self, agent_id: str) -> bool:
+        """Delete a session by agent ID. Returns True if deleted, False if not found."""
+        ...
+    
+    def list_sessions(self) -> list[str]:
+        """List all active session IDs."""
+        ...
+    
+    def session_exists(self, agent_id: str) -> bool:
+        """Check if a session exists."""
+        ...
+
+
+class InMemorySessionHandler:
+    """Default in-memory session handler implementation."""
+    
+    def __init__(self):
+        self._sessions: Dict[str, Dict[str, Any]] = {}
+    
+    def get_session(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """Retrieve a session by agent ID."""
+        return self._sessions.get(agent_id)
+    
+    def set_session(self, agent_id: str, session_data: Dict[str, Any]) -> None:
+        """Store session data for an agent ID."""
+        self._sessions[agent_id] = session_data
+    
+    def delete_session(self, agent_id: str) -> bool:
+        """Delete a session by agent ID. Returns True if deleted, False if not found."""
+        if agent_id in self._sessions:
+            del self._sessions[agent_id]
+            return True
+        return False
+    
+    def list_sessions(self) -> list[str]:
+        """List all active session IDs."""
+        return list(self._sessions.keys())
+    
+    def session_exists(self, agent_id: str) -> bool:
+        """Check if a session exists."""
+        return agent_id in self._sessions
+
+
+class RequirementAnalysis(BaseModel):
+    """Analysis of the user's requirement/goal."""
+    goal: str = Field(description="The main goal the user wants to achieve")
+    sub_goals: list[str] = Field(default_factory=list, description="Sub-goals that contribute to the main goal")
+    success_criteria: list[str] = Field(description="Criteria to determine if the goal is achieved")
+    constraints: list[str] = Field(default_factory=list, description="Any constraints or limitations to consider")
+    complexity_estimate: int = Field(ge=1, le=10, description="Complexity estimate from 1-10")
+
+
+class ToolAnalysis(BaseModel):
+    """Analysis of available tools and their relevance to the goal."""
+    relevant_tools: list[str] = Field(description="List of tool names relevant to the goal")
+    tool_mapping: dict[str, str] = Field(description="Mapping of tool names to their purpose for this goal")
+    missing_capabilities: list[str] = Field(default_factory=list, description="Capabilities needed but not available in tools")
+
+
+class GoalEvaluation(BaseModel):
+    """Evaluation of whether the goal has been achieved."""
+    goal_achieved: bool = Field(description="Whether the main goal has been achieved")
+    completion_percentage: int = Field(ge=0, le=100, description="Percentage of goal completion")
+    completed_criteria: list[str] = Field(description="Success criteria that have been met")
+    remaining_criteria: list[str] = Field(description="Success criteria that still need to be met")
+    feedback: str = Field(description="Detailed feedback on the goal achievement")
+    next_steps: list[str] = Field(default_factory=list, description="Next steps if goal is not fully achieved")
+
+
+class AgentState(str, Enum):
+    """Current state of the agent."""
+    ANALYZING_REQUIREMENT = "analyzing_requirement"
+    ANALYZING_TOOLS = "analyzing_tools"
+    GENERATING_TODO = "generating_todo"
+    EXECUTING_TASKS = "executing_tasks"
+    WAITING_FOR_HUMAN = "waiting_for_human"
+    EVALUATING_GOAL = "evaluating_goal"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class AgentResponse(BaseModel):
+    """Response from the agent that can contain various states and information."""
+    agent_id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="Unique identifier for this agent session")
+    state: AgentState = Field(description="Current state of the agent")
+    
+    # Legacy support for existing questions-based flow
+    questions: list[Question] = Field(default_factory=list, description="List of questions for the user (legacy)")
+    
+    # New architecture fields
+    requirement_analysis: Optional[RequirementAnalysis] = Field(default=None, description="Analysis of the requirement")
+    tool_analysis: Optional[ToolAnalysis] = Field(default=None, description="Analysis of available tools")
+    todo_list: Optional[TodoList] = Field(default=None, description="Current todo list")
+    current_task: Optional[Task] = Field(default=None, description="Currently executing task")
+    human_interaction_request: Optional[HumanInLoopRequest] = Field(default=None, description="Request for human interaction")
+    goal_evaluation: Optional[GoalEvaluation] = Field(default=None, description="Goal achievement evaluation")
+    
+    # Final response
+    final_response: Optional[Any] = Field(default=None, description="The final response if processing is complete")
+    
+    # Token usage tracking
+    token_summary: Optional[TokenSummary] = Field(default=None, description="Summary of token usage for this agent process")
+    
+    def has_questions(self) -> bool:
+        """Check if this response has questions that need to be answered (legacy)."""
+        return len(self.questions) > 0
+    
+    def needs_human_interaction(self) -> bool:
+        """Check if this response needs human interaction."""
+        return self.human_interaction_request is not None
+    
+    def is_complete(self) -> bool:
+        """Check if this response contains a final result."""
+        return self.state == AgentState.COMPLETED and self.final_response is not None
+    
+    def is_waiting_for_human(self) -> bool:
+        """Check if the agent is waiting for human input."""
+        return self.state == AgentState.WAITING_FOR_HUMAN

mbxai/examples/enhanced_agent_example.py

@@ -0,0 +1,344 @@
+"""
+Example demonstrating the enhanced Agent Client with the new 6-step process.
+"""
+
+import os
+from pydantic import BaseModel, Field
+from mbxai import AgentClient, OpenRouterClient, ToolClient
+from mbxai.agent.models import (
+    DialogOption, HumanInLoopResponse, HumanInteractionType, 
+    TaskStatus, AgentState
+)
+
+
+class ProjectPlan(BaseModel):
+    """A project plan response."""
+    project_name: str = Field(description="Name of the project")
+    description: str = Field(description="Project description")
+    technologies: list[str] = Field(description="Technologies to be used")
+    phases: list[str] = Field(description="Project phases")
+    estimated_duration: str = Field(description="Estimated project duration")
+    deliverables: list[str] = Field(description="Key deliverables")
+    risks: list[str] = Field(description="Potential risks and mitigation strategies")
+
+
+class WeatherInfo(BaseModel):
+    """Weather information response."""
+    location: str = Field(description="The location")
+    current_weather: str = Field(description="Current weather description")
+    temperature: str = Field(description="Current temperature")
+    recommendations: list[str] = Field(description="Recommendations based on weather")
+
+
+def google_auth_dialog_option() -> str:
+    """Simulate Google authentication."""
+    print("🔐 Simulating Google Authentication...")
+    return "Successfully authenticated with Google"
+
+
+def slack_integration_dialog_option() -> str:
+    """Simulate Slack integration setup."""
+    print("💬 Simulating Slack integration setup...")
+    return "Slack integration configured successfully"
+
+
+def example_basic_agent():
+    """Example of basic agent usage without human-in-the-loop."""
+    print("=== Basic Agent Example ===")
+    
+    # Initialize client
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "demo-token"))
+    agent = AgentClient(openrouter_client, human_in_loop=False)
+    
+    # Create a project plan
+    prompt = "Create a project plan for building a simple weather app using React and Node.js"
+    
+    print(f"🚀 Starting agent with prompt: {prompt}")
+    response = agent.agent(prompt, final_response_structure=ProjectPlan)
+    
+    print(f"📊 Agent state: {response.state}")
+    
+    if response.requirement_analysis:
+        print(f"📋 Goal: {response.requirement_analysis.goal}")
+        print(f"📋 Complexity: {response.requirement_analysis.complexity_estimate}/10")
+    
+    if response.todo_list:
+        print(f"📝 Generated {len(response.todo_list.tasks)} tasks:")
+        for task in response.todo_list.tasks:
+            print(f"  - {task.title} (Status: {task.status.value})")
+    
+    if response.is_complete():
+        plan = response.final_response
+        print(f"\n✅ Project Plan Generated:")
+        print(f"📦 Project: {plan.project_name}")
+        print(f"📄 Description: {plan.description}")
+        print(f"💻 Technologies: {', '.join(plan.technologies)}")
+        print(f"⏱️ Duration: {plan.estimated_duration}")
+        print(f"📋 Phases: {', '.join(plan.phases)}")
+        
+        # Print token usage
+        if response.token_summary:
+            print(f"\n📊 Token usage: {response.token_summary.total_tokens} total")
+    
+    return response.agent_id
+
+
+def example_human_in_loop():
+    """Example of agent with human-in-the-loop interactions."""
+    print("\n=== Human-in-the-Loop Agent Example ===")
+    
+    # Initialize client with dialog options
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "demo-token"))
+    
+    dialog_options = [
+        DialogOption(
+            id="google_auth",
+            title="Google Authentication",
+            description="Authenticate with Google services",
+            function=google_auth_dialog_option
+        ),
+        DialogOption(
+            id="slack_integration",
+            title="Slack Integration",
+            description="Set up Slack integration",
+            function=slack_integration_dialog_option
+        )
+    ]
+    
+    agent = AgentClient(
+        openrouter_client, 
+        human_in_loop=True, 
+        dialog_options=dialog_options,
+        max_task_iterations=5
+    )
+    
+    # Start with a complex task
+    prompt = "Set up a complete CI/CD pipeline for a web application with automated testing, deployment, and monitoring"
+    
+    print(f"🚀 Starting agent with human-in-loop: {prompt}")
+    response = agent.agent(prompt, final_response_structure=ProjectPlan)
+    
+    print(f"📊 Agent state: {response.state}")
+    
+    # Simulate human interactions
+    iteration = 0
+    max_iterations = 3
+    
+    while not response.is_complete() and iteration < max_iterations:
+        iteration += 1
+        print(f"\n--- Iteration {iteration} ---")
+        
+        if response.needs_human_interaction():
+            request = response.human_interaction_request
+            print(f"👤 Human interaction needed: {request.interaction_type.value}")
+            print(f"💬 Prompt: {request.prompt}")
+            
+            if request.interaction_type == HumanInteractionType.DECISION:
+                print(f"📋 Options: {', '.join(request.options)}")
+                # Simulate user choosing to proceed
+                human_response = HumanInLoopResponse(
+                    interaction_id=request.id,
+                    response_type=HumanInteractionType.DECISION,
+                    decision="proceed",
+                    additional_context="User decided to proceed with the current approach"
+                )
+            elif request.interaction_type == HumanInteractionType.QUESTION:
+                # Simulate user answering a question
+                human_response = HumanInLoopResponse(
+                    interaction_id=request.id,
+                    response_type=HumanInteractionType.QUESTION,
+                    answer="Use Docker for containerization and AWS for cloud services",
+                    additional_context="User prefers cloud-native solutions"
+                )
+            elif request.interaction_type == HumanInteractionType.DIALOG_OPTION:
+                # Simulate user selecting a dialog option
+                print(f"🔧 Available dialog options:")
+                for option in request.dialog_options:
+                    print(f"  - {option.title}: {option.description}")
+                
+                selected_option = request.dialog_options[0] if request.dialog_options else None
+                human_response = HumanInLoopResponse(
+                    interaction_id=request.id,
+                    response_type=HumanInteractionType.DIALOG_OPTION,
+                    dialog_option_id=selected_option.id if selected_option else "none",
+                    additional_context="User selected the first option"
+                )
+            else:
+                # Default response
+                human_response = HumanInLoopResponse(
+                    interaction_id=request.id,
+                    response_type=HumanInteractionType.QUESTION,
+                    answer="Continue with default settings"
+                )
+            
+            print(f"💭 Simulated user response: {human_response.answer or human_response.decision or 'dialog option selected'}")
+            
+            # Continue with human response
+            response = agent.agent(
+                prompt="Continue with user input", 
+                final_response_structure=ProjectPlan, 
+                agent_id=response.agent_id,
+                human_response=human_response
+            )
+        
+        elif response.state == AgentState.EXECUTING_TASKS:
+            print(f"⚡ Agent is executing tasks...")
+            if response.current_task:
+                print(f"📋 Current task: {response.current_task.title}")
+            
+            # Continue execution
+            response = agent.agent(
+                prompt="Continue execution", 
+                final_response_structure=ProjectPlan, 
+                agent_id=response.agent_id
+            )
+        
+        else:
+            print(f"📊 Agent state: {response.state}")
+            break
+    
+    if response.is_complete():
+        plan = response.final_response
+        print(f"\n✅ CI/CD Plan Generated:")
+        print(f"📦 Project: {plan.project_name}")
+        print(f"📄 Description: {plan.description}")
+        print(f"💻 Technologies: {', '.join(plan.technologies)}")
+        
+        if response.goal_evaluation:
+            print(f"\n🎯 Goal Achievement: {response.goal_evaluation.completion_percentage}%")
+            print(f"💭 Feedback: {response.goal_evaluation.feedback}")
+    
+    return response.agent_id
+
+
+def example_with_tools():
+    """Example of agent with tools."""
+    print("\n=== Agent with Tools Example ===")
+    
+    # Initialize tool client
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "demo-token"))
+    tool_client = ToolClient(openrouter_client)
+    
+    # Register a weather tool
+    def get_weather(location: str) -> str:
+        """Get current weather for a location."""
+        # This is a mock implementation
+        return f"The weather in {location} is sunny and 72°F with light winds"
+    
+    def get_forecast(location: str, days: int = 5) -> str:
+        """Get weather forecast for a location."""
+        return f"5-day forecast for {location}: Mostly sunny with temperatures ranging from 68-75°F"
+    
+    agent = AgentClient(tool_client, human_in_loop=False)
+    
+    # Register tools
+    agent.register_tool(
+        name="get_weather",
+        description="Get current weather information for a specific location",
+        function=get_weather
+    )
+    
+    agent.register_tool(
+        name="get_forecast", 
+        description="Get weather forecast for a location",
+        function=get_forecast
+    )
+    
+    # Ask for weather information
+    prompt = "I'm planning a picnic in San Francisco this weekend. Can you help me understand the weather and give recommendations?"
+    
+    print(f"🚀 Starting agent with tools: {prompt}")
+    response = agent.agent(prompt, final_response_structure=WeatherInfo)
+    
+    print(f"📊 Agent state: {response.state}")
+    
+    if response.tool_analysis:
+        print(f"🔧 Relevant tools: {', '.join(response.tool_analysis.relevant_tools)}")
+    
+    if response.is_complete():
+        weather = response.final_response
+        print(f"\n🌤️ Weather Information:")
+        print(f"📍 Location: {weather.location}")
+        print(f"🌡️ Current: {weather.current_weather}")
+        print(f"🌡️ Temperature: {weather.temperature}")
+        print(f"💡 Recommendations:")
+        for rec in weather.recommendations:
+            print(f"  - {rec}")
+    
+    return response.agent_id
+
+
+def example_session_management():
+    """Example of session management and continuation."""
+    print("\n=== Session Management Example ===")
+    
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "demo-token"))
+    agent = AgentClient(openrouter_client, human_in_loop=False)
+    
+    # Start first task
+    prompt1 = "Create a basic project structure for a Python web API"
+    response1 = agent.agent(prompt1, final_response_structure=ProjectPlan)
+    agent_id = response1.agent_id
+    
+    print(f"📋 First task completed: {response1.is_complete()}")
+    
+    if response1.is_complete():
+        plan1 = response1.final_response
+        print(f"📦 First project: {plan1.project_name}")
+        
+        # Continue with related task
+        prompt2 = "Now add authentication and user management to this API project"
+        response2 = agent.agent(prompt2, final_response_structure=ProjectPlan, agent_id=agent_id)
+        
+        print(f"📋 Second task completed: {response2.is_complete()}")
+        
+        if response2.is_complete():
+            plan2 = response2.final_response
+            print(f"📦 Enhanced project: {plan2.project_name}")
+            print(f"🔐 New features: {', '.join(plan2.technologies)}")
+    
+    # List sessions
+    sessions = agent.list_sessions()
+    print(f"📊 Active sessions: {len(sessions)}")
+    
+    # Get session info
+    if agent_id in sessions:
+        session_info = agent.get_session_info(agent_id)
+        print(f"💬 Conversation length: {session_info.get('conversation_length', 0)} messages")
+    
+    # Clean up
+    deleted = agent.delete_session(agent_id)
+    print(f"🗑️ Session deleted: {deleted}")
+    
+    return agent_id
+
+
+def main():
+    """Run all examples."""
+    print("🤖 Enhanced Agent Client Examples")
+    print("=" * 50)
+    
+    try:
+        # Basic agent without human interaction
+        basic_id = example_basic_agent()
+        
+        # Agent with human-in-the-loop
+        hitl_id = example_human_in_loop()
+        
+        # Agent with tools
+        tools_id = example_with_tools()
+        
+        # Session management
+        session_id = example_session_management()
+        
+        print(f"\n✅ All examples completed successfully!")
+        print(f"📋 Generated agent IDs: {basic_id}, {hitl_id}, {tools_id}, {session_id}")
+        
+    except Exception as e:
+        print(f"❌ Error running examples: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()