agnt5 0.2.8a4__cp310-abi3-manylinux_2_34_x86_64.whl → 0.2.8a5__cp310-abi3-manylinux_2_34_x86_64.whl

agnt5/__init__.py

@@ -26,9 +26,10 @@ from .exceptions import (
     ExecutionError,
     RetryError,
     StateError,
+    WaitingForUserInputException,
 )
 from .function import FunctionRegistry, function
-from .tool import Tool, ToolRegistry, tool
+from .tool import AskUserTool, RequestApprovalTool, Tool, ToolRegistry, tool
 from .types import BackoffPolicy, BackoffType, FunctionConfig, RetryPolicy, WorkflowConfig
 from .version import _get_version
 from .worker import Worker
@@ -62,6 +63,8 @@ __all__ = [
     "tool",
     "Tool",
     "ToolRegistry",
+    "AskUserTool",
+    "RequestApprovalTool",
     "agent",
     "Agent",
     "AgentRegistry",
@@ -81,6 +84,7 @@ __all__ = [
     "RetryError",
     "StateError",
     "CheckpointError",
+    "WaitingForUserInputException",
     "RunError",
     # Language Model (Simplified API)
     "lm",

agnt5/agent.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import functools
 import json
 import logging
+import time
 from typing import Any, Callable, Dict, List, Optional
 
 from .context import Context
@@ -221,10 +222,10 @@ class AgentContext(Context):
         for msg in messages:
             messages_data.append({
                 "role": msg.role.value if hasattr(msg.role, 'value') else str(msg.role),
-                "content": msg.content
+                "content": msg.content,
+                "timestamp": time.time()  # Add timestamp for each message
             })
 
-        import time
         entity_type = "AgentSession"
         entity_key = self._entity_key
 

agnt5/exceptions.py

@@ -1,5 +1,7 @@
 """AGNT5 SDK exceptions and error types."""
 
+from typing import Dict, List, Optional
+
 
 class AGNT5Error(Exception):
     """Base exception for all AGNT5 SDK errors."""
@@ -44,3 +46,44 @@ class NotImplementedError(AGNT5Error):
     """Raised when a feature is not yet implemented."""
 
     pass
+
+
+class WaitingForUserInputException(AGNT5Error):
+    """Raised when workflow needs to pause for user input.
+
+    This exception is used internally by ctx.wait_for_user() to signal
+    that a workflow execution should pause and wait for user input.
+
+    The platform catches this exception and:
+    1. Saves the workflow checkpoint state
+    2. Returns awaiting_user_input status to the client
+    3. Presents the question and options to the user
+    4. Resumes execution when user responds
+
+    Attributes:
+        question: The question to ask the user
+        input_type: Type of input ("text", "approval", or "choice")
+        options: List of options for approval/choice inputs
+        checkpoint_state: Current workflow state for resume
+    """
+
+    def __init__(
+        self,
+        question: str,
+        input_type: str,
+        options: Optional[List[Dict]],
+        checkpoint_state: Dict,
+    ) -> None:
+        """Initialize WaitingForUserInputException.
+
+        Args:
+            question: Question to ask the user
+            input_type: Type of input - "text", "approval", or "choice"
+            options: List of option dicts (for approval/choice)
+            checkpoint_state: Workflow state snapshot for resume
+        """
+        super().__init__(f"Waiting for user input: {question}")
+        self.question = question
+        self.input_type = input_type
+        self.options = options or []
+        self.checkpoint_state = checkpoint_state

agnt5/tool.py

@@ -416,3 +416,152 @@ def tool(
     if _func is None:
         return decorator
     return decorator(_func)
+
+
+# ============================================================================
+# Built-in Human-in-the-Loop Tools
+# ============================================================================
+
+class AskUserTool(Tool):
+    """
+    Built-in tool that agents can use to request text input from users.
+
+    This tool pauses the workflow execution and waits for the user to provide
+    a text response. The workflow resumes when the user submits their input.
+
+    Example:
+        ```python
+        from agnt5 import Agent, workflow, WorkflowContext
+        from agnt5.tool import AskUserTool
+
+        @workflow(chat=True)
+        async def agent_with_hitl(ctx: WorkflowContext, query: str) -> dict:
+            agent = Agent(
+                name="research_agent",
+                model="openai/gpt-4o-mini",
+                instructions="You are a research assistant.",
+                tools=[AskUserTool(ctx)]
+            )
+
+            result = await agent.run(query, context=ctx)
+            return {"response": result.output}
+        ```
+    """
+
+    def __init__(self, context: "WorkflowContext"):  # type: ignore
+        """
+        Initialize AskUserTool.
+
+        Args:
+            context: Workflow context with wait_for_user capability
+        """
+        # Import here to avoid circular dependency
+        from .workflow import WorkflowContext
+
+        if not isinstance(context, WorkflowContext):
+            raise ConfigurationError(
+                "AskUserTool requires a WorkflowContext. "
+                "This tool can only be used within workflows."
+            )
+
+        super().__init__(
+            name="ask_user",
+            description="Ask the user a question and wait for their text response",
+            handler=self._handler,
+            auto_schema=True
+        )
+        self.context = context
+
+    async def _handler(self, ctx: Context, question: str) -> str:
+        """
+        Ask user a question and wait for their response.
+
+        Args:
+            ctx: Execution context (unused, required by Tool signature)
+            question: Question to ask the user
+
+        Returns:
+            User's text response
+        """
+        return await self.context.wait_for_user(question, input_type="text")
+
+
+class RequestApprovalTool(Tool):
+    """
+    Built-in tool that agents can use to request approval from users.
+
+    This tool pauses the workflow execution and presents an approval request
+    to the user with approve/reject options. The workflow resumes when the
+    user makes a decision.
+
+    Example:
+        ```python
+        from agnt5 import Agent, workflow, WorkflowContext
+        from agnt5.tool import RequestApprovalTool
+
+        @workflow(chat=True)
+        async def deployment_agent(ctx: WorkflowContext, changes: dict) -> dict:
+            agent = Agent(
+                name="deploy_agent",
+                model="openai/gpt-4o-mini",
+                instructions="You help deploy code changes safely.",
+                tools=[RequestApprovalTool(ctx)]
+            )
+
+            result = await agent.run(
+                f"Review and deploy these changes: {changes}",
+                context=ctx
+            )
+            return {"response": result.output}
+        ```
+    """
+
+    def __init__(self, context: "WorkflowContext"):  # type: ignore
+        """
+        Initialize RequestApprovalTool.
+
+        Args:
+            context: Workflow context with wait_for_user capability
+        """
+        # Import here to avoid circular dependency
+        from .workflow import WorkflowContext
+
+        if not isinstance(context, WorkflowContext):
+            raise ConfigurationError(
+                "RequestApprovalTool requires a WorkflowContext. "
+                "This tool can only be used within workflows."
+            )
+
+        super().__init__(
+            name="request_approval",
+            description="Request user approval for an action before proceeding",
+            handler=self._handler,
+            auto_schema=True
+        )
+        self.context = context
+
+    async def _handler(self, ctx: Context, action: str, details: str = "") -> str:
+        """
+        Request approval from user for an action.
+
+        Args:
+            ctx: Execution context (unused, required by Tool signature)
+            action: The action requiring approval
+            details: Additional details about the action
+
+        Returns:
+            "approve" or "reject" based on user's decision
+        """
+        question = f"Action: {action}"
+        if details:
+            question += f"\n\nDetails:\n{details}"
+        question += "\n\nDo you approve?"
+
+        return await self.context.wait_for_user(
+            question,
+            input_type="approval",
+            options=[
+                {"id": "approve", "label": "Approve"},
+                {"id": "reject", "label": "Reject"}
+            ]
+        )

agnt5/worker.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import contextvars
 import logging
+import uuid
 from typing import Any, Dict, List, Optional
 
 from .function import FunctionRegistry
@@ -758,16 +759,31 @@ class Worker:
         """Execute a workflow handler with automatic replay support."""
         import json
         from .workflow import WorkflowEntity, WorkflowContext
-        from .entity import _get_state_adapter
+        from .entity import _get_state_adapter, _entity_state_adapter_ctx
+        from .exceptions import WaitingForUserInputException
         from ._core import PyExecuteComponentResponse
 
+        # Set entity state adapter in context so workflows can use Entities
+        _entity_state_adapter_ctx.set(self._entity_state_adapter)
+
         try:
             # Parse input data
             input_dict = json.loads(input_data.decode("utf-8")) if input_data else {}
 
+            # Extract or generate session_id for multi-turn conversation support (for chat workflows)
+            # If session_id is provided, the workflow can maintain conversation context
+            session_id = input_dict.get("session_id")
+
+            if not session_id:
+                session_id = str(uuid.uuid4())
+                logger.info(f"Created new workflow session: {session_id}")
+            else:
+                logger.info(f"Using existing workflow session: {session_id}")
+
             # Parse replay data from request metadata for crash recovery
             completed_steps = {}
             initial_state = {}
+            user_response = None
 
             if hasattr(request, 'metadata') and request.metadata:
                 # Parse completed steps for replay
@@ -790,6 +806,11 @@ class Worker:
                         except json.JSONDecodeError:
                             logger.warning("Failed to parse workflow_state from metadata")
 
+                # Check for user response (workflow resume after pause)
+                if "user_response" in request.metadata:
+                    user_response = request.metadata["user_response"]
+                    logger.info(f"▶️  Resuming workflow with user response: {user_response}")
+
             # Create WorkflowEntity for state management
             workflow_entity = WorkflowEntity(run_id=f"{self.service_name}:{config.name}")
 
@@ -798,6 +819,11 @@ class Worker:
                 workflow_entity._completed_steps = completed_steps
                 logger.debug(f"Loaded {len(completed_steps)} completed steps into workflow entity")
 
+            # Inject user response if resuming from pause
+            if user_response:
+                workflow_entity.inject_user_response(user_response)
+                logger.debug(f"Injected user response into workflow entity")
+
             if initial_state:
                 # Load initial state into entity's state adapter
                 state_adapter = _get_state_adapter()
@@ -860,13 +886,70 @@ class Worker:
 
             logger.info(f"Workflow completed successfully with {len(step_events)} steps")
 
+            # Add session_id to metadata for multi-turn conversation support
+            metadata["session_id"] = session_id
+
             return PyExecuteComponentResponse(
                 invocation_id=request.invocation_id,
                 success=True,
                 output_data=output_data,
                 state_update=None,  # Not used for workflows (use metadata instead)
                 error_message=None,
-                metadata=metadata if metadata else None,  # Include step events + state
+                metadata=metadata if metadata else None,  # Include step events + state + session_id
+                is_chunk=False,
+                done=True,
+                chunk_index=0,
+            )
+
+        except WaitingForUserInputException as e:
+            # Workflow paused for user input
+            logger.info(f"⏸️  Workflow paused waiting for user input: {e.question}")
+
+            # Collect metadata for pause state
+            # Note: All metadata values must be strings for Rust FFI
+            pause_metadata = {
+                "status": "awaiting_user_input",
+                "question": e.question,
+                "input_type": e.input_type,
+            }
+
+            # Add optional fields only if they exist
+            if e.options:
+                pause_metadata["options"] = json.dumps(e.options)
+            if e.checkpoint_state:
+                pause_metadata["checkpoint_state"] = json.dumps(e.checkpoint_state)
+            if session_id:
+                pause_metadata["session_id"] = session_id
+
+            # Add step events to pause metadata for durability
+            step_events = ctx._workflow_entity._step_events
+            if step_events:
+                pause_metadata["step_events"] = json.dumps(step_events)
+                logger.debug(f"Paused workflow has {len(step_events)} recorded steps")
+
+            # Add current workflow state to pause metadata
+            if hasattr(ctx, '_workflow_entity') and ctx._workflow_entity._state is not None:
+                if ctx._workflow_entity._state.has_changes():
+                    state_snapshot = ctx._workflow_entity._state.get_state_snapshot()
+                    pause_metadata["workflow_state"] = json.dumps(state_snapshot)
+                    logger.debug(f"Paused workflow state snapshot: {state_snapshot}")
+
+            # Return "success" with awaiting_user_input metadata
+            # The output contains the question details for the client
+            output = {
+                "question": e.question,
+                "input_type": e.input_type,
+                "options": e.options,
+            }
+            output_data = json.dumps(output).encode("utf-8")
+
+            return PyExecuteComponentResponse(
+                invocation_id=request.invocation_id,
+                success=True,  # This is a valid pause state, not an error
+                output_data=output_data,
+                state_update=None,
+                error_message=None,
+                metadata=pause_metadata,
                 is_chunk=False,
                 done=True,
                 chunk_index=0,

agnt5/workflow.py

@@ -7,7 +7,7 @@ import functools
 import inspect
 import logging
 import uuid
-from typing import Any, Callable, Dict, Optional, TypeVar, cast
+from typing import Any, Callable, Dict, List, Optional, TypeVar, cast
 
 from ._schema_utils import extract_function_metadata, extract_function_schemas
 from .context import Context
@@ -254,6 +254,86 @@ class WorkflowContext(Context):
 
         return result
 
+    async def wait_for_user(
+        self,
+        question: str,
+        input_type: str = "text",
+        options: Optional[List[Dict]] = None
+    ) -> str:
+        """
+        Pause workflow execution and wait for user input.
+
+        On replay (even after worker crash), resumes from this point
+        with the user's response. This method enables human-in-the-loop
+        workflows by pausing execution and waiting for user interaction.
+
+        Args:
+            question: Question to ask the user
+            input_type: Type of input - "text", "approval", or "choice"
+            options: For approval/choice, list of option dicts with 'id' and 'label'
+
+        Returns:
+            User's response string
+
+        Raises:
+            WaitingForUserInputException: When no cached response exists (first call)
+
+        Example (text input):
+            ```python
+            city = await ctx.wait_for_user("Which city?")
+            ```
+
+        Example (approval):
+            ```python
+            decision = await ctx.wait_for_user(
+                "Approve this action?",
+                input_type="approval",
+                options=[
+                    {"id": "approve", "label": "Approve"},
+                    {"id": "reject", "label": "Reject"}
+                ]
+            )
+            ```
+
+        Example (choice):
+            ```python
+            model = await ctx.wait_for_user(
+                "Which model?",
+                input_type="choice",
+                options=[
+                    {"id": "gpt4", "label": "GPT-4"},
+                    {"id": "claude", "label": "Claude"}
+                ]
+            )
+            ```
+        """
+        from .exceptions import WaitingForUserInputException
+
+        # Generate unique step name for this user input request
+        # Using run_id ensures uniqueness across workflow execution
+        response_key = f"user_response:{self.run_id}"
+
+        # Check if we already have the user's response (replay scenario)
+        if self._workflow_entity.has_completed_step(response_key):
+            response = self._workflow_entity.get_completed_step(response_key)
+            self._logger.info("🔄 Replaying user response from checkpoint")
+            return response
+
+        # No response yet - pause execution
+        # Collect current workflow state for checkpoint
+        checkpoint_state = {}
+        if hasattr(self._workflow_entity, '_state') and self._workflow_entity._state is not None:
+            checkpoint_state = self._workflow_entity._state.get_state_snapshot()
+
+        self._logger.info(f"⏸️  Pausing workflow for user input: {question}")
+
+        raise WaitingForUserInputException(
+            question=question,
+            input_type=input_type,
+            options=options,
+            checkpoint_state=checkpoint_state
+        )
+
 
 # ============================================================================
 # WorkflowEntity: Entity specialized for workflow execution state
@@ -337,6 +417,26 @@ class WorkflowEntity(Entity):
         """Check if step has been completed."""
         return step_name in self._completed_steps
 
+    def inject_user_response(self, response: str) -> None:
+        """
+        Inject user response as a completed step for workflow resume.
+
+        This method is called by the worker when resuming a paused workflow
+        with the user's response. It stores the response as if it was a
+        completed step, allowing wait_for_user() to retrieve it on replay.
+
+        Args:
+            response: User's response to inject
+
+        Example:
+            # Platform resumes workflow with user response
+            workflow_entity.inject_user_response("yes")
+            # On replay, wait_for_user() returns "yes" from cache
+        """
+        response_key = f"user_response:{self.run_id}"
+        self._completed_steps[response_key] = response
+        logger.info(f"Injected user response for {self.run_id}: {response}")
+
     @property
     def state(self) -> "WorkflowState":
         """
@@ -408,6 +508,14 @@ class WorkflowState(EntityState):
             "deleted": True
         })
 
+    def has_changes(self) -> bool:
+        """Check if any state changes have been tracked."""
+        return len(self._workflow_entity._state_changes) > 0
+
+    def get_state_snapshot(self) -> Dict[str, Any]:
+        """Get current state as a snapshot dictionary."""
+        return dict(self._state)
+
 
 class WorkflowRegistry:
     """Registry for workflow handlers."""

{agnt5-0.2.8a4.dist-info → agnt5-0.2.8a5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agnt5
-Version: 0.2.8a4
+Version: 0.2.8a5
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3

{agnt5-0.2.8a4.dist-info → agnt5-0.2.8a5.dist-info}/RECORD

@@ -1,22 +1,22 @@
-agnt5-0.2.8a4.dist-info/METADATA,sha256=Dp8yJo_dx5B79OM0ptGgR80TjCUbyovpSc4Pt57dfuY,996
-agnt5-0.2.8a4.dist-info/WHEEL,sha256=AdMozAxftELsa3nYun92mL1tYO-R1ewuDPju53zvoK0,107
-agnt5/__init__.py,sha256=ACkK91EPdnv5tYip09QCZ9rfV4iBKzNjGfYVLJD1XGg,2045
+agnt5-0.2.8a5.dist-info/METADATA,sha256=0yneaLrJFbpRR65wwR3XBaUy-KsJDFoi191gMrC1558,996
+agnt5-0.2.8a5.dist-info/WHEEL,sha256=AdMozAxftELsa3nYun92mL1tYO-R1ewuDPju53zvoK0,107
+agnt5/__init__.py,sha256=liMb9egh56qvgY4Xvs9s7grOzF3lXSE8-nIksJLNAy4,2195
 agnt5/_compat.py,sha256=BGuy3v5VDOHVa5f3Z-C22iMN19lAt0mPmXwF3qSSWxI,369
-agnt5/_core.abi3.so,sha256=CNmJC1AYLy8dABLguVfaWM6YqaTswjRnUZwM_07MXyk,15859720
+agnt5/_core.abi3.so,sha256=bMEWMgxWbi0KGt-9BJC34QqwWY3BHrHKQi_jgsDlmFU,15861440
 agnt5/_retry_utils.py,sha256=loHsWY5BR4wZy57IzcDEjQAy88DHVwVIr25Cn1d9GPA,5801
 agnt5/_schema_utils.py,sha256=MR67RW757T4Oq2Jqf4kB61H_b51zwaf3CLWELnkngRo,9572
 agnt5/_telemetry.py,sha256=bIY9AvBRjJBTHoBPbfR6X1OgaiUf-T0vCoi0_snsWXA,5957
-agnt5/agent.py,sha256=aBrhtPaUAHOHv3-h_Yb2UMqFHertr1P2hJ7fA_4IXcw,43225
+agnt5/agent.py,sha256=PuRq4cA8kJrBgrjRuDu62GBKJwefEjvndJZOj78_OGg,43293
 agnt5/client.py,sha256=kXksazgxdVXWaG9OkjJA4cWruNtcS-ENhtnkrIdw-Nk,23212
 agnt5/context.py,sha256=S2OzPkhn_jnqSWfT21mSYOux8vHaLKQxcAvggZDHQek,2378
 agnt5/entity.py,sha256=AlHmSHVxQD5EYBvkmERKUkwv0ERrKaT8rvRK611hv_I,28941
-agnt5/exceptions.py,sha256=mZ0q-NK6OKhYxgwBJpIbgpgzk-CJaFIHDbp1EE-pS7I,925
+agnt5/exceptions.py,sha256=2YB7o6B0FBW2S7x47HnV-HaaEYVSsjRDAdZ9_MSD8Tw,2431
 agnt5/function.py,sha256=f1vaAlJRwuo8cxCOGEd8XPido00mOhlPS8UJJx-6hJI,11041
 agnt5/lm.py,sha256=9dFjd6eQ3f3lFZe7H7rWZherYiP_58MT1F5xpwD8PCg,23195
-agnt5/tool.py,sha256=uc4L-Q9QyLzQDe-MZKk2Wo3o5e-mK8tfaQwVDgQdouQ,13133
+agnt5/tool.py,sha256=dkShd97Y1cwSOUnTwvL2gr0CW-usRlaq4frki9kREXI,18008
 agnt5/tracing.py,sha256=Mh2-OfnQM61lM_P8gxJstafdsUA8Gxoo1lP-Joxhub8,5980
 agnt5/types.py,sha256=Zb71ZMwvrt1p4SH18cAKunp2y5tao_W5_jGYaPDejQo,2840
 agnt5/version.py,sha256=rOq1mObLihnnKgKqBrwZA0zwOPudEKVFcW1a48ynkqc,573
-agnt5/worker.py,sha256=NflbueeL2LT8NGywTQnEv1r-N8f54AENWcZARJ5wO8o,47975
-agnt5/workflow.py,sha256=3s9CY6a4UkJZ9YyHv2SAkY3UeCVBlfVi7jxJMFi8Dhg,19488
-agnt5-0.2.8a4.dist-info/RECORD,,
+agnt5/worker.py,sha256=W5_yvy1vcflYjoPAGcIirbHXMbEXijXPJtGQOgl6oz4,51815
+agnt5/workflow.py,sha256=cDxKK21mLrsgjLGmosinhKnAme30CoQqs_fUFvRsyI0,23456
+agnt5-0.2.8a5.dist-info/RECORD,,