bedrock-agentcore-starter-toolkit 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

bedrock_agentcore_starter_toolkit/cli/runtime/commands.py

@@ -262,35 +262,102 @@ def launch(
     agent: Optional[str] = typer.Option(
         None, "--agent", "-a", help="Agent name (use 'agentcore configure list' to see available agents)"
     ),
-    local: bool = typer.Option(False, "--local", "-l", help="Run locally"),
-    push_ecr: bool = typer.Option(False, "--push-ecr", "-p", help="Build and push to ECR only (no deployment)"),
-    codebuild: bool = typer.Option(False, "--codebuild", "-cb", help="Use CodeBuild for ARM64 builds"),
+    local: bool = typer.Option(
+        False, "--local", "-l", help="Build locally and run container locally - requires Docker/Finch/Podman"
+    ),
+    local_build: bool = typer.Option(
+        False,
+        "--local-build",
+        "-lb",
+        help="Build locally and deploy to cloud runtime - requires Docker/Finch/Podman",
+    ),
     auto_update_on_conflict: bool = typer.Option(
-        False, "--auto-update-on-conflict", help="Enable automatic update when agent already exists"
+        False,
+        "--auto-update-on-conflict",
+        "-auc",
+        help="Automatically update existing agent instead of failing with ConflictException",
     ),
     envs: List[str] = typer.Option(  # noqa: B008
         None, "--env", "-env", help="Environment variables for agent (format: KEY=VALUE)"
     ),
+    code_build: bool = typer.Option(
+        False,
+        "--code-build",
+        help="[DEPRECATED] CodeBuild is now the default. Use no flags for CodeBuild deployment.",
+        hidden=True,
+    ),
 ):
-    """Launch Bedrock AgentCore locally or to cloud."""
+    """Launch Bedrock AgentCore with three deployment modes.
+
+    🚀 DEFAULT (no flags): CodeBuild + cloud runtime (RECOMMENDED)
+       - Build ARM64 containers in the cloud with CodeBuild
+       - Deploy to Bedrock AgentCore runtime
+       - No local Docker required
+       - CHANGED: CodeBuild is now the default (previously required --code-build flag)
+
+    💻 --local: Local build + local runtime
+       - Build container locally and run locally
+       - requires Docker/Finch/Podman
+       - For local development and testing
+
+    🔧 --local-build: Local build + cloud runtime
+       - Build container locally with Docker
+       - Deploy to Bedrock AgentCore runtime
+       - requires Docker/Finch/Podman
+       - Use when you need custom build control but want cloud deployment
+
+    MIGRATION GUIDE:
+    - OLD: agentcore launch --code-build  →  NEW: agentcore launch
+    - OLD: agentcore launch --local       →  NEW: agentcore launch --local (unchanged)
+    - NEW: agentcore launch --local-build (build locally + deploy to cloud)
+    """
+    # Handle deprecated --code-build flag
+    if code_build:
+        console.print("[yellow]⚠️  DEPRECATION WARNING: --code-build flag is deprecated[/yellow]")
+        console.print("[yellow]   CodeBuild is now the default deployment method[/yellow]")
+        console.print("[yellow]   MIGRATION: Simply use 'agentcore launch' (no flags needed)[/yellow]")
+        console.print("[yellow]   This flag will be removed in a future version[/yellow]\n")
+
     # Validate mutually exclusive options
-    if sum([local, push_ecr, codebuild]) > 1:
-        _handle_error("Error: --local, --push-ecr, and --codebuild cannot be used together")
+    if sum([local, local_build, code_build]) > 1:
+        _handle_error("Error: --local, --local-build, and --code-build cannot be used together")
 
     config_path = Path.cwd() / ".bedrock_agentcore.yaml"
 
     try:
-        # Show launch mode
+        # Show launch mode with enhanced migration guidance
         if local:
             mode = "local"
-        elif push_ecr:
-            mode = "push-ecr"
-        elif codebuild:
+            console.print(f"[cyan]🏠 Launching Bedrock AgentCore ({mode} mode)...[/cyan]")
+            console.print("[dim]   • Build and run container locally[/dim]")
+            console.print("[dim]   • Requires Docker/Finch/Podman to be installed[/dim]")
+            console.print("[dim]   • Perfect for development and testing[/dim]\n")
+        elif local_build:
+            mode = "local-build"
+            console.print(f"[cyan]🔧 Launching Bedrock AgentCore ({mode} mode - NEW!)...[/cyan]")
+            console.print("[dim]   • Build container locally with Docker[/dim]")
+            console.print("[dim]   • Deploy to Bedrock AgentCore cloud runtime[/dim]")
+            console.print("[dim]   • Requires Docker/Finch/Podman to be installed[/dim]")
+            console.print("[dim]   • Use when you need custom build control[/dim]\n")
+        elif code_build:
+            # Handle deprecated flag - treat as default
             mode = "codebuild"
+            console.print(f"[cyan]🚀 Launching Bedrock AgentCore ({mode} mode - RECOMMENDED)...[/cyan]")
+            console.print("[dim]   • Build ARM64 containers in the cloud with CodeBuild[/dim]")
+            console.print("[dim]   • No local Docker required[/dim]")
+            console.print("[dim]   • Production-ready deployment[/dim]\n")
         else:
-            mode = "cloud"
+            mode = "codebuild"
+            console.print(f"[cyan]🚀 Launching Bedrock AgentCore ({mode} mode - RECOMMENDED)...[/cyan]")
+            console.print("[dim]   • Build ARM64 containers in the cloud with CodeBuild[/dim]")
+            console.print("[dim]   • No local Docker required (DEFAULT behavior)[/dim]")
+            console.print("[dim]   • Production-ready deployment[/dim]\n")
 
-        console.print(f"[cyan]Launching Bedrock AgentCore ({mode} mode)...[/cyan]\n")
+            # Show deployment options hint for first-time users
+            console.print("[dim]💡 Deployment options:[/dim]")
+            console.print("[dim]   • agentcore launch                → CodeBuild (current)[/dim]")
+            console.print("[dim]   • agentcore launch --local        → Local development[/dim]")
+            console.print("[dim]   • agentcore launch --local-build  → Local build + cloud deploy[/dim]\n")
 
         # Use the operations module
         with console.status("[bold]Launching Bedrock AgentCore...[/bold]"):
@@ -304,13 +371,12 @@ def launch(
                     key, value = env_var.split("=", 1)
                     env_vars[key] = value
 
-            # Call the operation
+            # Call the operation - CodeBuild is now default, unless --local-build is specified
             result = launch_bedrock_agentcore(
                 config_path=config_path,
                 agent_name=agent,
                 local=local,
-                push_ecr_only=push_ecr,
-                use_codebuild=codebuild,
+                use_codebuild=not local_build,
                 env_vars=env_vars,
                 auto_update_on_conflict=auto_update_on_conflict,
             )
@@ -330,20 +396,6 @@ def launch(
             except KeyboardInterrupt:
                 console.print("\n[yellow]Stopped[/yellow]")
 
-        elif result.mode == "push-ecr":
-            _print_success(f"Image pushed to ECR: [cyan]{result.ecr_uri}:latest[/cyan]")
-            console.print(
-                Panel(
-                    f"[green]ECR Push Successful![/green]\n\n"
-                    f"Image: [cyan]{result.tag}[/cyan]\n"
-                    f"ECR URI: [cyan]{result.ecr_uri}:latest[/cyan]\n\n"
-                    f"Your image is now available in ECR.\n"
-                    f"Run [cyan]agentcore launch[/cyan] to deploy to Bedrock AgentCore.",
-                    title="Push to ECR Complete",
-                    border_style="green",
-                )
-            )
-
         elif result.mode == "codebuild":
             _print_success(f"CodeBuild completed: [cyan]{result.codebuild_id}[/cyan]")
             _print_success(f"ARM64 image pushed to ECR: [cyan]{result.ecr_uri}:latest[/cyan]")
@@ -386,13 +438,22 @@ def launch(
                 )
             )
 
-        else:  # cloud mode
+        else:  # cloud mode (either CodeBuild default or local-build)
             _print_success(f"Image pushed to ECR: [cyan]{result.ecr_uri}:latest[/cyan]")
 
             # Show deployment success panel
             agent_name = result.tag.split(":")[0].replace("bedrock_agentcore-", "")
+
+            # Determine deployment type for panel title
+            if local_build:
+                title = "Local Build Deployment Complete"
+                deployment_type = "Local Docker Build Deployment Successful!"
+            else:
+                title = "CodeBuild Deployment Complete"
+                deployment_type = "CodeBuild Deployment Successful!"
+
             deploy_panel = (
-                f"[green]Deployment Successful![/green]\n\n"
+                f"[green]{deployment_type}[/green]\n\n"
                 f"Agent Name: {agent_name}\n"
                 f"Agent ARN: [cyan]{result.agent_arn}[/cyan]\n"
                 f"ECR URI: [cyan]{result.ecr_uri}[/cyan]\n\n"
@@ -420,7 +481,7 @@ def launch(
             console.print(
                 Panel(
                     deploy_panel,
-                    title="Bedrock AgentCore Deployed",
+                    title=title,
                     border_style="green",
                 )
             )
@@ -484,7 +545,14 @@ def invoke(
 
         # Display payload
         console.print("[bold]Payload:[/bold]")
-        console.print(Syntax(json.dumps(payload_data, indent=2), "json", background_color="default", word_wrap=True))
+        console.print(
+            Syntax(
+                json.dumps(payload_data, indent=2, ensure_ascii=False),
+                "json",
+                background_color="default",
+                word_wrap=True,
+            )
+        )
 
         # Invoke
         result = invoke_bedrock_agentcore(
@@ -497,17 +565,31 @@ def invoke(
             local_mode=local_mode,
         )
         console.print(f"Session ID: [cyan]{result.session_id}[/cyan]")
-        console.print("\n[bold]Response:[/bold]")
-        console.print(
-            Syntax(
-                json.dumps(result.response, indent=2, default=str), "json", background_color="default", word_wrap=True
+        if result.response != {}:
+            console.print("\n[bold]Response:[/bold]")
+            console.print(
+                Syntax(
+                    json.dumps(result.response, indent=2, default=str, ensure_ascii=False),
+                    "json",
+                    background_color="default",
+                    word_wrap=True,
+                )
             )
-        )
 
     except FileNotFoundError:
-        _handle_error(".bedrock_agentcore.yaml not found. Run 'bedrock_agentcore configure --entrypoint <file>' first")
+        console.print("[red].bedrock_agentcore.yaml not found[/red]")
+        console.print("Run the following commands to get started:")
+        console.print("  1. agentcore configure --entrypoint your_agent.py")
+        console.print("  2. agentcore launch")
+        console.print('  3. agentcore invoke \'{"message": "Hello"}\'')
+        raise typer.Exit(1) from None
     except ValueError as e:
         if "not deployed" in str(e):
+            console.print("[yellow]Agent not deployed yet[/yellow]")
+            console.print("Deploy your agent first:")
+            console.print("  agentcore launch                    # Deploy to AWS (recommended)")
+            console.print("  agentcore launch --local            # Run locally")
+            console.print("Then check status: agentcore status")
             _handle_error("Bedrock AgentCore not deployed. Run 'bedrock_agentcore launch' first", e)
         else:
             _handle_error(f"Invocation failed: {e}", e)
@@ -639,12 +721,20 @@ def status(
         else:  # full json verbose output
             console.print(
                 Syntax(
-                    json.dumps(status_json, indent=2, default=str), "json", background_color="default", word_wrap=True
+                    json.dumps(status_json, indent=2, default=str, ensure_ascii=False),
+                    "json",
+                    background_color="default",
+                    word_wrap=True,
                 )
             )
 
     except FileNotFoundError:
-        _handle_error(".bedrock_agentcore.yaml not found. Run 'bedrock_agentcore configure --entrypoint <file>' first")
+        console.print("[yellow]Configuration not found[/yellow]")
+        console.print("Run the following commands to get started:")
+        console.print("  1. agentcore configure --entrypoint your_agent.py")
+        console.print("  2. agentcore launch")
+        console.print('  3. agentcore invoke \'{"message": "Hello"}\'')
+        raise typer.Exit(1) from None
     except ValueError as e:
         _handle_error(f"Status failed: {e}", e)
     except Exception as e:

bedrock_agentcore_starter_toolkit/notebook/runtime/bedrock_agentcore.py

@@ -45,6 +45,7 @@ class Runtime:
         authorizer_configuration: Optional[Dict[str, Any]] = None,
         region: Optional[str] = None,
         protocol: Optional[Literal["HTTP", "MCP"]] = None,
+        disable_otel: bool = False,
     ) -> ConfigureResult:
         """Configure Bedrock AgentCore from notebook using an entrypoint file.
 
@@ -62,6 +63,7 @@ class Runtime:
             authorizer_configuration: JWT authorizer configuration dictionary
             region: AWS region for deployment
             protocol: agent server protocol, must be either HTTP or MCP
+            disable_otel: Whether to disable OpenTelemetry observability (default: False)
 
         Returns:
             ConfigureResult with configuration details
@@ -110,6 +112,7 @@ class Runtime:
             ecr_repository=ecr_repository,
             container_runtime=container_runtime,
             auto_create_ecr=auto_create_ecr,
+            enable_observability=not disable_otel,
             requirements_file=final_requirements_file,
             authorizer_configuration=authorizer_configuration,
             region=region,
@@ -123,17 +126,15 @@ class Runtime:
     def launch(
         self,
         local: bool = False,
-        push_ecr: bool = False,
-        use_codebuild: bool = False,
+        local_build: bool = False,
         auto_update_on_conflict: bool = False,
         env_vars: Optional[Dict] = None,
     ) -> LaunchResult:
         """Launch Bedrock AgentCore from notebook.
 
         Args:
-            local: Whether to build for local execution only
-            push_ecr: Whether to push to ECR only (no deployment)
-            use_codebuild: Whether to use CodeBuild for ARM64 builds (cloud deployment only)
+            local: Whether to build and run locally (requires Docker/Finch/Podman)
+            local_build: Whether to build locally and deploy to cloud (requires Docker/Finch/Podman)
             auto_update_on_conflict: Whether to automatically update resources on conflict (default: False)
             env_vars: environment variables for agent container
 
@@ -141,26 +142,75 @@ class Runtime:
             LaunchResult with deployment details
         """
         if not self._config_path:
+            log.warning("Configuration required before launching")
+            log.info("Call .configure() first to set up your agent")
+            log.info("Example: runtime.configure(entrypoint='my_agent.py')")
             raise ValueError("Must configure before launching. Call .configure() first.")
 
-        # Validate mutually exclusive options
-        exclusive_options = [local, push_ecr, use_codebuild]
-        if sum(exclusive_options) > 1:
-            raise ValueError("Only one of 'local', 'push_ecr', or 'use_codebuild' can be True")
-
-        result = launch_bedrock_agentcore(
-            self._config_path,
-            local=local,
-            push_ecr_only=push_ecr,
-            use_codebuild=use_codebuild,
-            auto_update_on_conflict=auto_update_on_conflict,
-            env_vars=env_vars,
-        )
+        # Enhanced validation for mutually exclusive options with helpful guidance
+        if local and local_build:
+            raise ValueError(
+                "Cannot use both 'local' and 'local_build' flags together.\n"
+                "Choose one deployment mode:\n"
+                "• runtime.launch(local=True) - for local development\n"
+                "• runtime.launch(local_build=True) - for local build + cloud deployment\n"
+                "• runtime.launch() - for CodeBuild deployment (recommended)"
+            )
+
+        # Inform user about deployment mode with enhanced migration guidance
+        if local:
+            log.info("🏠 Local mode: building and running locally")
+            log.info("   • Build and run container locally")
+            log.info("   • Requires Docker/Finch/Podman to be installed")
+            log.info("   • Perfect for development and testing")
+        elif local_build:
+            log.info("🔧 Local build mode: building locally, deploying to cloud (NEW OPTION!)")
+            log.info("   • Build container locally with Docker")
+            log.info("   • Deploy to Bedrock AgentCore cloud runtime")
+            log.info("   • Requires Docker/Finch/Podman to be installed")
+            log.info("   • Use when you need custom build control")
+        else:
+            log.info("🚀 CodeBuild mode: building in cloud (RECOMMENDED - DEFAULT)")
+            log.info("   • Build ARM64 containers in the cloud with CodeBuild")
+            log.info("   • No local Docker required")
+
+            # Show deployment options hint for first-time notebook users
+            log.info("💡 Available deployment modes:")
+            log.info("   • runtime.launch()                           → CodeBuild (current)")
+            log.info("   • runtime.launch(local=True)                 → Local development")
+            log.info("   • runtime.launch(local_build=True)           → Local build + cloud deploy (NEW)")
+
+        # Map to the underlying operation's use_codebuild parameter
+        # use_codebuild=False when local=True OR local_build=True
+        use_codebuild = not (local or local_build)
+
+        try:
+            result = launch_bedrock_agentcore(
+                self._config_path,
+                local=local,
+                use_codebuild=use_codebuild,
+                auto_update_on_conflict=auto_update_on_conflict,
+                env_vars=env_vars,
+            )
+        except RuntimeError as e:
+            # Enhance Docker-related error messages
+            error_msg = str(e)
+            if "docker" in error_msg.lower() or "container runtime" in error_msg.lower():
+                if local or local_build:
+                    enhanced_msg = (
+                        f"Docker/Finch/Podman is required for {'local' if local else 'local-build'} mode.\n\n"
+                    )
+                    enhanced_msg += "Options to fix this:\n"
+                    enhanced_msg += "1. Install Docker/Finch/Podman and try again\n"
+                    enhanced_msg += "2. Use CodeBuild mode instead: runtime.launch() - no Docker required\n\n"
+                    enhanced_msg += f"Original error: {error_msg}"
+                    raise RuntimeError(enhanced_msg) from e
+            raise
 
         if result.mode == "cloud":
             log.info("Deployed to cloud: %s", result.agent_arn)
-            # Show log information for cloud deployments
-            if result.agent_id:
+            # For local_build mode, show minimal output; for pure cloud mode, show log details
+            if not local_build and result.agent_id:
                 from ...utils.runtime.logs import get_agent_log_paths, get_aws_tail_commands
 
                 runtime_logs, otel_logs = get_agent_log_paths(result.agent_id)
@@ -185,11 +235,14 @@ class Runtime:
                 log.info("   %s", otel_logs)
                 log.info("💡 Tail logs with: %s", follow_cmd)
                 log.info("💡 Or view recent logs: %s", since_cmd)
-        elif result.mode == "push-ecr":
-            log.info("Pushed to ECR: %s", result.ecr_uri)
         else:
             log.info("Built for local: %s", result.tag)
 
+        # For notebook interface, clear verbose build output to keep output clean
+        # especially for local_build mode where build logs can be very verbose
+        if local_build and hasattr(result, "build_output"):
+            result.build_output = None
+
         return result
 
     def invoke(
@@ -213,6 +266,12 @@ class Runtime:
             Response from the Bedrock AgentCore endpoint
         """
         if not self._config_path:
+            log.warning("Agent not configured and deployed")
+            log.info("Required workflow: .configure() → .launch() → .invoke()")
+            log.info("Example:")
+            log.info("  runtime.configure(entrypoint='my_agent.py')")
+            log.info("  runtime.launch()")
+            log.info("  runtime.invoke({'message': 'Hello'})")
             raise ValueError("Must configure and launch first.")
 
         result = invoke_bedrock_agentcore(
@@ -232,8 +291,47 @@ class Runtime:
             StatusResult with configuration, agent, and endpoint status
         """
         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.")
 
         result = get_status(self._config_path)
         log.info("Retrieved Bedrock AgentCore status for: %s", self.name or "Bedrock AgentCore")
         return result
+
+    def help_deployment_modes(self):
+        """Display information about available deployment modes and migration guidance."""
+        print("\n🚀 Bedrock AgentCore Deployment Modes:")
+        print("=" * 50)
+
+        print("\n1. 📦 CodeBuild Mode (RECOMMENDED - DEFAULT)")
+        print("   Usage: runtime.launch()")
+        print("   • Build ARM64 containers in the cloud with CodeBuild")
+        print("   • No local Docker/Finch/Podman required")
+        print("   • ✅ Works in SageMaker Notebooks, Cloud9, laptops")
+
+        print("\n2. 🏠 Local Development Mode")
+        print("   Usage: runtime.launch(local=True)")
+        print("   • Build and run container locally")
+        print("   • Requires Docker/Finch/Podman installation")
+        print("   • Perfect for development and testing")
+        print("   • Fast iteration and debugging")
+
+        print("\n3. 🔧 Local Build Mode (NEW!)")
+        print("   Usage: runtime.launch(local_build=True)")
+        print("   • Build container locally with Docker")
+        print("   • Deploy to Bedrock AgentCore cloud runtime")
+        print("   • Requires Docker/Finch/Podman installation")
+        print("   • Use when you need custom build control")
+
+        print("\n📋 Migration Guide:")
+        print("   • CodeBuild is now the default (no code changes needed)")
+        print("   • Previous --code-build flag is deprecated")
+        print("   • local_build=True option for hybrid workflows")
+
+        print("\n💡 Quick Start:")
+        print("   runtime.configure(entrypoint='my_agent.py')")
+        print("   runtime.launch()  # Uses CodeBuild by default")
+        print('   runtime.invoke({"prompt": "Hello"})')
+        print()

bedrock_agentcore_starter_toolkit/operations/gateway/client.py

@@ -65,7 +65,7 @@ class GatewayClient:
         :param role_arn: optional - the role arn to use (creates one if none provided).
         :param authorizer_config: optional - the authorizer config (will create one if none provided).
         :param enable_semantic_search: optional - whether to enable search tool (defaults to True).
-        :return: the created Gateway.
+        :return: the created Gateway
         """
         if not name:
             name = f"TestGateway{GatewayClient.generate_random_id()}"
@@ -130,6 +130,7 @@ class GatewayClient:
             "gatewayIdentifier": gateway["gatewayId"],
             "name": name,
             "targetConfiguration": {"mcp": {target_type: target_payload}},
+            "credentialProviderConfigurations": [{"credentialProviderType": "GATEWAY_IAM_ROLE"}],
         }
         # handle cases of missing target payloads across smithy and lambda (default to something)
         if not target_payload and target_type == "lambda":
@@ -183,7 +184,6 @@ class GatewayClient:
 
         return {
             "targetConfiguration": {"mcp": {"lambda": {"lambdaArn": lambda_arn, "toolSchema": LAMBDA_CONFIG}}},
-            "credentialProviderConfigurations": [{"credentialProviderType": "GATEWAY_IAM_ROLE"}],
         }
 
     def __handle_openapi_target_credential_provider_creation(

bedrock_agentcore_starter_toolkit/operations/runtime/configure.py

@@ -145,11 +145,14 @@ def configure_bedrock_agentcore(
         log.debug("Agent name from BedrockAgentCoreApp: %s", agent_name)
         log.debug("Config path: %s", config_path)
 
+    # Convert to POSIX for cross-platform compatibility
+    entrypoint_path_str = entrypoint_path.as_posix()
+
     # Determine entrypoint format
     if bedrock_agentcore_name:
-        entrypoint = f"{str(entrypoint_path)}:{bedrock_agentcore_name}"
+        entrypoint = f"{entrypoint_path_str}:{bedrock_agentcore_name}"
     else:
-        entrypoint = str(entrypoint_path)
+        entrypoint = entrypoint_path_str
 
     if verbose:
         log.debug("Using entrypoint format: %s", entrypoint)

bedrock_agentcore_starter_toolkit/operations/runtime/invoke.py

@@ -53,7 +53,7 @@ def invoke_bedrock_agentcore(
 
     # Convert payload to string if needed
     if isinstance(payload, dict):
-        payload_str = json.dumps(payload)
+        payload_str = json.dumps(payload, ensure_ascii=False)
     else:
         payload_str = str(payload)