agnt5 0.2.8a2__cp310-abi3-macosx_10_12_x86_64.whl → 0.2.8a3__cp310-abi3-macosx_10_12_x86_64.whl

agnt5/__init__.py

@@ -7,6 +7,7 @@ with built-in durability guarantees and state management.
 
 from ._compat import _import_error, _rust_available
 from .agent import Agent, AgentContext, AgentRegistry, AgentResult, Handoff, agent, handoff
+from .agent_session import AgentSession
 from .client import Client, RunError
 from .context import Context
 from .function import FunctionContext
@@ -66,6 +67,7 @@ __all__ = [
     "Agent",
     "AgentRegistry",
     "AgentResult",
+    "AgentSession",
     "Handoff",
     "handoff",
     # Types

agnt5/agent.py

@@ -102,17 +102,25 @@ class AgentContext(Context):
                     # FunctionContext or base Context - create new state manager
                     self._state_manager = EntityStateManager()
                     logger.debug(f"AgentContext created new state manager (parent has no state)")
-            except RuntimeError:
+            except RuntimeError as e:
                 # _get_state_manager() failed (not in worker context) - create standalone
                 self._state_manager = EntityStateManager()
-                logger.debug(f"AgentContext created standalone state manager")
+                logger.debug(f"AgentContext created standalone state manager (not in worker context)")
         else:
-            # Standalone - create new state manager
-            self._state_manager = EntityStateManager()
-            logger.debug(f"AgentContext created standalone state manager")
+            # Try to get from worker context first
+            try:
+                self._state_manager = _get_state_manager()
+                logger.debug(f"AgentContext got state manager from worker context")
+            except RuntimeError as e:
+                # Standalone - create new state manager
+                self._state_manager = EntityStateManager()
+                logger.debug(f"AgentContext created standalone state manager")
 
-        # Conversation key for state storage
+        # 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):
@@ -143,14 +151,49 @@ class AgentContext(Context):
         """Get session identifier for this agent context."""
         return self._session_id
 
-    def get_conversation_history(self) -> List[Message]:
+    async def get_conversation_history(self) -> List[Message]:
         """
-        Retrieve conversation history from state.
+        Retrieve conversation history from state, loading from database if needed.
 
         Returns:
             List of Message objects from conversation history
         """
+        # Try to load from database first if not in memory
+        entity_type = "AgentSession"
+        entity_key = self._entity_key  # Use entity_key without :messages suffix
+        state_key = (entity_type, entity_key)
+
+        # Check if we need to load from platform
+        if state_key not in self._state_manager._states and self._state_manager._rust_manager:
+            try:
+                result = await self._state_manager._rust_manager.py_load_state(
+                    entity_type, entity_key
+                )
+                found, state_json_bytes, version = result
+                if found:
+                    import json
+                    state_json = state_json_bytes.decode('utf-8') if isinstance(state_json_bytes, bytes) else state_json_bytes
+                    session_data = json.loads(state_json)
+
+                    # Extract messages from session object (might be old format or new format)
+                    if isinstance(session_data, dict) and "messages" in session_data:
+                        # New format with session metadata
+                        messages_data = session_data["messages"]
+                    elif isinstance(session_data, list):
+                        # Old format - just messages array
+                        messages_data = session_data
+                    else:
+                        messages_data = []
+
+                    # Load messages into in-memory state (store just messages, not full session object)
+                    self._state_manager.load_state_from_platform(state_key, json.dumps(messages_data), version)
+                    logger.info(f"Loaded conversation history from database: {entity_key} (version {version})")
+            except Exception as e:
+                logger.warning(f"Failed to load conversation history from database: {e}")
+
+        # Get from in-memory state
         messages_data = self.state.get(self._conversation_key, [])
+        logger.debug(f"Loaded {len(messages_data)} messages from conversation history")
 
         # Convert dict representations back to Message objects
         messages = []
@@ -174,13 +217,15 @@ class AgentContext(Context):
 
         return messages
 
-    def save_conversation_history(self, messages: List[Message]) -> None:
+    async def save_conversation_history(self, messages: List[Message]) -> None:
         """
-        Save conversation history to state.
+        Save conversation history to state and persist to database.
 
         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:
@@ -189,8 +234,47 @@ class AgentContext(Context):
                 "content": msg.content
             })
 
+        # Save to in-memory state
         self.state.set(self._conversation_key, messages_data)
 
+        # Persist to database via Rust EntityStateManager
+        if self._state_manager._rust_manager:
+            try:
+                import json
+                import time
+                entity_type = "AgentSession"
+                entity_key = self._entity_key  # Use entity_key without :messages suffix
+                state_key = (entity_type, entity_key)
+
+                # Get current version
+                expected_version = self._state_manager._versions.get(state_key, 0)
+
+                # Build session object with metadata for the sessions API
+                now = time.time()
+                session_data = {
+                    "session_id": self._session_id,
+                    "agent_name": self._agent_name,
+                    "created_at": now if expected_version == 0 else None,  # Only set on first save
+                    "last_message_time": now,
+                    "message_count": len(messages_data),
+                    "messages": messages_data,
+                    "metadata": {}
+                }
+
+                # Serialize to JSON bytes
+                state_json = json.dumps(session_data).encode('utf-8')
+
+                # Save to platform
+                new_version = await self._state_manager._rust_manager.py_save_state(
+                    entity_type, entity_key, state_json, expected_version
+                )
+
+                # Update version tracking
+                self._state_manager._versions[state_key] = new_version
+                logger.info(f"Persisted conversation history to database: {entity_key} (version {expected_version} -> {new_version})")
+            except Exception as e:
+                logger.error(f"Failed to persist conversation history to database: {e}")
+
 
 class Handoff:
     """Configuration for agent-to-agent handoff.
@@ -665,11 +749,11 @@ class Agent:
 
         # Load conversation history from state (if AgentContext)
         if isinstance(context, AgentContext):
-            messages: List[Message] = context.get_conversation_history()
+            messages: List[Message] = await context.get_conversation_history()
             # Add new user message
             messages.append(Message.user(user_message))
             # Save updated conversation
-            context.save_conversation_history(messages)
+            await context.save_conversation_history(messages)
         else:
             # Fallback for non-AgentContext (shouldn't happen with code above)
             messages = [Message.user(user_message)]
@@ -795,7 +879,7 @@ class Agent:
                                     )
                                     # Save conversation before returning
                                     if isinstance(context, AgentContext):
-                                        context.save_conversation_history(messages)
+                                        await context.save_conversation_history(messages)
                                     # Return immediately with handoff result
                                     return AgentResult(
                                         output=result["output"],
@@ -835,7 +919,7 @@ class Agent:
                     self.logger.debug(f"Agent completed after {iteration + 1} iterations")
                     # Save conversation before returning
                     if isinstance(context, AgentContext):
-                        context.save_conversation_history(messages)
+                        await context.save_conversation_history(messages)
                     return AgentResult(
                         output=response.text,
                         tool_calls=all_tool_calls,
@@ -847,7 +931,7 @@ class Agent:
             final_output = messages[-1].content if messages else "No output generated"
             # Save conversation before returning
             if isinstance(context, AgentContext):
-                context.save_conversation_history(messages)
+                await context.save_conversation_history(messages)
             return AgentResult(
                 output=final_output,
                 tool_calls=all_tool_calls,

agnt5/agent_session.py

@@ -0,0 +1,110 @@
+"""Agent session management for multi-turn conversations.
+
+Provides AgentSession entity to track and persist conversation metadata
+across multiple agent invocations. Session state is backed by the entity
+infrastructure for durability.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional, Dict, Any
+
+from .entity import Entity
+
+
+class AgentSession(Entity):
+    """
+    Entity representing an agent conversation session.
+
+    Tracks metadata about multi-turn conversations including:
+    - Session creation and last activity timestamps
+    - Message count
+    - Agent identification
+    - Custom metadata
+
+    The actual conversation messages are stored separately in AgentContext
+    using the session_id as the key. This entity only tracks session metadata.
+
+    Example:
+        ```python
+        # Create new session
+        session = AgentSession("session-123")
+        session.create(agent_name="tutor", metadata={"user_id": "user-456"})
+
+        # Update on each message
+        session.add_message()
+
+        # Get session summary
+        summary = session.get_summary()
+        ```
+    """
+
+    def __init__(self, session_id: str):
+        """
+        Initialize agent session entity.
+
+        Args:
+            session_id: Unique session identifier
+        """
+        self.session_id = session_id
+        self.agent_name: str = ""
+        self.created_at: float = 0.0
+        self.last_message_time: float = 0.0
+        self.message_count: int = 0
+        self.metadata: Dict[str, Any] = {}
+
+    def create(self, agent_name: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Initialize a new session.
+
+        Args:
+            agent_name: Name of the agent for this session
+            metadata: Optional additional session metadata
+        """
+        current_time = time.time()
+        self.agent_name = agent_name
+        self.created_at = current_time
+        self.last_message_time = current_time
+        self.message_count = 0
+        self.metadata = metadata or {}
+
+    def add_message(self) -> None:
+        """
+        Record a new message in the session.
+
+        Updates message count and last activity timestamp.
+        """
+        self.message_count += 1
+        self.last_message_time = time.time()
+
+    def get_summary(self) -> Dict[str, Any]:
+        """
+        Get session metadata summary.
+
+        Returns:
+            Dictionary with session metadata including:
+            - session_id
+            - agent_name
+            - created_at
+            - last_message_time
+            - message_count
+            - metadata
+        """
+        return {
+            "session_id": self.session_id,
+            "agent_name": self.agent_name,
+            "created_at": self.created_at,
+            "last_message_time": self.last_message_time,
+            "message_count": self.message_count,
+            "metadata": self.metadata,
+        }
+
+    def update_metadata(self, metadata: Dict[str, Any]) -> None:
+        """
+        Update session metadata.
+
+        Args:
+            metadata: Metadata to merge into existing metadata
+        """
+        self.metadata.update(metadata)

agnt5/entity.py

@@ -497,15 +497,25 @@ def _create_entity_method_wrapper(entity_type: str, method):
         lock = state_manager.get_or_create_lock(state_key)
 
         async with lock:
-            # TODO: Load state from platform if not in memory
-            # if state_key not in state_manager._states and state_manager._rust_manager:
-            #     result = await state_manager._rust_manager.load_state(
-            #         tenant_id, entity_type, self._key
-            #     )
-            #     if result.found:
-            #         state_manager.load_state_from_platform(
-            #             state_key, result.state_json, result.version
-            #         )
+            # Load state from platform if not in memory
+            if state_key not in state_manager._states and state_manager._rust_manager:
+                try:
+                    # Call Rust manager to load state from platform
+                    result = await state_manager._rust_manager.py_load_state(
+                        entity_type, self._key
+                    )
+                    # result is a tuple: (found, state_json, version)
+                    found, state_json_bytes, version = result
+                    if found:
+                        # Decode and load state
+                        state_json = state_json_bytes.decode('utf-8') if isinstance(state_json_bytes, bytes) else state_json_bytes
+                        state_manager.load_state_from_platform(
+                            state_key, state_json, version
+                        )
+                        logger.info(f"Loaded entity state from platform: {entity_type}:{self._key} (version {version})")
+                except Exception as e:
+                    logger.warning(f"Failed to load entity state from platform: {e}")
+                    # Continue with empty state
 
             # Get or create state for this entity instance
             state_dict = state_manager.get_or_create_state(state_key)
@@ -519,16 +529,25 @@ def _create_entity_method_wrapper(entity_type: str, method):
                 result = await method(self, *args, **kwargs)
                 logger.debug("Completed %s:%s.%s", entity_type, self._key, method.__name__)
 
-                # TODO: Save state to platform after successful execution
-                # if state_manager._rust_manager:
-                #     state_dict, expected_version, new_version = \
-                #         state_manager.get_state_for_persistence(state_key)
-                #     import json
-                #     state_json = json.dumps(state_dict).encode('utf-8')
-                #     save_result = await state_manager._rust_manager.save_state(
-                #         tenant_id, entity_type, self._key, state_json, expected_version
-                #     )
-                #     state_manager._versions[state_key] = save_result.new_version
+                # Save state to platform after successful execution
+                if state_manager._rust_manager:
+                    try:
+                        import json
+                        # Get current version
+                        expected_version = state_manager._versions.get(state_key, 0)
+                        # Serialize state
+                        state_json = json.dumps(state_dict).encode('utf-8')
+                        # Call Rust manager to save state
+                        new_version = await state_manager._rust_manager.py_save_state(
+                            entity_type, self._key, state_json, expected_version
+                        )
+                        # Update version
+                        state_manager._versions[state_key] = new_version
+                        logger.info(f"Saved entity state to platform: {entity_type}:{self._key} (version {expected_version} -> {new_version})")
+                    except Exception as e:
+                        logger.error(f"Failed to save entity state to platform: {e}")
+                        # Don't fail the method execution just because persistence failed
+                        # The state is still in memory
 
                 return result
 

agnt5/worker.py

@@ -128,10 +128,11 @@ class Worker:
 
         # Import Rust worker
         try:
-            from ._core import PyWorker, PyWorkerConfig, PyComponentInfo
+            from ._core import PyWorker, PyWorkerConfig, PyComponentInfo, EntityStateManager as RustEntityStateManager
             self._PyWorker = PyWorker
             self._PyWorkerConfig = PyWorkerConfig
             self._PyComponentInfo = PyComponentInfo
+            self._RustEntityStateManager = RustEntityStateManager
         except ImportError as e:
             raise ImportError(
                 f"Failed to import Rust core worker: {e}. "
@@ -148,9 +149,16 @@ class Worker:
         # Create Rust worker instance
         self._rust_worker = self._PyWorker(self._rust_config)
 
-        # Create worker-scoped entity state manager
+        # Get tenant_id for entity state manager
+        import os
+        tenant_id = os.getenv("AGNT5_TENANT_ID", "00000000-0000-0000-0000-000000000001")
+
+        # Create Rust entity state manager
+        self._rust_entity_state_manager = self._RustEntityStateManager(tenant_id)
+
+        # Create worker-scoped entity state manager with Rust manager
         from .entity import EntityStateManager
-        self._entity_state_manager = EntityStateManager()
+        self._entity_state_manager = EntityStateManager(rust_entity_state_manager=self._rust_entity_state_manager)
 
         # Component registration: auto-discover or explicit
         if auto_register:
@@ -1027,11 +1035,16 @@ class Worker:
             )
 
     async def _execute_agent(self, agent, input_data: bytes, request):
-        """Execute an agent."""
+        """Execute an agent with session support for multi-turn conversations."""
         import json
-        from .context import Context
+        import uuid
+        from .agent import AgentContext
+        from .entity import _entity_state_manager_ctx
         from ._core import PyExecuteComponentResponse
 
+        # Set entity state manager in context so AgentContext can access it
+        _entity_state_manager_ctx.set(self._entity_state_manager)
+
         try:
             # Parse input data
             input_dict = json.loads(input_data.decode("utf-8")) if input_data else {}
@@ -1041,16 +1054,30 @@ class Worker:
             if not user_message:
                 raise ValueError("Agent invocation requires 'message' parameter")
 
-            # Create context with runtime_context for trace correlation
-            ctx = Context(
-                run_id=f"{self.service_name}:{agent.name}",
+            # Extract or generate session_id for multi-turn conversation support
+            # If session_id is provided, the agent will load previous conversation history
+            # If not provided, a new session is created with auto-generated ID
+            session_id = input_dict.get("session_id")
+
+            if not session_id:
+                session_id = str(uuid.uuid4())
+                logger.info(f"Created new agent session: {session_id}")
+            else:
+                logger.info(f"Using existing agent session: {session_id}")
+
+            # Create AgentContext with session support for conversation persistence
+            # AgentContext automatically loads/saves conversation history based on session_id
+            ctx = AgentContext(
+                run_id=request.invocation_id,
+                agent_name=agent.name,
+                session_id=session_id,
                 runtime_context=request.runtime_context,
             )
 
-            # Execute agent
+            # Execute agent - conversation history is automatically included
             agent_result = await agent.run(user_message, context=ctx)
 
-            # Build response
+            # Build response with agent output and tool calls
             result = {
                 "output": agent_result.output,
                 "tool_calls": agent_result.tool_calls,
@@ -1059,13 +1086,16 @@ class Worker:
             # Serialize result
             output_data = json.dumps(result).encode("utf-8")
 
+            # Return session_id in metadata so UI can persist it
+            metadata = {"session_id": session_id}
+
             return PyExecuteComponentResponse(
                 invocation_id=request.invocation_id,
                 success=True,
                 output_data=output_data,
                 state_update=None,
                 error_message=None,
-                metadata=None,
+                metadata=metadata,
                 is_chunk=False,
                 done=True,
                 chunk_index=0,
@@ -1127,6 +1157,10 @@ class Worker:
         if self.metadata:
             self._rust_worker.set_service_metadata(self.metadata)
 
+        # Set entity state manager on Rust worker for database persistence
+        logger.info("Configuring entity state manager for database persistence")
+        self._rust_worker.set_entity_state_manager(self._rust_entity_state_manager)
+
         # Get the current event loop to pass to Rust for concurrent Python async execution
         # This allows Rust to execute Python async functions on the same event loop
         # without spawn_blocking overhead, enabling true concurrency

{agnt5-0.2.8a2.dist-info → agnt5-0.2.8a3.dist-info}/METADATA

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

{agnt5-0.2.8a2.dist-info → agnt5-0.2.8a3.dist-info}/RECORD

@@ -1,15 +1,16 @@
-agnt5-0.2.8a2.dist-info/METADATA,sha256=1Lj5nOz64iKpWdMoxTRlt_DB4QavSlWDrqqjZXzH11c,996
-agnt5-0.2.8a2.dist-info/WHEEL,sha256=eZxluNosN814qqPoiTnB1GwMrzvnR_7wE3Goh6BHRg8,105
-agnt5/__init__.py,sha256=Cscbhye6pA8Jp-sKBGfP4kYXElUdF6aOSHVf-7ph4Dg,2045
+agnt5-0.2.8a3.dist-info/METADATA,sha256=CSD_9YZ9vmaRf7sXcVSefdJ2YeIZnwQ2PZCohtvv5TY,996
+agnt5-0.2.8a3.dist-info/WHEEL,sha256=eZxluNosN814qqPoiTnB1GwMrzvnR_7wE3Goh6BHRg8,105
+agnt5/__init__.py,sha256=dlJ3rUXiWIZMd0LpGGhgaItkdYlcp3yuEufQb-Yqh9A,2105
 agnt5/_compat.py,sha256=BGuy3v5VDOHVa5f3Z-C22iMN19lAt0mPmXwF3qSSWxI,369
-agnt5/_core.abi3.so,sha256=UJwjlDs1Fwfa4wRggs9-vliCm1nOZ6hdox9EP9e0kM0,12292560
+agnt5/_core.abi3.so,sha256=-OEUHiGnOMzN5khT65z0mb1clTG8fOV7_urZe6N-KPY,12533812
 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=cz9gDB6c-eRJhBihEIuvTnNBwonpH6G8lbm44j_DKgA,36704
+agnt5/agent.py,sha256=fLX8k7cJ5-OKF9OU0Ykd__62mGFrYuToGUK0UdpNtas,41171
+agnt5/agent_session.py,sha256=mZ61mVax6Wt1ArocwdVEx4Kju6veFYtqxtSNWeKOve0,3161
 agnt5/client.py,sha256=kXksazgxdVXWaG9OkjJA4cWruNtcS-ENhtnkrIdw-Nk,23212
 agnt5/context.py,sha256=S2OzPkhn_jnqSWfT21mSYOux8vHaLKQxcAvggZDHQek,2378
-agnt5/entity.py,sha256=jMnSRTv6MNlK05cJ0FWYQR89ZTz_ywtVuwv-Sjr2Jfc,24925
+agnt5/entity.py,sha256=KXSDklsqe9PoIKGz4hZpcmHJFLJKGe0Am8-3FH72Fxk,26150
 agnt5/exceptions.py,sha256=mZ0q-NK6OKhYxgwBJpIbgpgzk-CJaFIHDbp1EE-pS7I,925
 agnt5/function.py,sha256=f1vaAlJRwuo8cxCOGEd8XPido00mOhlPS8UJJx-6hJI,11041
 agnt5/lm.py,sha256=9dFjd6eQ3f3lFZe7H7rWZherYiP_58MT1F5xpwD8PCg,23195
@@ -17,6 +18,6 @@ agnt5/tool.py,sha256=uc4L-Q9QyLzQDe-MZKk2Wo3o5e-mK8tfaQwVDgQdouQ,13133
 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=gIbYOdmOczNAqCgErzfLqIukbCpOutdOTZSWv_BatkU,46777
+agnt5/worker.py,sha256=ALX8g8ij4GZ465mgEa17CO9I7Ybysv8w9uJWQRSd3g8,48685
 agnt5/workflow.py,sha256=sU8Gk7unxE_Gla7Fe-KlXfcBvYa2326GciuoR26CCr0,19585
-agnt5-0.2.8a2.dist-info/RECORD,,
+agnt5-0.2.8a3.dist-info/RECORD,,