bedrock-agentcore-starter-toolkit 0.1.26__py3-none-any.whl → 0.1.27__py3-none-any.whl

bedrock_agentcore_starter_toolkit/notebook/runtime/bedrock_agentcore.py

@@ -6,12 +6,14 @@ from typing import Any, Dict, List, Literal, Optional
 
 from ...operations.runtime import (
     configure_bedrock_agentcore,
+    destroy_bedrock_agentcore,
     get_status,
     invoke_bedrock_agentcore,
     launch_bedrock_agentcore,
+    stop_runtime_session,
     validate_agent_name,
 )
-from ...operations.runtime.models import ConfigureResult, LaunchResult, StatusResult
+from ...operations.runtime.models import ConfigureResult, DestroyResult, LaunchResult, StatusResult
 
 # Setup centralized logging for SDK usage (notebooks, scripts, imports)
 from ...utils.logging_config import setup_toolkit_logging
@@ -48,8 +50,13 @@ class Runtime:
         region: Optional[str] = None,
         protocol: Optional[Literal["HTTP", "MCP", "A2A"]] = None,
         disable_otel: bool = False,
-        memory_mode: Literal["NO_MEMORY", "STM_ONLY", "STM_AND_LTM"] = "STM_ONLY",
+        memory_mode: Literal["NO_MEMORY", "STM_ONLY", "STM_AND_LTM"] = "NO_MEMORY",
         non_interactive: bool = True,
+        vpc_enabled: bool = False,
+        vpc_subnets: Optional[List[str]] = None,
+        vpc_security_groups: Optional[List[str]] = None,
+        idle_timeout: Optional[int] = None,
+        max_lifetime: Optional[int] = None,
     ) -> ConfigureResult:
         """Configure Bedrock AgentCore from notebook using an entrypoint file.
 
@@ -75,6 +82,11 @@ class Runtime:
                 - "STM_ONLY": Short-term memory only (default)
                 - "STM_AND_LTM": Short-term + long-term memory with strategy extraction
             non_interactive: Skip interactive prompts and use defaults (default: True)
+            vpc_enabled: Enable VPC networking mode (requires vpc_subnets and vpc_security_groups)
+            vpc_subnets: List of VPC subnet IDs (required if vpc_enabled=True)
+            vpc_security_groups: List of VPC security group IDs (required if vpc_enabled=True)
+            idle_timeout: Idle runtime session timeout in seconds (60-28800)
+            max_lifetime: Maximum instance lifetime in seconds (60-28800)
 
         Returns:
             ConfigureResult with configuration details
@@ -83,6 +95,14 @@ class Runtime:
             # Default: STM only (backward compatible)
             runtime.configure(entrypoint='handler.py')
 
+            # With VPC networking
+            runtime.configure(
+                entrypoint='handler.py',
+                vpc_enabled=True,
+                vpc_subnets=['subnet-abc123', 'subnet-def456'],
+                vpc_security_groups=['sg-xyz789']
+            )
+
             # Explicitly enable LTM
             runtime.configure(entrypoint='handler.py', memory_mode='STM_AND_LTM')
 
@@ -91,10 +111,60 @@ class Runtime:
 
             # Invalid - raises error
             runtime.configure(entrypoint='handler.py', disable_memory=True, memory_mode='STM_AND_LTM')
+
+            # With lifecycle settings
+            runtime.configure(
+                entrypoint='handler.py',
+                idle_timeout=1800,  # 30 minutes
+                max_lifetime=7200   # 2 hours
+            )
         """
         if protocol and protocol.upper() not in ["HTTP", "MCP", "A2A"]:
             raise ValueError("protocol must be either HTTP or MCP or A2A")
 
+        # Validate VPC configuration
+        if vpc_enabled:
+            if not vpc_subnets or not vpc_security_groups:
+                raise ValueError(
+                    "VPC mode requires both vpc_subnets and vpc_security_groups.\n"
+                    "Example: runtime.configure(entrypoint='handler.py', vpc_enabled=True, "
+                    "vpc_subnets=['subnet-abc123', 'subnet-def456'], "
+                    "vpc_security_groups=['sg-xyz789'])"
+                )
+
+            # Validate subnet ID format - UPDATED
+            for subnet_id in vpc_subnets:
+                if not subnet_id.startswith("subnet-"):
+                    raise ValueError(f"Invalid subnet ID format: {subnet_id}\nSubnet IDs must start with 'subnet-'")
+                if len(subnet_id) < 15:  # "subnet-" + 8 chars minimum
+                    raise ValueError(
+                        f"Invalid subnet ID format: {subnet_id}\n"
+                        f"Subnet ID is too short. Expected: subnet-xxxxxxxx (at least 8 hex chars)"
+                    )
+
+            # Validate security group ID format - UPDATED
+            for sg_id in vpc_security_groups:
+                if not sg_id.startswith("sg-"):
+                    raise ValueError(
+                        f"Invalid security group ID format: {sg_id}\nSecurity group IDs must start with 'sg-'"
+                    )
+                if len(sg_id) < 11:  # "sg-" + 8 chars minimum
+                    raise ValueError(
+                        f"Invalid security group ID format: {sg_id}\n"
+                        f"Security group ID is too short. Expected: sg-xxxxxxxx (at least 8 hex chars)"
+                    )
+
+            log.info(
+                "VPC mode enabled with %d subnets and %d security groups", len(vpc_subnets), len(vpc_security_groups)
+            )
+
+        elif vpc_subnets or vpc_security_groups:
+            raise ValueError(
+                "vpc_subnets and vpc_security_groups require vpc_enabled=True.\n"
+                "Use: runtime.configure(entrypoint='handler.py', vpc_enabled=True, "
+                "vpc_subnets=[...], vpc_security_groups=[...])"
+            )
+
         # Parse entrypoint to get agent name
         file_path, file_name = parse_entrypoint(entrypoint)
         agent_name = agent_name or file_name
@@ -152,6 +222,11 @@ class Runtime:
             region=region,
             protocol=protocol.upper() if protocol else None,
             non_interactive=non_interactive,
+            vpc_enabled=vpc_enabled,
+            vpc_subnets=vpc_subnets,
+            vpc_security_groups=vpc_security_groups,
+            idle_timeout=idle_timeout,
+            max_lifetime=max_lifetime,
         )
 
         self._config_path = result.config_path
@@ -319,6 +394,36 @@ class Runtime:
         )
         return result.response
 
+    def stop_session(self, session_id: Optional[str] = None) -> Dict[str, Any]:
+        """Stop an active runtime session.
+
+        Args:
+            session_id: Optional session ID to stop. If not provided, uses tracked session.
+
+        Returns:
+            Dictionary with stop session result details
+
+        Raises:
+            ValueError: If no session ID provided or found, or agent not configured
+        """
+        if not self._config_path:
+            log.warning("Agent not configured")
+            log.info("Call .configure() first to set up your agent")
+            raise ValueError("Must configure first. Call .configure() first.")
+
+        result = stop_runtime_session(
+            config_path=self._config_path,
+            session_id=session_id,
+        )
+
+        log.info("Session stopped: %s", result.session_id)
+        return {
+            "session_id": result.session_id,
+            "agent_name": result.agent_name,
+            "status_code": result.status_code,
+            "message": result.message,
+        }
+
     def status(self) -> StatusResult:
         """Get Bedrock AgentCore status including config and runtime details.
 
@@ -335,6 +440,76 @@ class Runtime:
         log.info("Retrieved Bedrock AgentCore status for: %s", self.name or "Bedrock AgentCore")
         return result
 
+    def destroy(
+        self,
+        dry_run: bool = False,
+        delete_ecr_repo: bool = False,
+    ) -> DestroyResult:
+        """Destroy Bedrock AgentCore resources from notebook.
+
+        Args:
+            dry_run: If True, only show what would be destroyed without actually doing it
+            delete_ecr_repo: If True, also delete the ECR repository after removing images
+
+        Returns:
+            DestroyResult with details of what was destroyed or would be destroyed
+
+        Example:
+            # Preview what would be destroyed
+            result = runtime.destroy(dry_run=True)
+
+            # Destroy resources (keeping ECR repository)
+            result = runtime.destroy()
+
+            # Destroy resources including ECR repository
+            result = runtime.destroy(delete_ecr_repo=True)
+        """
+        if not self._config_path:
+            log.warning("Configuration not found")
+            log.info("Call .configure() first to set up your agent")
+            log.info("Example: runtime.configure(entrypoint='my_agent.py')")
+            raise ValueError("Must configure first. Call .configure() first.")
+
+        if dry_run:
+            log.info("🔍 Dry run mode: showing what would be destroyed")
+        else:
+            log.info("🗑️ Destroying Bedrock AgentCore resources")
+            if delete_ecr_repo:
+                log.info("   • Including ECR repository deletion")
+
+        try:
+            result = destroy_bedrock_agentcore(
+                config_path=self._config_path,
+                agent_name=self.name,
+                dry_run=dry_run,
+                force=True,  # Always force in notebook interface to avoid interactive prompts
+                delete_ecr_repo=delete_ecr_repo,
+            )
+
+            # Log summary
+            if dry_run:
+                log.info("Dry run completed. Would destroy %d resources", len(result.resources_removed))
+            else:
+                log.info("Destroy completed. Removed %d resources", len(result.resources_removed))
+
+                # Clear our internal state if destruction was successful and not a dry run
+                if not result.errors:
+                    self._config_path = None
+                    self.name = None
+
+            # Log warnings and errors
+            for warning in result.warnings:
+                log.warning("⚠️ %s", warning)
+
+            for error in result.errors:
+                log.error("❌ %s", error)
+
+            return result
+
+        except Exception as e:
+            log.error("Destroy operation failed: %s", str(e))
+            raise
+
     def help_deployment_modes(self):
         """Display information about available deployment modes and migration guidance."""
         print("\n🚀 Bedrock AgentCore Deployment Modes:")
@@ -370,3 +545,66 @@ class Runtime:
         print("   runtime.launch()  # Uses CodeBuild by default")
         print('   runtime.invoke({"prompt": "Hello"})')
         print()
+
+    def help_vpc_networking(self):
+        """Display information about VPC networking configuration."""
+        print("\n🔒 VPC Networking for Bedrock AgentCore")
+        print("=" * 50)
+
+        print("\n📋 What is VPC Networking?")
+        print("   VPC (Virtual Private Cloud) mode allows your agent to:")
+        print("   • Access private resources (databases, internal APIs)")
+        print("   • Run in isolated network environments")
+        print("   • Comply with enterprise security requirements")
+
+        print("\n⚙️  Prerequisites:")
+        print("   You must have existing AWS resources:")
+        print("   • VPC with private subnets")
+        print("   • Security groups with appropriate rules")
+        print("   • (Optional) NAT Gateway for internet access")
+        print("   • (Optional) VPC endpoints for AWS services")
+
+        print("\n🚀 Basic Usage:")
+        print("   runtime.configure(")
+        print("       entrypoint='my_agent.py',")
+        print("       vpc_enabled=True,")
+        print("       vpc_subnets=['subnet-abc123', 'subnet-def456'],")
+        print("       vpc_security_groups=['sg-xyz789']")
+        print("   )")
+        print("   runtime.launch()")
+
+        print("\n📝 Requirements:")
+        print("   • All subnets must be in the same VPC")
+        print("   • Security groups must be in the same VPC as subnets")
+        print("   • Use subnets from multiple AZs for high availability")
+        print("   • Security groups must allow outbound HTTPS (443) traffic")
+
+        print("\n⚠️  Important Notes:")
+        print("   • Network configuration is IMMUTABLE after agent creation")
+        print("   • Cannot migrate existing PUBLIC agents to VPC mode")
+        print("   • Create a new agent if you need to change network settings")
+        print("   • Without NAT gateway, agent cannot pull container images")
+
+        print("\n🔍 Security Group Requirements:")
+        print("   Your security groups must allow:")
+        print("   • Outbound HTTPS (443) - for AWS API calls")
+        print("   • Outbound to your private resources (as needed)")
+        print("   • Inbound rules are typically not required")
+
+        print("\n💡 Example with All Features:")
+        print("   runtime.configure(")
+        print("       entrypoint='my_agent.py',")
+        print("       execution_role='arn:aws:iam::123456789012:role/MyRole',")
+        print("       vpc_enabled=True,")
+        print("       vpc_subnets=['subnet-abc123', 'subnet-def456'],")
+        print("       vpc_security_groups=['sg-xyz789'],")
+        print("       memory_mode='STM_AND_LTM'")
+        print("   )")
+
+        print("\n📚 Related Commands:")
+        print("   runtime.status()  # View network configuration")
+        print("   runtime.help_deployment_modes()  # Deployment options")
+
+        print("\n🔗 More Information:")
+        print("   See AWS VPC documentation for networking setup")
+        print()

bedrock_agentcore_starter_toolkit/operations/memory/manager.py

@@ -9,6 +9,7 @@ from typing import Any, Dict, List, Optional, Union
 import boto3
 from botocore.config import Config as BotocoreConfig
 from botocore.exceptions import ClientError
+from rich.console import Console
 
 from .constants import MemoryStatus, MemoryStrategyStatus, OverrideType, StrategyType
 from .models import convert_strategies_to_dicts
@@ -32,6 +33,7 @@ class MemoryManager:
         region_name: Optional[str] = None,
         boto3_session: Optional[boto3.Session] = None,
         boto_client_config: Optional[BotocoreConfig] = None,
+        console: Optional[Console] = None,
     ):
         """Initialize MemoryManager with AWS region.
 
@@ -42,12 +44,14 @@ class MemoryManager:
                           parameter is also specified, validation will ensure they match.
             boto_client_config: Optional boto3 client configuration. If provided, will be
                               merged with default configuration including user agent.
+            console: Optional Rich console instance for output (creates new if not provided)
 
         Raises:
             ValueError: If region_name parameter conflicts with boto3_session region.
         """
         session = boto3_session or boto3.Session()
         session_region = session.region_name
+        self.console = console or Console()
 
         # Validate region consistency if both are provided
         if region_name and boto3_session and session_region and region_name != session_region:
@@ -280,32 +284,7 @@ class MemoryManager:
         if memory_id is None:
             memory_id = ""
         logger.info("Created memory %s, waiting for ACTIVE status...", memory_id)
-
-        start_time = time.time()
-        while time.time() - start_time < max_wait:
-            elapsed = int(time.time() - start_time)
-
-            try:
-                status = self.get_memory_status(memory_id)
-
-                if status == MemoryStatus.ACTIVE.value:
-                    logger.info("Memory %s is now ACTIVE (took %d seconds)", memory_id, elapsed)
-                    return memory
-                elif status == MemoryStatus.FAILED.value:
-                    # Get failure reason if available
-                    response = self._control_plane_client.get_memory(memoryId=memory_id)
-                    failure_reason = response["memory"].get("failureReason", "Unknown")
-                    raise RuntimeError("Memory creation failed: %s" % failure_reason)
-                else:
-                    logger.debug("Memory status: %s (%d seconds elapsed)", status, elapsed)
-
-            except ClientError as e:
-                logger.error("Error checking memory status: %s", e)
-                raise
-
-            time.sleep(poll_interval)
-
-        raise TimeoutError(f"Memory {memory_id} did not become ACTIVE within {max_wait} seconds")
+        return self._wait_for_memory_active(memory_id, max_wait, poll_interval)
 
     def create_memory_and_wait(
         self,
@@ -1008,6 +987,8 @@ class MemoryManager:
         )
 
         start_time = time.time()
+        last_status_print = 0
+        status_print_interval = 10  # Print status every 10 seconds
 
         while time.time() - start_time < max_wait:
             elapsed = int(time.time() - start_time)
@@ -1029,13 +1010,18 @@ class MemoryManager:
                     self._check_strategies_terminal_state(strategies)
                 )
 
-                # Log current status
-                logger.debug(
-                    "Memory status: %s, Strategy statuses: %s (%d seconds elapsed)",
-                    memory_status,
-                    strategy_statuses,
-                    elapsed,
-                )
+                # Print status update every 10 seconds
+                if elapsed - last_status_print >= status_print_interval:
+                    if strategies:
+                        active_count = len([s for s in strategy_statuses if s == "ACTIVE"])
+                        self.console.log(
+                            f"   ⏳ Memory: {memory_status}, "
+                            f"Strategies: {active_count}/{len(strategies)} active "
+                            f"({elapsed}s elapsed)"
+                        )
+                    else:
+                        self.console.log(f"   ⏳ Memory: {memory_status} ({elapsed}s elapsed)")
+                    last_status_print = elapsed
 
                 # Check if memory is ACTIVE and all strategies are in terminal states
                 if memory_status == MemoryStatus.ACTIVE.value and all_strategies_terminal:
@@ -1048,6 +1034,7 @@ class MemoryManager:
                         memory_id,
                         elapsed,
                     )
+                    self.console.log(f"   ✅ Memory is ACTIVE (took {elapsed}s)")
                     return Memory(memory)
 
                 # Wait before next check

bedrock_agentcore_starter_toolkit/operations/memory/models/strategies/base.py

@@ -7,6 +7,7 @@ from pydantic import BaseModel, ConfigDict, Field
 
 if TYPE_CHECKING:
     from .custom import CustomSemanticStrategy, CustomSummaryStrategy, CustomUserPreferenceStrategy
+    from .self_managed import SelfManagedStrategy
     from .semantic import SemanticStrategy
     from .summary import SummaryStrategy
     from .user_preference import UserPreferenceStrategy
@@ -73,5 +74,6 @@ StrategyType = Union[
     "CustomSummaryStrategy",
     "CustomUserPreferenceStrategy",
     "UserPreferenceStrategy",
+    "SelfManagedStrategy",
     Dict[str, Any],  # Backward compatibility with dict-based strategies
 ]

bedrock_agentcore_starter_toolkit/operations/memory/models/strategies/self_managed.py

@@ -0,0 +1,107 @@
+"""Self managed memory strategy implementation."""
+
+from typing import Any, Dict, List, Union
+
+from pydantic import BaseModel, Field
+
+from .base import BaseStrategy
+
+
+class MessageBasedTrigger(BaseModel):
+    """Trigger configuration based on message."""
+
+    message_count: int = Field(default=6, description="Number of messages that trigger memory processing.")
+
+
+class TokenBasedTrigger(BaseModel):
+    """Trigger configuration based on tokens."""
+
+    token_count: int = Field(default=5000, description="Number of tokens that trigger memory processing.")
+
+
+class TimeBasedTrigger(BaseModel):
+    """Trigger configuration based on time."""
+
+    idle_session_timeout: int = Field(
+        default=20, description="Idle session timeout (seconds) that triggers memory processing."
+    )
+
+
+class InvocationConfig(BaseModel):
+    """Configuration to invoke customer-owned memory processing pipeline."""
+
+    topic_arn: str = Field(..., description="The ARN of the SNS topic for job notifications.")
+    payload_delivery_bucket_name: str = Field(..., description="S3 bucket name for event payload delivery.")
+
+
+class SelfManagedStrategy(BaseStrategy):
+    """Self-managed memory strategy with custom processing pipeline.
+
+    This strategy allows complete control over memory processing through
+    customer-owned pipelines triggered by configurable conditions.
+
+    Attributes:
+        trigger_conditions: List of conditions that trigger memory processing
+        invocation_config: Configuration for invoking memory processing pipeline
+        historical_context_window_size: Number of historical messages to include
+
+    Example:
+        strategy = SelfManagedStrategy(
+            name="SelfManagedStrategy",
+            description="Self-managed processing with SNS notifications",
+            trigger_conditions=[
+                MessageBasedTrigger(message_count=10),
+                TokenBasedTrigger(token_count=8000)
+            ],
+            invocation_config=InvocationConfig(
+                topic_arn="arn:aws:sns:us-east-1:123456789012:memory-processing",
+                payload_delivery_bucket_name="my-memory-bucket"
+            ),
+            historical_context_window_size=6
+        )
+    """
+
+    trigger_conditions: List[Union[MessageBasedTrigger, TokenBasedTrigger, TimeBasedTrigger]] = Field(
+        default_factory=list
+    )
+    invocation_config: InvocationConfig
+    historical_context_window_size: int = Field(
+        default=4, description="Number of historical messages to include in processing context."
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary format for API calls."""
+        config = {
+            "name": self.name,
+            "configuration": {
+                "selfManagedConfiguration": {
+                    "triggerConditions": self._convert_trigger_conditions(),
+                    "invocationConfiguration": self._convert_invocation_config(),
+                    "historicalContextWindowSize": self.historical_context_window_size,
+                }
+            },
+        }
+
+        if self.description is not None:
+            config["description"] = self.description
+
+        return {"customMemoryStrategy": config}
+
+    def _convert_trigger_conditions(self) -> List[Dict[str, Any]]:
+        """Convert trigger conditions to API format."""
+        conditions = []
+        for condition in self.trigger_conditions:
+            if isinstance(condition, MessageBasedTrigger):
+                conditions.append({"messageBasedTrigger": {"messageCount": condition.message_count}})
+            elif isinstance(condition, TokenBasedTrigger):
+                conditions.append({"tokenBasedTrigger": {"tokenCount": condition.token_count}})
+            elif isinstance(condition, TimeBasedTrigger):
+                conditions.append({"timeBasedTrigger": {"idleSessionTimeout": condition.idle_session_timeout}})
+        return conditions
+
+    def _convert_invocation_config(self) -> Dict[str, Any]:
+        """Convert invocation config to API format."""
+        return {
+            "topicArn": self.invocation_config.topic_arn,
+            "payloadDeliveryBucketName": self.invocation_config.payload_delivery_bucket_name,
+        }

bedrock_agentcore_starter_toolkit/operations/runtime/__init__.py

@@ -18,8 +18,10 @@ from .models import (
     LaunchResult,
     StatusConfigInfo,
     StatusResult,
+    StopSessionResult,
 )
 from .status import get_status
+from .stop_session import stop_runtime_session
 
 __all__ = [
     "configure_bedrock_agentcore",
@@ -31,6 +33,7 @@ __all__ = [
     "infer_agent_name",
     "launch_bedrock_agentcore",
     "invoke_bedrock_agentcore",
+    "stop_runtime_session",
     "get_status",
     "ConfigureResult",
     "DestroyResult",
@@ -38,4 +41,5 @@ __all__ = [
     "LaunchResult",
     "StatusResult",
     "StatusConfigInfo",
+    "StopSessionResult",
 ]