agnt5 0.2.8a4__cp310-abi3-manylinux_2_34_x86_64.whl → 0.2.8a6__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/_telemetry.py

@@ -73,10 +73,17 @@ class OpenTelemetryHandler(logging.Handler):
                 exc_text = self.formatException(record.exc_info)
                 message = f"{message}\n{exc_text}"
 
+            # Extract correlation IDs from LogRecord attributes (added by _CorrelationFilter)
+            # These ensure logs can be correlated with distributed traces in observability backends
+            trace_id = getattr(record, 'trace_id', None)
+            span_id = getattr(record, 'span_id', None)
+            run_id = getattr(record, 'run_id', None)
+
             # Forward to Rust tracing system
             # Rust side will:
             # - Add to current span context (inherits invocation.id)
-            # - Send to OTLP exporter
+            # - Attach correlation IDs as span attributes for OTLP export
+            # - Send to OTLP exporter with trace context
             # - Print to console via fmt layer
             self._log_from_python(
                 level=record.levelname,
@@ -84,7 +91,10 @@ class OpenTelemetryHandler(logging.Handler):
                 target=record.name,
                 module_path=record.module,
                 filename=record.pathname,
-                line=record.lineno
+                line=record.lineno,
+                trace_id=trace_id,
+                span_id=span_id,
+                run_id=run_id,
             )
         except Exception:
             # Don't let logging errors crash the application

agnt5/agent.py

@@ -9,7 +9,8 @@ from __future__ import annotations
 import functools
 import json
 import logging
-from typing import Any, Callable, Dict, List, Optional
+import time
+from typing import Any, Callable, Dict, List, Optional, Union
 
 from .context import Context
 from . import lm
@@ -85,7 +86,6 @@ class AgentContext(Context):
         if state_manager:
             # Explicit state adapter provided (parameter name kept for backward compat)
             self._state_adapter = state_manager
-            logger.debug(f"AgentContext using provided state adapter")
         elif parent_context:
             # Try to inherit state adapter from parent
             try:
@@ -93,38 +93,30 @@ class AgentContext(Context):
                 if hasattr(parent_context, '_workflow_entity'):
                     # WorkflowContext - get state adapter from worker context
                     self._state_adapter = _get_state_adapter()
-                    logger.debug(f"AgentContext inheriting state from WorkflowContext")
                 elif hasattr(parent_context, '_state_adapter'):
                     # Parent AgentContext - share state adapter
                     self._state_adapter = parent_context._state_adapter
-                    logger.debug(f"AgentContext inheriting state from parent AgentContext")
                 elif hasattr(parent_context, '_state_manager'):
                     # Backward compatibility: parent has old _state_manager
                     self._state_adapter = parent_context._state_manager
-                    logger.debug(f"AgentContext inheriting state from parent (legacy)")
                 else:
                     # FunctionContext or base Context - create new state adapter
                     self._state_adapter = EntityStateAdapter()
-                    logger.debug(f"AgentContext created new state adapter (parent has no state)")
             except RuntimeError as e:
                 # _get_state_adapter() failed (not in worker context) - create standalone
                 self._state_adapter = EntityStateAdapter()
-                logger.debug(f"AgentContext created standalone state adapter (not in worker context)")
         else:
             # Try to get from worker context first
             try:
                 self._state_adapter = _get_state_adapter()
-                logger.debug(f"AgentContext got state adapter from worker context")
             except RuntimeError as e:
                 # Standalone - create new state adapter
                 self._state_adapter = EntityStateAdapter()
-                logger.debug(f"AgentContext created standalone state adapter")
 
         # Conversation key for state storage (used for in-memory state)
         self._conversation_key = f"agent:{agent_name}:{self._session_id}:messages"
         # Entity key for database persistence (without :messages suffix to match API expectations)
         self._entity_key = f"agent:{agent_name}:{self._session_id}"
-        logger.debug(f"AgentContext initialized - session_id={self._session_id}")
 
     @property
     def state(self):
@@ -173,15 +165,12 @@ class AgentContext(Context):
         if isinstance(session_data, dict) and "messages" in session_data:
             # New format with session metadata
             messages_data = session_data["messages"]
-            logger.debug(f"Loaded {len(messages_data)} messages from session {entity_key}")
         elif isinstance(session_data, list):
             # Old format - just messages array
             messages_data = session_data
-            logger.debug(f"Loaded {len(messages_data)} messages (legacy format)")
         else:
             # No messages found
             messages_data = []
-            logger.debug(f"No conversation history found for {entity_key}")
 
         # Convert dict representations back to Message objects
         messages = []
@@ -214,17 +203,15 @@ class AgentContext(Context):
         Args:
             messages: List of Message objects to persist
         """
-        logger.debug(f"Saving {len(messages)} messages to conversation history")
-
         # Convert Message objects to dict for JSON serialization
         messages_data = []
         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
 
@@ -359,16 +346,23 @@ class Handoff:
         ```python
         specialist = Agent(name="specialist", ...)
 
-        # Create handoff configuration
-        handoff_to_specialist = Handoff(
-            agent=specialist,
-            description="Transfer to specialist for detailed analysis"
+        # Simple: Pass agent directly (auto-wrapped with defaults)
+        coordinator = Agent(
+            name="coordinator",
+            handoffs=[specialist]  # Agent auto-converted to Handoff
         )
 
-        # Use in coordinator agent
+        # Advanced: Use Handoff for custom configuration
         coordinator = Agent(
             name="coordinator",
-            handoffs=[handoff_to_specialist]
+            handoffs=[
+                Handoff(
+                    agent=specialist,
+                    description="Custom description for LLM",
+                    tool_name="custom_transfer_name",
+                    pass_full_history=False
+                )
+            ]
         )
         ```
     """
@@ -446,7 +440,6 @@ class AgentRegistry:
         if agent.name in _AGENT_REGISTRY:
             logger.warning(f"Overwriting existing agent '{agent.name}'")
         _AGENT_REGISTRY[agent.name] = agent
-        logger.debug(f"Registered agent '{agent.name}'")
 
     @staticmethod
     def get(name: str) -> Optional["Agent"]:
@@ -462,7 +455,6 @@ class AgentRegistry:
     def clear() -> None:
         """Clear all registered agents."""
         _AGENT_REGISTRY.clear()
-        logger.debug("Cleared agent registry")
 
 
 class AgentResult:
@@ -527,7 +519,7 @@ class Agent:
         model: Any,  # Can be string like "openai/gpt-4o-mini" OR LanguageModel instance
         instructions: str,
         tools: Optional[List[Any]] = None,
-        handoffs: Optional[List[Handoff]] = None,
+        handoffs: Optional[List[Union["Agent", Handoff]]] = None,  # Accept Agent or Handoff instances
         temperature: float = 0.7,
         max_tokens: Optional[int] = None,
         top_p: Optional[float] = None,
@@ -542,7 +534,7 @@ class Agent:
             model: Model string with provider prefix (e.g., "openai/gpt-4o-mini") OR LanguageModel instance
             instructions: System instructions for the agent
             tools: List of tools available to the agent (functions, Tool instances, or Agent instances)
-            handoffs: List of Handoff configurations for agent-to-agent delegation
+            handoffs: List of handoff configurations - can be Agent instances (auto-wrapped) or Handoff instances for custom config
             temperature: LLM temperature (0.0 to 1.0)
             max_tokens: Maximum tokens to generate
             top_p: Nucleus sampling parameter
@@ -572,8 +564,18 @@ class Agent:
         else:
             raise TypeError(f"model must be a string or LanguageModel instance, got {type(model)}")
 
-        # Store handoffs for building handoff tools
-        self.handoffs = handoffs or []
+        # Normalize handoffs: convert Agent instances to Handoff instances
+        self.handoffs: List[Handoff] = []
+        if handoffs:
+            for handoff_item in handoffs:
+                if isinstance(handoff_item, Agent):
+                    # Auto-wrap Agent in Handoff with sensible defaults
+                    self.handoffs.append(Handoff(agent=handoff_item))
+                    logger.info(f"Auto-wrapped agent '{handoff_item.name}' in Handoff for '{self.name}'")
+                elif isinstance(handoff_item, Handoff):
+                    self.handoffs.append(handoff_item)
+                else:
+                    raise TypeError(f"handoffs must contain Agent or Handoff instances, got {type(handoff_item)}")
 
         # Build tool registry (includes regular tools, agent-as-tools, and handoff tools)
         self.tools: Dict[str, Tool] = {}

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
@@ -611,7 +612,6 @@ class Worker:
             elif component_type == "function":
                 function_config = FunctionRegistry.get(component_name)
                 if function_config:
-                    logger.info(f"🔥 WORKER: Received request for function: {component_name}")
                     # Return coroutine, don't await it
                     return self._execute_function(function_config, input_data, request)
 
@@ -636,7 +636,6 @@ class Worker:
         from ._core import PyExecuteComponentResponse
 
         exec_start = time.time()
-        logger.info(f"🔥 WORKER: Executing function {config.name}")
 
         try:
             # Parse input data
@@ -654,26 +653,15 @@ class Worker:
                 runtime_context=request.runtime_context,
             )
 
-            # Create span for function execution with trace linking
-            from ._core import create_span
-
-            with create_span(
-                config.name,
-                "function",
-                request.runtime_context,
-                {
-                    "function.name": config.name,
-                    "service.name": self.service_name,
-                },
-            ) as span:
-                # Execute function
-                if input_dict:
-                    result = config.handler(ctx, **input_dict)
-                else:
-                    result = config.handler(ctx)
-
-                # Debug: Log what type result is
-                logger.info(f"🔥 WORKER: Function result type: {type(result).__name__}, isasyncgen: {inspect.isasyncgen(result)}, iscoroutine: {inspect.iscoroutine(result)}")
+            # Execute function directly - Rust bridge handles tracing
+            # Note: Removed Python-level span creation to avoid duplicate spans.
+            # The Rust worker bridge (sdk-python/rust-src/worker.rs:413-659) already
+            # creates a comprehensive OpenTelemetry span with all necessary attributes.
+            # See DUPLICATE_SPANS_FIX.md for details.
+            if input_dict:
+                result = config.handler(ctx, **input_dict)
+            else:
+                result = config.handler(ctx)
 
             # Note: Removed flush_telemetry_py() call here - it was causing 2-second blocking delay!
             # The batch span processor handles flushing automatically with 5s timeout
@@ -758,16 +746,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 +793,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 +806,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()
@@ -816,23 +829,14 @@ class Worker:
                 runtime_context=request.runtime_context,
             )
 
-            # Create span for workflow execution with trace linking
-            from ._core import create_span
-
-            with create_span(
-                config.name,
-                "workflow",
-                request.runtime_context,
-                {
-                    "workflow.name": config.name,
-                    "service.name": self.service_name,
-                },
-            ) as span:
-                # Execute workflow
-                if input_dict:
-                    result = await config.handler(ctx, **input_dict)
-                else:
-                    result = await config.handler(ctx)
+            # Execute workflow directly - Rust bridge handles tracing
+            # Note: Removed Python-level span creation to avoid duplicate spans.
+            # The Rust worker bridge creates comprehensive OpenTelemetry spans.
+            # See DUPLICATE_SPANS_FIX.md for details.
+            if input_dict:
+                result = await config.handler(ctx, **input_dict)
+            else:
+                result = await config.handler(ctx)
 
             # Note: Removed flush_telemetry_py() call here - it was causing 2-second blocking delay!
             # The batch span processor handles flushing automatically with 5s timeout
@@ -860,13 +864,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.8a6.dist-info}/METADATA

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

{agnt5-0.2.8a4.dist-info → agnt5-0.2.8a6.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.8a6.dist-info/METADATA,sha256=st25oz0S3w9locE4xf85jnN25ZtanIvYJJXTnckQ0QM,996
+agnt5-0.2.8a6.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=6xzh1gJ7PTU3-7Tt1Wnh9S_x-XWNTNj5tERSW58SeFQ,15809776
 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/_telemetry.py,sha256=gx4TQNqxeQwpyPWvgVVknPjx5NbenmR6E-DGCj18Ssw,6510
+agnt5/agent.py,sha256=ccV0rLj_9eF_G2VfrY8GWDBbNBadmDAYPrBJ6hMeuTE,43089
 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=jRguDRF0uTjYAmmAgmn3GtdEvIxgTuUoIOsme3ba6mU,51172
+agnt5/workflow.py,sha256=cDxKK21mLrsgjLGmosinhKnAme30CoQqs_fUFvRsyI0,23456
+agnt5-0.2.8a6.dist-info/RECORD,,