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

bedrock_agentcore_starter_toolkit/operations/gateway/create_role.py

@@ -0,0 +1,89 @@
+"""Creates an execution role to use in the Bedrock AgentCore Gateway module."""
+
+import json
+import logging
+from typing import Optional
+
+from boto3 import Session
+from botocore.client import BaseClient
+from botocore.exceptions import ClientError
+
+from ...operations.gateway.constants import (
+    BEDROCK_AGENTCORE_TRUST_POLICY,
+    POLICIES,
+    POLICIES_TO_CREATE,
+)
+
+
+def create_gateway_execution_role(
+    session: Session, logger: logging.Logger, role_name: str = "AgentCoreGatewayExecutionRole"
+) -> str:
+    """Create the Gateway execution role.
+
+    :param logger: the logger to use.
+    :return: the role ARN.
+    """
+    iam = session.client("iam")
+    # Create the role
+    try:
+        role = iam.create_role(
+            RoleName=role_name,
+            AssumeRolePolicyDocument=json.dumps(BEDROCK_AGENTCORE_TRUST_POLICY),
+            Description="Execution role for AgentCore Gateway",
+        )
+        for policy_name, policy in POLICIES_TO_CREATE:
+            _attach_policy(
+                iam_client=iam,
+                role_name=role_name,
+                policy_name=policy_name,
+                policy_document=json.dumps(policy),
+            )
+        for policy_arn in POLICIES:
+            _attach_policy(iam_client=iam, role_name=role_name, policy_arn=policy_arn)
+
+        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
+
+
+def _attach_policy(
+    iam_client: BaseClient,
+    role_name: str,
+    policy_arn: Optional[str] = None,
+    policy_document: Optional[str] = None,
+    policy_name: Optional[str] = None,
+) -> None:
+    """Attach a policy to an IAM role.
+
+    :param iam_client: the IAM client to use.
+    :param role_name: name of the role.
+    :param policy_arn: the arn of the policy to attach.
+    :param policy_document: the policy document (if not using a policy_arn).
+    :param policy_name: the policy name (if not using a policy_arn).
+    :return:
+    """
+    if policy_arn and policy_document:
+        raise Exception("Cannot specify both policy arn and policy document.")
+    try:
+        if policy_arn:
+            iam_client.attach_role_policy(RoleName=role_name, PolicyArn=policy_arn)
+        elif policy_document and policy_name:
+            policy = iam_client.create_policy(
+                PolicyName=policy_name,
+                PolicyDocument=policy_document,
+            )
+            iam_client.attach_role_policy(RoleName=role_name, PolicyArn=policy["Policy"]["Arn"])
+        else:
+            raise Exception("Must specify both policy document and policy name or just a policy arn")
+    except ClientError as e:
+        raise RuntimeError(f"Failed to attach AgentCore policy: {e}") from e

bedrock_agentcore_starter_toolkit/operations/gateway/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions for the Bedrock AgentCore Gateway module."""
+
+
+class GatewayException(Exception):
+    """Base exception for all Gateway SDK errors."""
+
+    pass
+
+
+class GatewaySetupException(GatewayException):
+    """Raised when gateway or Cognito setup fails."""
+
+    pass

bedrock_agentcore_starter_toolkit/operations/runtime/__init__.py

@@ -0,0 +1,26 @@
+"""Bedrock AgentCore operations - shared business logic for CLI and notebook interfaces."""
+
+from .configure import configure_bedrock_agentcore, validate_agent_name
+from .invoke import invoke_bedrock_agentcore
+from .launch import launch_bedrock_agentcore
+from .models import (
+    ConfigureResult,
+    InvokeResult,
+    LaunchResult,
+    StatusConfigInfo,
+    StatusResult,
+)
+from .status import get_status
+
+__all__ = [
+    "configure_bedrock_agentcore",
+    "validate_agent_name",
+    "launch_bedrock_agentcore",
+    "invoke_bedrock_agentcore",
+    "get_status",
+    "ConfigureResult",
+    "InvokeResult",
+    "LaunchResult",
+    "StatusResult",
+    "StatusConfigInfo",
+]

bedrock_agentcore_starter_toolkit/operations/runtime/configure.py

@@ -0,0 +1,227 @@
+"""Configure operation - creates BedrockAgentCore configuration and Dockerfile."""
+
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+from ...services.ecr import get_account_id, get_region
+from ...utils.runtime.config import merge_agent_config, save_config
+from ...utils.runtime.container import ContainerRuntime
+from ...utils.runtime.schema import (
+    AWSConfig,
+    BedrockAgentCoreAgentSchema,
+    BedrockAgentCoreDeploymentInfo,
+    NetworkConfiguration,
+    ObservabilityConfig,
+    ProtocolConfiguration,
+)
+from .models import ConfigureResult
+
+log = logging.getLogger(__name__)
+
+
+def configure_bedrock_agentcore(
+    agent_name: str,
+    entrypoint_path: Path,
+    execution_role: Optional[str] = None,
+    ecr_repository: Optional[str] = None,
+    container_runtime: Optional[str] = None,
+    auto_create_ecr: bool = True,
+    enable_observability: bool = True,
+    requirements_file: Optional[str] = None,
+    authorizer_configuration: Optional[Dict[str, Any]] = None,
+    verbose: bool = False,
+    region: Optional[str] = None,
+    protocol: Optional[str] = None,
+) -> ConfigureResult:
+    """Configure Bedrock AgentCore application with deployment settings.
+
+    Args:
+        agent_name: name of the agent,
+        entrypoint_path: Path to the entrypoint file
+        execution_role: AWS execution role ARN or name
+        ecr_repository: ECR repository URI
+        container_runtime: Container runtime to use
+        auto_create_ecr: Whether to auto-create ECR repository
+        enable_observability: Whether to enable observability
+        requirements_file: Path to requirements file
+        authorizer_configuration: JWT authorizer configuration dictionary
+        verbose: Whether to provide verbose output during configuration
+        region: AWS region for deployment
+        protocol: agent server protocol, must be either HTTP or MCP
+
+    Returns:
+        ConfigureResult model with configuration details
+    """
+    # Set logging level based on verbose flag
+    if verbose:
+        log.setLevel(logging.DEBUG)
+        log.debug("Verbose mode enabled")
+    else:
+        log.setLevel(logging.INFO)
+    # Log agent name at the start of configuration
+    log.info("Configuring BedrockAgentCore agent: %s", agent_name)
+    build_dir = Path.cwd()
+
+    if verbose:
+        log.debug("Build directory: %s", build_dir)
+        log.debug("Bedrock AgentCore name: %s", agent_name)
+        log.debug("Entrypoint path: %s", entrypoint_path)
+
+    # Get AWS info
+    if verbose:
+        log.debug("Retrieving AWS account information...")
+    account_id = get_account_id()
+    region = region or get_region()
+
+    if verbose:
+        log.debug("AWS account ID: %s", account_id)
+        log.debug("AWS region: %s", region)
+
+    # Initialize container runtime
+    if verbose:
+        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}"
+        if verbose:
+            log.debug("Converting role name to ARN: %s → %s", execution_role, execution_role_arn)
+    else:
+        execution_role_arn = execution_role
+        if verbose:
+            log.debug("Using execution role as provided: %s", execution_role_arn)
+
+    # Generate Dockerfile and .dockerignore
+    bedrock_agentcore_name = None
+    # Try to find the variable name for the Bedrock AgentCore instance in the file
+    if verbose:
+        log.debug("Attempting to find Bedrock AgentCore instance name in %s", entrypoint_path)
+
+    if verbose:
+        log.debug("Generating Dockerfile with parameters:")
+        log.debug("  Entrypoint: %s", entrypoint_path)
+        log.debug("  Build directory: %s", build_dir)
+        log.debug("  Bedrock AgentCore name: %s", bedrock_agentcore_name or "bedrock_agentcore")
+        log.debug("  Region: %s", region)
+        log.debug("  Enable observability: %s", enable_observability)
+        log.debug("  Requirements file: %s", requirements_file)
+
+    dockerfile_path = runtime.generate_dockerfile(
+        entrypoint_path,
+        build_dir,
+        bedrock_agentcore_name or "bedrock_agentcore",
+        region,
+        enable_observability,
+        requirements_file,
+    )
+
+    # Check if .dockerignore was created
+    dockerignore_path = build_dir / ".dockerignore"
+
+    log.info("Generated Dockerfile: %s", dockerfile_path)
+    if dockerignore_path.exists():
+        log.info("Generated .dockerignore: %s", dockerignore_path)
+
+    # Handle project configuration (named agents)
+    config_path = build_dir / ".bedrock_agentcore.yaml"
+
+    if verbose:
+        log.debug("Agent name from BedrockAgentCoreApp: %s", agent_name)
+        log.debug("Config path: %s", config_path)
+
+    # Determine entrypoint format
+    if bedrock_agentcore_name:
+        entrypoint = f"{str(entrypoint_path)}:{bedrock_agentcore_name}"
+    else:
+        entrypoint = str(entrypoint_path)
+
+    if verbose:
+        log.debug("Using entrypoint format: %s", entrypoint)
+
+    # Create new configuration
+    ecr_auto_create_value = bool(auto_create_ecr and not ecr_repository)
+
+    if verbose:
+        log.debug("ECR auto-create: %s", ecr_auto_create_value)
+
+    if verbose:
+        log.debug("Creating BedrockAgentCoreConfigSchema with following parameters:")
+        log.debug("  Name: %s", agent_name)
+        log.debug("  Entrypoint: %s", entrypoint)
+        log.debug("  Platform: %s", ContainerRuntime.DEFAULT_PLATFORM)
+        log.debug("  Container runtime: %s", runtime.runtime)
+        log.debug("  Execution role: %s", execution_role_arn)
+        ecr_repo_display = ecr_repository if ecr_repository else "Auto-create" if ecr_auto_create_value else "N/A"
+        log.debug("  ECR repository: %s", ecr_repo_display)
+        log.debug("  Enable observability: %s", enable_observability)
+
+    # Create new agent configuration
+    config = BedrockAgentCoreAgentSchema(
+        name=agent_name,
+        entrypoint=entrypoint,
+        platform=ContainerRuntime.DEFAULT_PLATFORM,
+        container_runtime=runtime.runtime,
+        aws=AWSConfig(
+            execution_role=execution_role_arn,
+            account=account_id,
+            region=region,
+            ecr_repository=ecr_repository,
+            ecr_auto_create=ecr_auto_create_value,
+            network_configuration=NetworkConfiguration(network_mode="PUBLIC"),
+            protocol_configuration=ProtocolConfiguration(server_protocol=protocol or "HTTP"),
+            observability=ObservabilityConfig(enabled=enable_observability),
+        ),
+        bedrock_agentcore=BedrockAgentCoreDeploymentInfo(),
+        authorizer_configuration=authorizer_configuration,
+    )
+
+    # Use simplified config merging
+    project_config = merge_agent_config(config_path, agent_name, config)
+    save_config(project_config, config_path)
+
+    if verbose:
+        log.debug("Configuration saved with agent: %s", agent_name)
+
+    return ConfigureResult(
+        config_path=config_path,
+        dockerfile_path=dockerfile_path,
+        dockerignore_path=dockerignore_path if dockerignore_path.exists() else None,
+        runtime=runtime.get_name(),
+        region=region,
+        account_id=account_id,
+        execution_role=execution_role_arn,
+        ecr_repository=ecr_repository,
+        auto_create_ecr=auto_create_ecr and not ecr_repository,
+    )
+
+
+AGENT_NAME_REGEX = r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$"
+AGENT_NAME_ERROR = (
+    "Invalid agent name. Must start with a letter, contain only letters/numbers/underscores, "
+    "and be 1-48 characters long."
+)
+
+
+def validate_agent_name(name: str) -> Tuple[bool, str]:
+    """Check if name matches the pattern [a-zA-Z][a-zA-Z0-9_]{0,47}.
+
+    This pattern requires:
+    - First character: letter (a-z or A-Z)
+    - Remaining 0-47 characters: letters, digits, or underscores
+    - Total maximum length: 48 characters
+
+    Args:
+        name: The string to validate
+
+    Returns:
+        bool: True if the string matches the pattern, False otherwise
+    """
+    match = bool(re.match(AGENT_NAME_REGEX, name))
+
+    if match:
+        return match, ""
+    else:
+        return match, AGENT_NAME_ERROR

bedrock_agentcore_starter_toolkit/operations/runtime/invoke.py

@@ -0,0 +1,129 @@
+"""Invoke operation - invokes deployed Bedrock AgentCore endpoints."""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+from bedrock_agentcore.services.identity import IdentityClient
+
+from ...services.runtime import BedrockAgentCoreClient, generate_session_id
+from ...utils.runtime.config import load_config, save_config
+from ...utils.runtime.schema import BedrockAgentCoreConfigSchema
+from .models import InvokeResult
+
+log = logging.getLogger(__name__)
+
+
+def invoke_bedrock_agentcore(
+    config_path: Path,
+    payload: Any,
+    agent_name: Optional[str] = None,
+    session_id: Optional[str] = None,
+    bearer_token: Optional[str] = None,
+    user_id: Optional[str] = None,
+    local_mode: Optional[bool] = False,
+) -> InvokeResult:
+    """Invoke deployed Bedrock AgentCore endpoint."""
+    # Load project configuration
+    project_config = load_config(config_path)
+    agent_config = project_config.get_agent_config(agent_name)
+    # Log which agent is being invoked
+    mode = "locally" if local_mode else "via cloud endpoint"
+    log.info("Invoking BedrockAgentCore agent '%s' %s", agent_config.name, mode)
+
+    region = agent_config.aws.region
+    if not region:
+        raise ValueError("Region not configured.")
+
+    agent_arn = agent_config.bedrock_agentcore.agent_arn
+
+    # Handle session ID
+    if not session_id:
+        session_id = agent_config.bedrock_agentcore.agent_session_id
+        if not session_id:
+            session_id = generate_session_id()
+
+    # Save session ID for reuse
+    agent_config.bedrock_agentcore.agent_session_id = session_id
+
+    # Update project config and save
+    project_config.agents[agent_config.name] = agent_config
+    save_config(project_config, config_path)
+
+    # Convert payload to string if needed
+    if isinstance(payload, dict):
+        payload_str = json.dumps(payload)
+    else:
+        payload_str = str(payload)
+
+    if local_mode:
+        from ...services.runtime import LocalBedrockAgentCoreClient
+
+        identity_client = IdentityClient(region)
+        workload_name = _get_workload_name(project_config, config_path, agent_config.name, identity_client)
+        workload_access_token = identity_client.get_workload_access_token(
+            workload_name=workload_name, user_token=bearer_token, user_id=user_id
+        )["workloadAccessToken"]
+
+        # TODO: store and read port config of local running container
+        client = LocalBedrockAgentCoreClient("http://0.0.0.0:8080")
+        response = client.invoke_endpoint(session_id, payload_str, workload_access_token)
+
+    else:
+        if not agent_arn:
+            raise ValueError("Bedrock AgentCore not deployed. Run launch first.")
+
+        # Invoke endpoint using appropriate client
+        if bearer_token:
+            if user_id:
+                log.warning("Both bearer token and user id are specified, ignoring user id")
+
+            # Use HTTP client with bearer token
+            from ...services.runtime import HttpBedrockAgentCoreClient
+
+            client = HttpBedrockAgentCoreClient(region)
+            response = client.invoke_endpoint(
+                agent_arn=agent_arn,
+                payload=payload_str,
+                session_id=session_id,
+                bearer_token=bearer_token,
+            )
+        else:
+            # Use existing boto3 client
+            bedrock_agentcore_client = BedrockAgentCoreClient(region)
+            response = bedrock_agentcore_client.invoke_endpoint(
+                agent_arn=agent_arn, payload=payload_str, session_id=session_id, user_id=user_id
+            )
+
+    return InvokeResult(
+        response=response,
+        session_id=session_id,
+        agent_arn=agent_arn,
+    )
+
+
+def _get_workload_name(
+    project_config: BedrockAgentCoreConfigSchema,
+    project_config_path: Path,
+    agent_name: str,
+    identity_client: IdentityClient,
+) -> str:
+    agent_config = project_config.get_agent_config(agent_name)
+    oauth_config = agent_config.oauth_configuration
+    workload_name = None
+    if oauth_config:
+        workload_name = oauth_config.get("workload_name", None)
+    else:
+        oauth_config = {}
+        agent_config.oauth_configuration = oauth_config
+
+    if not workload_name:
+        log.info("Workload not detected, creating...")
+        workload_name = identity_client.create_workload_identity()["name"]
+        log.info("Created workload %s", workload_name)
+
+    oauth_config["workload_name"] = workload_name
+    save_config(project_config, project_config_path)
+
+    return workload_name

bedrock_agentcore_starter_toolkit/operations/runtime/launch.py

@@ -0,0 +1,163 @@
+"""Launch operation - deploys Bedrock AgentCore locally or to cloud."""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from ...services.ecr import create_ecr_repository, deploy_to_ecr
+from ...services.runtime import BedrockAgentCoreClient
+from ...utils.runtime.config import load_config, save_config
+from ...utils.runtime.container import ContainerRuntime
+from .models import LaunchResult
+
+log = logging.getLogger(__name__)
+
+
+def launch_bedrock_agentcore(
+    config_path: Path,
+    agent_name: Optional[str] = None,
+    local: bool = False,
+    push_ecr_only: bool = False,
+    env_vars: Optional[dict] = None,
+) -> LaunchResult:
+    """Launch Bedrock AgentCore locally or to cloud.
+
+    Args:
+        config_path: Path to BedrockAgentCore configuration file
+        agent_name: Name of agent to launch (for project configurations)
+        local: Whether to run locally
+        push_ecr_only: Whether to only build and push to ECR without deploying
+        env_vars: Environment variables to pass to local container (dict of key-value pairs)
+
+    Returns:
+        LaunchResult model with launch details
+    """
+    # Load project configuration
+    project_config = load_config(config_path)
+    agent_config = project_config.get_agent_config(agent_name)
+
+    # Log which agent is being launched
+    mode = "locally" if local else "to ECR only" if push_ecr_only else "to cloud"
+    log.info("Launching Bedrock AgentCore agent '%s' %s", agent_config.name, mode)
+
+    # Validate configuration
+    errors = agent_config.validate(for_local=local)
+    if errors:
+        raise ValueError(f"Invalid configuration: {', '.join(errors)}")
+
+    # Initialize container runtime
+    runtime = ContainerRuntime(agent_config.container_runtime)
+
+    # Get build context - always use project root (where config and Dockerfile are)
+    build_dir = config_path.parent
+
+    bedrock_agentcore_name = agent_config.name
+    tag = f"bedrock_agentcore-{bedrock_agentcore_name}:latest"
+
+    # Step 1: Build Docker image
+    success, output = runtime.build(build_dir, tag)
+    if not success:
+        error_lines = output[-10:] if len(output) > 10 else output
+        raise RuntimeError(f"Build failed: {' '.join(error_lines)}")
+
+    log.info("Docker image built: %s", tag)
+
+    if local:
+        # Return info for local deployment
+        return LaunchResult(
+            mode="local",
+            tag=tag,
+            port=8080,
+            runtime=runtime,
+            env_vars=env_vars,
+        )
+
+    # Step 2: Push to ECR
+    log.info("Uploading to ECR...")
+
+    region = agent_config.aws.region
+    if not region:
+        raise ValueError("Region not found in configuration")
+
+    # Handle ECR repository
+    ecr_uri = agent_config.aws.ecr_repository
+    if not ecr_uri and agent_config.aws.ecr_auto_create:
+        repo_name = f"bedrock_agentcore-{bedrock_agentcore_name}"
+        ecr_uri = create_ecr_repository(repo_name, region)
+
+        # Update the config
+        agent_config.aws.ecr_repository = ecr_uri
+        agent_config.aws.ecr_auto_create = False
+
+        # Update the project config and save
+        project_config.agents[agent_config.name] = agent_config
+        save_config(project_config, config_path)
+
+    if not ecr_uri:
+        raise ValueError("ECR repository not configured and auto-create not enabled")
+
+    # Deploy to ECR
+    repo_name = ecr_uri.split("/")[-1]
+    deploy_to_ecr(tag, repo_name, region, runtime)
+
+    log.info("Image uploaded to ECR: %s", ecr_uri)
+
+    # If push_ecr_only, return early
+    if push_ecr_only:
+        return LaunchResult(
+            mode="push-ecr",
+            tag=tag,
+            ecr_uri=ecr_uri,
+            build_output=output,
+        )
+
+    # Step 3: Deploy agent
+    log.info("Creating/updating agent...")
+
+    bedrock_agentcore_client = BedrockAgentCoreClient(region)
+
+    # Transform network configuration to AWS API format
+    network_config = agent_config.aws.network_configuration.to_aws_dict()
+    protocol_config = agent_config.aws.protocol_configuration.to_aws_dict()
+
+    if not agent_config.aws.execution_role:
+        raise ValueError("Execution role not configured")
+
+    agent_info = bedrock_agentcore_client.create_or_update_agent(
+        agent_id=agent_config.bedrock_agentcore.agent_id,
+        agent_name=bedrock_agentcore_name,
+        image_uri=f"{ecr_uri}:latest",
+        execution_role_arn=agent_config.aws.execution_role,
+        network_config=network_config,
+        authorizer_config=agent_config.get_authorizer_configuration(),
+        protocol_config=protocol_config,
+        env_vars=env_vars,
+    )
+
+    # Save deployment info
+    agent_id = agent_info["id"]
+    agent_arn = agent_info["arn"]
+
+    # Update the config
+    agent_config.bedrock_agentcore.agent_id = agent_id
+    agent_config.bedrock_agentcore.agent_arn = agent_arn
+
+    # Update the project config and save
+    project_config.agents[agent_config.name] = agent_config
+    save_config(project_config, config_path)
+
+    log.info("Agent created/updated: %s", agent_arn)
+
+    # Step 4: Wait for agent to be ready
+    log.info("Polling for endpoint to be ready...")
+    result = bedrock_agentcore_client.wait_for_agent_endpoint_ready(agent_id)
+    log.info("Agent endpoint: %s", result)
+
+    return LaunchResult(
+        mode="cloud",
+        tag=tag,
+        agent_arn=agent_arn,
+        agent_id=agent_id,
+        ecr_uri=ecr_uri,
+        build_output=output,
+    )