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

bedrock_agentcore_starter_toolkit/cli/cli.py

@@ -5,7 +5,14 @@ import typer
 from ..cli.gateway.commands import create_mcp_gateway, create_mcp_gateway_target, gateway_app
 from ..utils.logging_config import setup_toolkit_logging
 from .import_agent.commands import import_agent
-from .runtime.commands import configure_app, destroy, invoke, launch, status
+from .runtime.commands import (
+    configure_app,
+    destroy,
+    invoke,
+    launch,
+    status,
+    stop_session,
+)
 
 app = typer.Typer(name="agentcore", help="BedrockAgentCore CLI", add_completion=False, rich_markup_mode="rich")
 
@@ -18,6 +25,7 @@ app.command("status")(status)
 app.command("launch")(launch)
 app.command("import-agent")(import_agent)
 app.command("destroy")(destroy)
+app.command("stop-session")(stop_session)
 app.add_typer(configure_app)
 
 # gateway

bedrock_agentcore_starter_toolkit/cli/runtime/commands.py

@@ -4,6 +4,7 @@ import json
 import logging
 import os
 from pathlib import Path
+from threading import Thread
 from typing import List, Optional
 
 import typer
@@ -12,6 +13,7 @@ from prompt_toolkit.completion import PathCompleter
 from rich.panel import Panel
 from rich.syntax import Syntax
 
+from ...operations.identity.oauth2_callback_server import start_oauth2_callback_server
 from ...operations.runtime import (
     configure_bedrock_agentcore,
     destroy_bedrock_agentcore,
@@ -255,6 +257,33 @@ def configure(
         help="Comma-separated list of allowed request headers "
         "(Authorization or X-Amzn-Bedrock-AgentCore-Runtime-Custom-*)",
     ),
+    vpc: bool = typer.Option(
+        False, "--vpc", help="Enable VPC networking mode (requires --subnets and --security-groups)"
+    ),
+    subnets: Optional[str] = typer.Option(
+        None,
+        "--subnets",
+        help="Comma-separated list of subnet IDs (e.g., subnet-abc123,subnet-def456). Required with --vpc.",
+    ),
+    security_groups: Optional[str] = typer.Option(
+        None,
+        "--security-groups",
+        help="Comma-separated list of security group IDs (e.g., sg-xyz789). Required with --vpc.",
+    ),
+    idle_timeout: Optional[int] = typer.Option(
+        None,
+        "--idle-timeout",
+        help="Idle runtime session timeout in seconds (60-28800, default: 900)",
+        min=60,
+        max=28800,
+    ),
+    max_lifetime: Optional[int] = typer.Option(
+        None,
+        "--max-lifetime",
+        help="Maximum instance lifetime in seconds (60-28800, default: 28800)",
+        min=60,
+        max=28800,
+    ),
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output"),
     region: Optional[str] = typer.Option(None, "--region", "-r"),
     protocol: Optional[str] = typer.Option(None, "--protocol", "-p", help="Server protocol (HTTP or MCP or A2A)"),
@@ -275,6 +304,64 @@ def configure(
     if protocol and protocol.upper() not in ["HTTP", "MCP", "A2A"]:
         _handle_error("Error: --protocol must be either HTTP or MCP or A2A")
 
+    # Validate VPC configuration
+    vpc_subnets = None
+    vpc_security_groups = None
+
+    if vpc:
+        # VPC mode requires both subnets and security groups
+        if not subnets or not security_groups:
+            _handle_error(
+                "VPC mode requires both --subnets and --security-groups.\n"
+                "Example: agentcore configure --entrypoint my_agent.py --vpc "
+                "--subnets subnet-abc123,subnet-def456 --security-groups sg-xyz789"
+            )
+
+        # Parse and validate subnet IDs - UPDATED VALIDATION
+        vpc_subnets = [s.strip() for s in subnets.split(",") if s.strip()]
+        for subnet_id in vpc_subnets:
+            # Format: subnet-{8-17 hex characters}
+            if not subnet_id.startswith("subnet-"):
+                _handle_error(
+                    f"Invalid subnet ID format: {subnet_id}\nSubnet IDs must start with 'subnet-' (e.g., subnet-abc123)"
+                )
+            # Check minimum length (subnet- + at least 8 chars)
+            if len(subnet_id) < 15:  # "subnet-" (7) + 8 chars = 15
+                _handle_error(
+                    f"Invalid subnet ID format: {subnet_id}\nSubnet ID is too short. Expected format: subnet-xxxxxxxx"
+                )
+
+        # Parse and validate security group IDs - UPDATED VALIDATION
+        vpc_security_groups = [sg.strip() for sg in security_groups.split(",") if sg.strip()]
+        for sg_id in vpc_security_groups:
+            # Format: sg-{8-17 hex characters}
+            if not sg_id.startswith("sg-"):
+                _handle_error(
+                    f"Invalid security group ID format: {sg_id}\n"
+                    f"Security group IDs must start with 'sg-' (e.g., sg-abc123)"
+                )
+            # Check minimum length (sg- + at least 8 chars)
+            if len(sg_id) < 11:  # "sg-" (3) + 8 chars = 11
+                _handle_error(
+                    f"Invalid security group ID format: {sg_id}\n"
+                    f"Security group ID is too short. Expected format: sg-xxxxxxxx"
+                )
+
+        _print_success(
+            f"VPC mode enabled with {len(vpc_subnets)} subnets and {len(vpc_security_groups)} security groups"
+        )
+
+    elif subnets or security_groups:
+        # Error: VPC resources provided without --vpc flag
+        _handle_error(
+            "The --subnets and --security-groups flags require --vpc flag.\n"
+            "Use: agentcore configure --entrypoint my_agent.py --vpc --subnets ... --security-groups ..."
+        )
+    # Validate lifecycle configuration
+    if idle_timeout is not None and max_lifetime is not None:
+        if idle_timeout > max_lifetime:
+            _handle_error(f"Error: --idle-timeout ({idle_timeout}s) must be <= --max-lifetime ({max_lifetime}s)")
+
     console.print("[cyan]Configuring Bedrock AgentCore...[/cyan]")
 
     # Create configuration manager early for consistent prompting
@@ -397,6 +484,11 @@ def configure(
             protocol=protocol.upper() if protocol else None,
             non_interactive=non_interactive,
             source_path=source_path,
+            vpc_enabled=vpc,
+            vpc_subnets=vpc_subnets,
+            vpc_security_groups=vpc_security_groups,
+            idle_timeout=idle_timeout,
+            max_lifetime=max_lifetime,
         )
 
         # Prepare authorization info for summary
@@ -410,10 +502,29 @@ def configure(
             headers = request_header_config.get("requestHeaderAllowlist", [])
             headers_info = f"Request Headers Allowlist: [dim]{len(headers)} headers configured[/dim]\n"
 
+        network_info = "Public"
+        if vpc:
+            network_info = f"VPC ({len(vpc_subnets)} subnets, {len(vpc_security_groups)} security groups)"
+
         execution_role_display = "Auto-create" if not result.execution_role else result.execution_role
-        memory_info = "Short-term memory (30-day retention)"
-        if disable_memory:
+        saved_config = load_config(result.config_path)
+        saved_agent = saved_config.get_agent_config(agent_name)
+
+        # Display memory status based on actual configuration
+        if saved_agent.memory.mode == "NO_MEMORY":
             memory_info = "Disabled"
+        elif saved_agent.memory.mode == "STM_AND_LTM":
+            memory_info = "Short-term + Long-term memory (30-day retention)"
+        else:  # STM_ONLY
+            memory_info = "Short-term memory (30-day retention)"
+
+        lifecycle_info = ""
+        if idle_timeout or max_lifetime:
+            lifecycle_info = "\n[bold]Lifecycle Settings:[/bold]\n"
+            if idle_timeout:
+                lifecycle_info += f"Idle Timeout: [cyan]{idle_timeout}s ({idle_timeout // 60} minutes)[/cyan]\n"
+            if max_lifetime:
+                lifecycle_info += f"Max Lifetime: [cyan]{max_lifetime}s ({max_lifetime // 3600} hours)[/cyan]\n"
 
         console.print(
             Panel(
@@ -427,9 +538,11 @@ def configure(
                 f"ECR Repository: [cyan]"
                 f"{'Auto-create' if result.auto_create_ecr else result.ecr_repository or 'N/A'}"
                 f"[/cyan]\n"
+                f"Network Mode: [cyan]{network_info}[/cyan]\n"
                 f"Authorization: [cyan]{auth_info}[/cyan]\n\n"
                 f"{headers_info}\n"
                 f"Memory: [cyan]{memory_info}[/cyan]\n\n"
+                f"{lifecycle_info}\n"
                 f"📄 Config saved to: [dim]{result.config_path}[/dim]\n\n"
                 f"[bold]Next Steps:[/bold]\n"
                 f"   [cyan]agentcore launch[/cyan]",
@@ -566,6 +679,7 @@ def launch(
                 use_codebuild=not local_build,
                 env_vars=env_vars,
                 auto_update_on_conflict=auto_update_on_conflict,
+                console=console,
             )
 
         project_config = load_config(config_path)
@@ -575,12 +689,23 @@ def launch(
             _print_success(f"Docker image built: {result.tag}")
             _print_success("Ready to run locally")
             console.print("Starting server at http://localhost:8080")
+            console.print("Starting OAuth2 3LO callback server at http://localhost:8081")
             console.print("[yellow]Press Ctrl+C to stop[/yellow]\n")
 
             if result.runtime is None or result.port is None:
                 _handle_error("Unable to launch locally")
 
             try:
+                oauth2_callback_endpoint = Thread(
+                    target=start_oauth2_callback_server,
+                    args=(
+                        config_path,
+                        agent,
+                    ),
+                    name="OAuth2 3LO Callback Server",
+                    daemon=True,
+                )
+                oauth2_callback_endpoint.start()
                 result.runtime.run_local(result.tag, result.port, result.env_vars)
             except KeyboardInterrupt:
                 console.print("\n[yellow]Stopped[/yellow]")
@@ -970,11 +1095,6 @@ def status(
 
                     # Determine overall status
                     endpoint_status = endpoint_data.get("status", "Unknown") if endpoint_data else "Not Ready"
-                    # memory_info = ""
-                    # if hasattr(status_json["config"], "memory_id") and status_json["config"].get("memory_id"):
-                    #    memory_type = status_json["config"].get("memory_type", "Short-term")
-                    #    memory_id = status_json["config"].get("memory_id")
-                    #    memory_info = f"Memory: [cyan]{memory_type}[/cyan] ([dim]{memory_id}[/dim])\n"
                     if endpoint_status == "READY":
                         status_text = "Ready - Agent deployed and endpoint available"
                     else:
@@ -992,6 +1112,26 @@ def status(
                         f"Account: [dim]{status_json['config'].get('account', 'Not available')}[/dim]\n\n"
                     )
 
+                    # Add network information
+                    network_mode = status_json.get("agent", {}).get("networkConfiguration", {}).get("networkMode")
+                    if network_mode == "VPC":
+                        # Get VPC info from agent response (not config)
+                        network_config = (
+                            status_json.get("agent", {}).get("networkConfiguration", {}).get("networkModeConfig", {})
+                        )
+                        vpc_subnets = network_config.get("subnets", [])
+                        vpc_security_groups = network_config.get("securityGroups", [])
+                        subnet_count = len(vpc_subnets)
+                        sg_count = len(vpc_security_groups)
+                        vpc_id = status_json.get("config", {}).get("network_vpc_id", "unknown")
+                        if vpc_id:
+                            panel_content += f"Network: [cyan]VPC[/cyan] ([dim]{vpc_id}[/dim])\n"
+                            panel_content += f"         {subnet_count} subnets, {sg_count} security groups\n\n"
+                        else:
+                            panel_content += "Network: [cyan]VPC[/cyan]\n\n"
+                    else:
+                        panel_content += "Network: [cyan]Public[/cyan]\n\n"
+
                     # Add memory status with proper provisioning indication
                     if "memory_id" in status_json.get("config", {}) and status_json["config"]["memory_id"]:
                         memory_type = status_json["config"].get("memory_type", "Unknown")
@@ -1021,6 +1161,19 @@ def status(
                         f"[/dim]\n\n"
                     )
 
+                    if status_json["config"].get("idle_timeout") or status_json["config"].get("max_lifetime"):
+                        panel_content += "[bold]Lifecycle Settings:[/bold]\n"
+
+                        idle = status_json["config"].get("idle_timeout")
+                        if idle:
+                            panel_content += f"Idle Timeout: [cyan]{idle}s ({idle // 60} minutes)[/cyan]\n"
+
+                        max_life = status_json["config"].get("max_lifetime")
+                        if max_life:
+                            panel_content += f"Max Lifetime: [cyan]{max_life}s ({max_life // 3600} hours)[/cyan]\n"
+
+                        panel_content += "\n"
+
                     # Add CloudWatch logs information
                     agent_id = status_json.get("config", {}).get("agent_id")
                     if agent_id:
@@ -1115,6 +1268,109 @@ def status(
         raise typer.Exit(1) from e
 
 
+def stop_session(
+    session_id: Optional[str] = typer.Option(
+        None,
+        "--session-id",
+        "-s",
+        help="Runtime session ID to stop. If not provided, stops the last active session from invoke.",
+    ),
+    agent: Optional[str] = typer.Option(
+        None,
+        "--agent",
+        "-a",
+        help="Agent name (use 'agentcore configure list' to see available agents)",
+    ),
+):
+    """Stop an active runtime session.
+
+    Terminates the compute session for the running agent. This frees up resources
+    and ends any ongoing agent processing for that session.
+
+    🔍 How to find session IDs:
+       • Last invoked session is automatically tracked (no flag needed)
+       • Check 'agentcore status' to see the tracked session ID
+       • Check CloudWatch logs for session IDs from previous invokes
+       • Session IDs are also visible in the config file: .bedrock_agentcore.yaml
+
+    ⏱️  Session Lifecycle:
+       • Runtime sessions are created when you invoke an agent
+       • They automatically expire after the configured idle timeout
+       • Stopping a session immediately frees resources without waiting for timeout
+
+    Examples:
+        # Stop the last invoked session (most common)
+        agentcore stop-session
+
+        # Stop a specific session by ID
+        agentcore stop-session --session-id abc123xyz
+
+        # Stop last session for a specific agent
+        agentcore stop-session --agent my-agent
+
+        # Get current session ID before stopping
+        agentcore status  # Shows tracked session ID
+        agentcore stop-session
+    """
+    config_path = Path.cwd() / ".bedrock_agentcore.yaml"
+
+    try:
+        from ...operations.runtime import stop_runtime_session
+
+        result = stop_runtime_session(
+            config_path=config_path,
+            session_id=session_id,
+            agent_name=agent,
+        )
+
+        # Show result panel
+        status_icon = "✅" if result.status_code == 200 else "⚠️"
+        status_color = "green" if result.status_code == 200 else "yellow"
+
+        console.print(
+            Panel(
+                f"[{status_color}]{status_icon} {result.message}[/{status_color}]\n\n"
+                f"[bold]Session Details:[/bold]\n"
+                f"Session ID: [cyan]{result.session_id}[/cyan]\n"
+                f"Agent: [cyan]{result.agent_name}[/cyan]\n"
+                f"Status Code: [cyan]{result.status_code}[/cyan]\n\n"
+                f"[dim]💡 Runtime sessions automatically expire after idle timeout.\n"
+                f"   Manually stopping frees resources immediately.[/dim]",
+                title="Session Stopped",
+                border_style="bright_blue",
+            )
+        )
+
+    except FileNotFoundError:
+        _show_configuration_not_found_panel()
+        raise typer.Exit(1) from None
+    except ValueError as e:
+        console.print(
+            Panel(
+                f"[red]❌ Failed to Stop Session[/red]\n\n"
+                f"Error: {str(e)}\n\n"
+                f"[bold]How to find session IDs:[/bold]\n"
+                f"  • Check 'agentcore status' for the tracked session ID\n"
+                f"  • Check CloudWatch logs for session IDs\n"
+                f"  • Invoke the agent first to create a session\n\n"
+                f"[dim]Note: Runtime sessions cannot be listed. You can only stop\n"
+                f"the session from your last invoke or a specific session ID.[/dim]",
+                title="Stop Session Error",
+                border_style="red",
+            )
+        )
+        raise typer.Exit(1) from e
+    except Exception as e:
+        console.print(
+            Panel(
+                f"[red]❌ Unexpected Error[/red]\n\n{str(e)}",
+                title="Stop Session Error",
+                border_style="red",
+            )
+        )
+        raise typer.Exit(1) from e
+
+
 def destroy(
     agent: Optional[str] = typer.Option(
         None, "--agent", "-a", help="Agent name (use 'agentcore configure list' to see available agents)"

bedrock_agentcore_starter_toolkit/cli/runtime/configuration_manager.py

@@ -267,8 +267,8 @@ class ConfigurationManager:
 
         Returns:
             Tuple of (action, value) where:
-            - action is "USE_EXISTING", "CREATE_NEW"
-            - value is memory_id for USE_EXISTING, mode for CREATE_NEW
+            - action is "USE_EXISTING", "CREATE_NEW", "SKIP"
+            - value is memory_id for USE_EXISTING, mode for CREATE_NEW, None for SKIP
         """
         if self.non_interactive:
             # In non-interactive mode, default to creating new STM
@@ -285,8 +285,19 @@ class ConfigurationManager:
             region = self.region or (self.existing_config.aws.region if self.existing_config else None)
 
             if not region:
-                # No region available - skip to new memory creation
-                console.print("[dim]No region configured yet, proceeding with new memory creation[/dim]")
+                # No region available - offer skip option
+                console.print("[dim]No region configured yet[/dim]")
+                console.print("\n[dim]Options:[/dim]")
+                console.print("[dim]  • Press Enter to create new memory[/dim]")
+                console.print("[dim]  • Type 's' to skip memory setup[/dim]")  # <-- ADD
+                console.print()
+
+                response = _prompt_with_default("Your choice", "").strip().lower()
+
+                if response == "s" or response == "skip":  # <-- ADD
+                    _print_success("Skipping memory configuration")
+                    return ("SKIP", None)
+
                 return self._prompt_new_memory_config()
 
             memory_manager = MemoryManager(region_name=region)
@@ -311,10 +322,14 @@ class ConfigurationManager:
                 console.print("\n[dim]Options:[/dim]")
                 console.print("[dim]  • Enter a number to use existing memory[/dim]")
                 console.print("[dim]  • Press Enter to create new memory[/dim]")
+                console.print("[dim]  • Type 's' to skip memory setup[/dim]")
 
                 response = _prompt_with_default("Your choice", "").strip().lower()
 
-                if response.isdigit():
+                if response == "s" or response == "skip":
+                    _print_success("Skipping memory configuration")
+                    return ("SKIP", None)
+                elif response.isdigit():
                     idx = int(response) - 1
                     if 0 <= idx < len(existing_memories):
                         selected = existing_memories[idx]
@@ -323,7 +338,16 @@ class ConfigurationManager:
             else:
                 # No existing memories found
                 console.print("[yellow]No existing memory resources found in your account[/yellow]")
-                console.print("[dim]Proceeding with new memory creation...[/dim]\n")
+                console.print("\n[dim]Options:[/dim]")
+                console.print("[dim]  • Press Enter to create new memory[/dim]")
+                console.print("[dim]  • Type 's' to skip memory setup[/dim]")
+                console.print()
+
+                response = _prompt_with_default("Your choice", "").strip().lower()
+
+                if response == "s" or response == "skip":
+                    _print_success("Skipping memory configuration")
+                    return ("SKIP", None)
 
         except Exception as e:
             console.print(f"[dim]Could not list existing memories: {e}[/dim]")
@@ -332,7 +356,7 @@ class ConfigurationManager:
         return self._prompt_new_memory_config()
 
     def _prompt_new_memory_config(self) -> Tuple[str, str]:
-        """Prompt for new memory configuration (no skip option)."""
+        """Prompt for new memory configuration - LTM yes/no only."""
         console.print("[green]✓ Short-term memory will be enabled (default)[/green]")
         console.print("  • Stores conversations within sessions")
         console.print("  • Provides immediate context recall")