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

bedrock_agentcore_starter_toolkit/cli/cli.py

@@ -1,22 +1,15 @@
 """BedrockAgentCore CLI main module."""
 
-import logging
-
 import typer
-from rich.logging import RichHandler
 
 from ..cli.gateway.commands import create_mcp_gateway, create_mcp_gateway_target, gateway_app
-from .common import console
+from ..utils.logging_config import setup_toolkit_logging
 from .runtime.commands import configure_app, invoke, launch, status
 
 app = typer.Typer(name="agentcore", help="BedrockAgentCore CLI", add_completion=False)
 
-FORMAT = "%(message)s"
-logging.basicConfig(
-    level="INFO",
-    format=FORMAT,
-    handlers=[RichHandler(show_time=False, show_path=False, show_level=False, console=console)],
-)
+# Setup centralized logging for CLI
+setup_toolkit_logging(mode="cli")
 
 # runtime
 app.command("invoke")(invoke)

bedrock_agentcore_starter_toolkit/cli/runtime/commands.py

@@ -264,14 +264,18 @@ def launch(
     ),
     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"),
+    auto_update_on_conflict: bool = typer.Option(
+        False, "--auto-update-on-conflict", help="Enable automatic update when agent already exists"
+    ),
     envs: List[str] = typer.Option(  # noqa: B008
         None, "--env", "-env", help="Environment variables for agent (format: KEY=VALUE)"
     ),
 ):
     """Launch Bedrock AgentCore locally or to cloud."""
     # Validate mutually exclusive options
-    if local and push_ecr:
-        _handle_error("Error: --local and --push-ecr cannot be used together")
+    if sum([local, push_ecr, codebuild]) > 1:
+        _handle_error("Error: --local, --push-ecr, and --codebuild cannot be used together")
 
     config_path = Path.cwd() / ".bedrock_agentcore.yaml"
 
@@ -281,6 +285,8 @@ def launch(
             mode = "local"
         elif push_ecr:
             mode = "push-ecr"
+        elif codebuild:
+            mode = "codebuild"
         else:
             mode = "cloud"
 
@@ -304,7 +310,9 @@ def launch(
                 agent_name=agent,
                 local=local,
                 push_ecr_only=push_ecr,
+                use_codebuild=codebuild,
                 env_vars=env_vars,
+                auto_update_on_conflict=auto_update_on_conflict,
             )
 
         # Handle result based on mode
@@ -336,6 +344,48 @@ def launch(
                 )
             )
 
+        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]")
+
+            # Show deployment success panel
+            agent_name = result.tag.split(":")[0].replace("bedrock_agentcore-", "")
+            deploy_panel = (
+                f"[green]CodeBuild ARM64 Deployment Successful![/green]\n\n"
+                f"Agent Name: {agent_name}\n"
+                f"CodeBuild ID: [cyan]{result.codebuild_id}[/cyan]\n"
+                f"Agent ARN: [cyan]{result.agent_arn}[/cyan]\n"
+                f"ECR URI: [cyan]{result.ecr_uri}:latest[/cyan]\n\n"
+                f"ARM64 container deployed to Bedrock AgentCore.\n\n"
+                f"You can now check the status of your Bedrock AgentCore endpoint with:\n"
+                f"[cyan]agentcore status[/cyan]\n\n"
+                f"You can now invoke your Bedrock AgentCore endpoint with:\n"
+                f'[cyan]agentcore invoke \'{{"prompt": "Hello"}}\'[/cyan]'
+            )
+
+            # Add log information if we have agent_id
+            if 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)
+                follow_cmd, since_cmd = get_aws_tail_commands(runtime_logs)
+                deploy_panel += (
+                    f"\n\n📋 [cyan]Agent logs available at:[/cyan]\n"
+                    f"   {runtime_logs}\n"
+                    f"   {otel_logs}\n\n"
+                    f"💡 [dim]Tail logs with:[/dim]\n"
+                    f"   {follow_cmd}\n"
+                    f"   {since_cmd}"
+                )
+
+            console.print(
+                Panel(
+                    deploy_panel,
+                    title="CodeBuild Deployment Complete",
+                    border_style="green",
+                )
+            )
+
         else:  # cloud mode
             _print_success(f"Image pushed to ECR: [cyan]{result.ecr_uri}:latest[/cyan]")
 
@@ -485,8 +535,6 @@ def status(
     try:
         if not verbose:
             if "config" in status_json:
-                print(f"Getting Status for {status_json['config']['name']}")
-
                 if status_json["agent"] is None:
                     console.print(
                         Panel(

bedrock_agentcore_starter_toolkit/cli/runtime/configuration_manager.py

@@ -21,19 +21,25 @@ class ConfigurationManager:
         project_config = load_config_if_exists(config_path)
         self.existing_config = project_config.get_agent_config() if project_config else None
 
-    def prompt_execution_role(self) -> str:
-        """Prompt for execution role with existing config as default."""
+    def prompt_execution_role(self) -> Optional[str]:
+        """Prompt for execution role. Returns role name/ARN or None for auto-creation."""
         console.print("\n🔐 [cyan]Execution Role[/cyan]")
-        console.print("[dim]Execution role is required for deployment[/dim]")
+        console.print(
+            "[dim]Press Enter to auto-create execution role, or provide execution role ARN/name to use existing[/dim]"
+        )
 
-        default = self.existing_config.aws.execution_role if self.existing_config else ""
-        role = _prompt_with_default("Enter execution role ARN or name", default)
+        # Show existing config info but don't use as default
+        if self.existing_config and self.existing_config.aws.execution_role:
+            console.print(f"[dim]Previously configured: {self.existing_config.aws.execution_role}[/dim]")
 
-        if not role:
-            _handle_error("Execution role is required")
+        role = _prompt_with_default("Execution role ARN/name (or press Enter to auto-create)", "")
 
-        _print_success(f"Using execution role: [dim]{role}[/dim]")
-        return role
+        if role:
+            _print_success(f"Using existing execution role: [dim]{role}[/dim]")
+            return role
+        else:
+            _print_success("Will auto-create execution role")
+            return None
 
     def prompt_ecr_repository(self) -> tuple[Optional[str], bool]:
         """Prompt for ECR repository. Returns (repository, auto_create_flag)."""
@@ -42,8 +48,11 @@ class ConfigurationManager:
             "[dim]Press Enter to auto-create ECR repository, or provide ECR Repository URI to use existing[/dim]"
         )
 
-        default = self.existing_config.aws.ecr_repository if self.existing_config else ""
-        response = _prompt_with_default("ECR Repository URI (or skip to auto-create)", default)
+        # Show existing config info but don't use as default
+        if self.existing_config and self.existing_config.aws.ecr_repository:
+            console.print(f"[dim]Previously configured: {self.existing_config.aws.ecr_repository}[/dim]")
+
+        response = _prompt_with_default("ECR Repository URI (or press Enter to auto-create)", "")
 
         if response:
             _print_success(f"Using existing ECR repository: [dim]{response}[/dim]")

bedrock_agentcore_starter_toolkit/notebook/runtime/bedrock_agentcore.py

@@ -12,15 +12,15 @@ from ...operations.runtime import (
     validate_agent_name,
 )
 from ...operations.runtime.models import ConfigureResult, LaunchResult, StatusResult
+
+# Setup centralized logging for SDK usage (notebooks, scripts, imports)
+from ...utils.logging_config import setup_toolkit_logging
 from ...utils.runtime.entrypoint import parse_entrypoint
 
-# Configure logger for notebook use
+setup_toolkit_logging(mode="sdk")
+
+# Configure logger for this module
 log = logging.getLogger(__name__)
-if not log.handlers:
-    handler = logging.StreamHandler()
-    handler.setFormatter(logging.Formatter("%(message)s"))
-    log.addHandler(handler)
-    log.setLevel(logging.INFO)
 
 
 class Runtime:
@@ -34,13 +34,14 @@ class Runtime:
     def configure(
         self,
         entrypoint: str,
-        execution_role: str,
+        execution_role: Optional[str] = None,
         agent_name: Optional[str] = None,
         requirements: Optional[List[str]] = None,
         requirements_file: Optional[str] = None,
         ecr_repository: Optional[str] = None,
         container_runtime: Optional[str] = None,
         auto_create_ecr: bool = True,
+        auto_create_execution_role: bool = False,
         authorizer_configuration: Optional[Dict[str, Any]] = None,
         region: Optional[str] = None,
         protocol: Optional[Literal["HTTP", "MCP"]] = None,
@@ -50,13 +51,14 @@ class Runtime:
         Args:
             entrypoint: Path to Python file with optional Bedrock AgentCore name
                 (e.g., "handler.py" or "handler.py:bedrock_agentcore")
-            execution_role: AWS IAM execution role ARN or name
+            execution_role: AWS IAM execution role ARN or name (optional if auto_create_execution_role=True)
             agent_name: name of the agent
             requirements: Optional list of requirements to generate requirements.txt
             requirements_file: Optional path to existing requirements file
             ecr_repository: Optional ECR repository URI
             container_runtime: Optional container runtime (docker/podman)
             auto_create_ecr: Whether to auto-create ECR repository
+            auto_create_execution_role: Whether to auto-create execution role (makes execution_role optional)
             authorizer_configuration: JWT authorizer configuration dictionary
             region: AWS region for deployment
             protocol: agent server protocol, must be either HTTP or MCP
@@ -75,6 +77,10 @@ class Runtime:
         if not valid:
             raise ValueError(error)
 
+        # Validate execution role configuration
+        if not execution_role and not auto_create_execution_role:
+            raise ValueError("Must provide either 'execution_role' or set 'auto_create_execution_role=True'")
+
         # Update our name if not already set
         if not self.name:
             self.name = agent_name
@@ -99,6 +105,7 @@ class Runtime:
         result = configure_bedrock_agentcore(
             agent_name=agent_name,
             entrypoint_path=Path(file_path),
+            auto_create_execution_role=auto_create_execution_role,
             execution_role=execution_role,
             ecr_repository=ecr_repository,
             container_runtime=container_runtime,
@@ -113,12 +120,21 @@ class Runtime:
         log.info("Bedrock AgentCore configured: %s", self._config_path)
         return result
 
-    def launch(self, local: bool = False, push_ecr: bool = False, env_vars: Optional[Dict] = None) -> LaunchResult:
+    def launch(
+        self,
+        local: bool = False,
+        push_ecr: bool = False,
+        use_codebuild: 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)
+            auto_update_on_conflict: Whether to automatically update resources on conflict (default: False)
             env_vars: environment variables for agent container
 
         Returns:
@@ -127,7 +143,19 @@ class Runtime:
         if not self._config_path:
             raise ValueError("Must configure before launching. Call .configure() first.")
 
-        result = launch_bedrock_agentcore(self._config_path, local=local, push_ecr_only=push_ecr, env_vars=env_vars)
+        # 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,
+        )
 
         if result.mode == "cloud":
             log.info("Deployed to cloud: %s", result.agent_arn)
@@ -135,6 +163,21 @@ class Runtime:
             if 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)
+                follow_cmd, since_cmd = get_aws_tail_commands(runtime_logs)
+                log.info("🔍 Agent logs available at:")
+                log.info("   %s", runtime_logs)
+                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 == "codebuild":
+            log.info("Built with CodeBuild: %s", result.codebuild_id)
+            log.info("Deployed to cloud: %s", result.agent_arn)
+            log.info("ECR image: %s", result.ecr_uri)
+            # Show log information for CodeBuild deployments
+            if 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)
                 follow_cmd, since_cmd = get_aws_tail_commands(runtime_logs)
                 log.info("🔍 Agent logs available at:")

bedrock_agentcore_starter_toolkit/operations/gateway/README.md

@@ -18,16 +18,16 @@ agentcore create_mcp_gateway \
 
 # Create a Gateway Target with predefined smithy model
 agentcore create_mcp_gateway_target \
---region us-east-1 \
---gateway-arn arn:aws:bedrock-agentcore:us-east-1:123:gateway/gateway-id \
+--region us-west-2 \
+--gateway-arn arn:aws:bedrock-agentcore:us-west-2:123:gateway/gateway-id \
 --gateway-url https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
 --role-arn arn:aws:iam::123:role/BedrockAgentCoreGatewayRole \
 --target-type smithyModel
 
 # Create a Gateway Target with OpenAPI target (OAuth with API Key)
 agentcore create_mcp_gateway_target \
---region us-east-1 \
---gateway-arn arn:aws:bedrock-agentcore:us-east-1:123:gateway/gateway-id \
+--region us-west-2 \
+--gateway-arn arn:aws:bedrock-agentcore:us-west-2:123:gateway/gateway-id \
 --gateway-url https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
 --role-arn arn:aws:iam::123:role/BedrockAgentCoreGatewayRole \
 --target-type openApiSchema \
@@ -36,8 +36,8 @@ agentcore create_mcp_gateway_target \
 
 # Create a Gateway Target with OpenAPI target (OAuth with credential provider)
 agentcore create_mcp_gateway_target \
---region us-east-1 \
---gateway-arn arn:aws:bedrock-agentcore:us-east-1:123:gateway/gateway-id \
+--region us-west-2 \
+--gateway-arn arn:aws:bedrock-agentcore:us-west-2:123:gateway/gateway-id \
 --gateway-url https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
 --role-arn arn:aws:iam::123:role/BedrockAgentCoreGatewayRole \
 --target-type openApiSchema \

bedrock_agentcore_starter_toolkit/operations/gateway/create_role.py

@@ -43,17 +43,18 @@ def create_gateway_execution_role(
 
         return role["Role"]["Arn"]
 
-    except iam.exceptions.EntityAlreadyExistsException:
-        try:
-            role = iam.get_role(RoleName=role_name)
-            logger.info("✓ Role already exists: %s", role["Role"]["Arn"])
-            return role["Role"]["Arn"]
-        except ClientError as e:
-            logger.error("Error getting existing role: %s", e)
-            raise
     except ClientError as e:
-        logger.error("Error creating role: %s", e)
-        raise
+        if e.response["Error"]["Code"] == "EntityAlreadyExists":
+            try:
+                role = iam.get_role(RoleName=role_name)
+                logger.info("✓ Role already exists: %s", role["Role"]["Arn"])
+                return role["Role"]["Arn"]
+            except ClientError as get_error:
+                logger.error("Error getting existing role: %s", get_error)
+                raise
+        else:
+            logger.error("Error creating role: %s", e)
+            raise
 
 
 def _attach_policy(

bedrock_agentcore_starter_toolkit/operations/runtime/configure.py

@@ -28,6 +28,7 @@ def configure_bedrock_agentcore(
     ecr_repository: Optional[str] = None,
     container_runtime: Optional[str] = None,
     auto_create_ecr: bool = True,
+    auto_create_execution_role: bool = True,
     enable_observability: bool = True,
     requirements_file: Optional[str] = None,
     authorizer_configuration: Optional[Dict[str, Any]] = None,
@@ -40,10 +41,11 @@ def configure_bedrock_agentcore(
     Args:
         agent_name: name of the agent,
         entrypoint_path: Path to the entrypoint file
-        execution_role: AWS execution role ARN or name
+        execution_role: AWS execution role ARN or name (auto-created if not provided)
         ecr_repository: ECR repository URI
         container_runtime: Container runtime to use
         auto_create_ecr: Whether to auto-create ECR repository
+        auto_create_execution_role: Whether to auto-create execution role if not provided
         enable_observability: Whether to enable observability
         requirements_file: Path to requirements file
         authorizer_configuration: JWT authorizer configuration dictionary
@@ -84,15 +86,26 @@ def configure_bedrock_agentcore(
         log.debug("Initializing container runtime with: %s", container_runtime or "default")
     runtime = ContainerRuntime(container_runtime)
 
-    # Handle execution role ARN
-    if execution_role and not execution_role.startswith("arn:aws:iam::"):
-        execution_role_arn = f"arn:aws:iam::{account_id}:role/{execution_role}"
+    # Handle execution role - convert to ARN if provided, otherwise use auto-create setting
+    execution_role_arn = None
+    execution_role_auto_create = auto_create_execution_role
+
+    if execution_role:
+        # User provided a role - convert to ARN format if needed
+        if execution_role.startswith("arn:aws:iam::"):
+            execution_role_arn = execution_role
+        else:
+            execution_role_arn = f"arn:aws:iam::{account_id}:role/{execution_role}"
+
         if verbose:
-            log.debug("Converting role name to ARN: %s → %s", execution_role, execution_role_arn)
+            log.debug("Using execution role: %s", execution_role_arn)
     else:
-        execution_role_arn = execution_role
+        # No role provided - use auto_create_execution_role parameter
         if verbose:
-            log.debug("Using execution role as provided: %s", execution_role_arn)
+            if execution_role_auto_create:
+                log.debug("Execution role will be auto-created during launch")
+            else:
+                log.debug("No execution role provided and auto-create disabled")
 
     # Generate Dockerfile and .dockerignore
     bedrock_agentcore_name = None
@@ -166,6 +179,7 @@ def configure_bedrock_agentcore(
         container_runtime=runtime.runtime,
         aws=AWSConfig(
             execution_role=execution_role_arn,
+            execution_role_auto_create=execution_role_auto_create,
             account=account_id,
             region=region,
             ecr_repository=ecr_repository,