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

bedrock_agentcore_starter_toolkit/cli/runtime/configuration_manager.py

@@ -0,0 +1,124 @@
+"""Configuration management for BedrockAgentCore runtime."""
+
+import os
+from pathlib import Path
+from typing import Dict, Optional
+
+from ..common import _handle_error, _print_success, _prompt_with_default, console
+
+
+class ConfigurationManager:
+    """Manages interactive configuration prompts with existing configuration defaults."""
+
+    def __init__(self, config_path: Path):
+        """Initialize the ConfigPrompt with a configuration path.
+
+        Args:
+            config_path: Path to the configuration file
+        """
+        from ...utils.runtime.config import load_config_if_exists
+
+        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."""
+        console.print("\n🔐 [cyan]Execution Role[/cyan]")
+        console.print("[dim]Execution role is required for deployment[/dim]")
+
+        default = self.existing_config.aws.execution_role if self.existing_config else ""
+        role = _prompt_with_default("Enter execution role ARN or name", default)
+
+        if not role:
+            _handle_error("Execution role is required")
+
+        _print_success(f"Using execution role: [dim]{role}[/dim]")
+        return role
+
+    def prompt_ecr_repository(self) -> tuple[Optional[str], bool]:
+        """Prompt for ECR repository. Returns (repository, auto_create_flag)."""
+        console.print("\n🏗️  [cyan]ECR Repository[/cyan]")
+        console.print(
+            "[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)
+
+        if response:
+            _print_success(f"Using existing ECR repository: [dim]{response}[/dim]")
+            return response, False
+        else:
+            _print_success("Will auto-create ECR repository")
+            return None, True
+
+    def prompt_oauth_config(self) -> Optional[dict]:
+        """Prompt for OAuth configuration. Returns OAuth config dict or None."""
+        console.print("\n🔐 [cyan]Authorization Configuration[/cyan]")
+        console.print("[dim]By default, Bedrock AgentCore uses IAM authorization.[/dim]")
+
+        existing_oauth = self.existing_config and self.existing_config.authorizer_configuration
+        oauth_default = "yes" if existing_oauth else "no"
+
+        response = _prompt_with_default("Configure OAuth authorizer instead? (yes/no)", oauth_default)
+
+        if response.lower() in ["yes", "y"]:
+            return self._configure_oauth()
+        else:
+            _print_success("Using default IAM authorization")
+            return None
+
+    def _configure_oauth(self) -> dict:
+        """Configure OAuth settings and return config dict."""
+        console.print("\n📋 [cyan]OAuth Configuration[/cyan]")
+
+        # Get existing OAuth values
+        existing_discovery_url = ""
+        existing_client_ids = ""
+        existing_audience = ""
+
+        if (
+            self.existing_config
+            and self.existing_config.authorizer_configuration
+            and "customJWTAuthorizer" in self.existing_config.authorizer_configuration
+        ):
+            jwt_config = self.existing_config.authorizer_configuration["customJWTAuthorizer"]
+            existing_discovery_url = jwt_config.get("discoveryUrl", "")
+            existing_client_ids = ",".join(jwt_config.get("allowedClients", []))
+            existing_audience = ",".join(jwt_config.get("allowedAudience", []))
+
+        # Prompt for discovery URL
+        default_discovery_url = existing_discovery_url or os.getenv("BEDROCK_AGENTCORE_DISCOVERY_URL", "")
+        discovery_url = _prompt_with_default("Enter OAuth discovery URL", default_discovery_url)
+
+        if not discovery_url:
+            _handle_error("OAuth discovery URL is required")
+
+        # Prompt for client IDs
+        default_client_id = existing_client_ids or os.getenv("BEDROCK_AGENTCORE_CLIENT_ID", "")
+        client_ids_input = _prompt_with_default("Enter allowed OAuth client IDs (comma-separated)", default_client_id)
+        # Prompt for audience
+        default_audience = existing_audience or os.getenv("BEDROCK_AGENTCORE_AUDIENCE", "")
+        audience_input = _prompt_with_default("Enter allowed OAuth audience (comma-separated)", default_audience)
+
+        if not client_ids_input and not audience_input:
+            _handle_error("At least one client ID or one audience is required for OAuth configuration")
+
+        # Parse and return config
+        client_ids = [cid.strip() for cid in client_ids_input.split(",") if cid.strip()]
+        audience = [aud.strip() for aud in audience_input.split(", ") if aud.strip()]
+
+        config: Dict = {
+            "customJWTAuthorizer": {
+                "discoveryUrl": discovery_url,
+            }
+        }
+
+        if client_ids:
+            config["customJWTAuthorizer"]["allowedClients"] = client_ids
+
+        if audience:
+            config["customJWTAuthorizer"]["allowedAudience"] = audience
+
+        _print_success("OAuth authorizer configuration created")
+        return config

bedrock_agentcore_starter_toolkit/notebook/__init__.py

@@ -0,0 +1,5 @@
+"""Bedrock AgentCore Starter Toolkit notebook package."""
+
+from .runtime.bedrock_agentcore import Runtime
+
+__all__ = ["Runtime"]

bedrock_agentcore_starter_toolkit/notebook/runtime/__init__.py

@@ -0,0 +1 @@
+"""Bedrock AgentCore Starter Toolkit notebook runtime package."""

bedrock_agentcore_starter_toolkit/notebook/runtime/bedrock_agentcore.py

@@ -0,0 +1,196 @@
+"""Bedrock AgentCore Notebook - Jupyter notebook interface for Bedrock AgentCore."""
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional
+
+from ...operations.runtime import (
+    configure_bedrock_agentcore,
+    get_status,
+    invoke_bedrock_agentcore,
+    launch_bedrock_agentcore,
+    validate_agent_name,
+)
+from ...operations.runtime.models import ConfigureResult, LaunchResult, StatusResult
+from ...utils.runtime.entrypoint import parse_entrypoint
+
+# Configure logger for notebook use
+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:
+    """Bedrock AgentCore for Jupyter notebooks - simplified interface for file-based configuration."""
+
+    def __init__(self):
+        """Initialize Bedrock AgentCore notebook interface."""
+        self._config_path: Optional[Path] = None
+        self.name = None
+
+    def configure(
+        self,
+        entrypoint: str,
+        execution_role: str,
+        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,
+        authorizer_configuration: Optional[Dict[str, Any]] = None,
+        region: Optional[str] = None,
+        protocol: Optional[Literal["HTTP", "MCP"]] = None,
+    ) -> ConfigureResult:
+        """Configure Bedrock AgentCore from notebook using an entrypoint file.
+
+        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
+            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
+            authorizer_configuration: JWT authorizer configuration dictionary
+            region: AWS region for deployment
+            protocol: agent server protocol, must be either HTTP or MCP
+
+        Returns:
+            ConfigureResult with configuration details
+        """
+        if protocol and protocol.upper() not in ["HTTP", "MCP"]:
+            raise ValueError("protocol must be either HTTP or MCP")
+
+        # Parse entrypoint to get agent name
+        file_path, file_name = parse_entrypoint(entrypoint)
+        agent_name = agent_name or file_name
+
+        valid, error = validate_agent_name(agent_name)
+        if not valid:
+            raise ValueError(error)
+
+        # Update our name if not already set
+        if not self.name:
+            self.name = agent_name
+
+        # Handle requirements
+        final_requirements_file = requirements_file
+
+        if requirements and not requirements_file:
+            # Create requirements.txt in the same directory as the handler
+            handler_dir = Path(file_path).parent
+            req_file_path = handler_dir / "requirements.txt"
+
+            all_requirements = []  # "bedrock_agentcore" # Always include bedrock_agentcore
+            all_requirements.extend(requirements)
+
+            req_file_path.write_text("\n".join(all_requirements))
+            log.info("Generated requirements.txt: %s", req_file_path)
+
+            final_requirements_file = str(req_file_path)
+
+        # Configure using the operations module
+        result = configure_bedrock_agentcore(
+            agent_name=agent_name,
+            entrypoint_path=Path(file_path),
+            execution_role=execution_role,
+            ecr_repository=ecr_repository,
+            container_runtime=container_runtime,
+            auto_create_ecr=auto_create_ecr,
+            requirements_file=final_requirements_file,
+            authorizer_configuration=authorizer_configuration,
+            region=region,
+            protocol=protocol.upper() if protocol else None,
+        )
+
+        self._config_path = result.config_path
+        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:
+        """Launch Bedrock AgentCore from notebook.
+
+        Args:
+            local: Whether to build for local execution only
+            push_ecr: Whether to push to ECR only (no deployment)
+            env_vars: environment variables for agent container
+
+        Returns:
+            LaunchResult with deployment details
+        """
+        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)
+
+        if result.mode == "cloud":
+            log.info("Deployed to cloud: %s", result.agent_arn)
+            # Show log information for cloud 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:")
+                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 == "push-ecr":
+            log.info("Pushed to ECR: %s", result.ecr_uri)
+        else:
+            log.info("Built for local: %s", result.tag)
+
+        return result
+
+    def invoke(
+        self,
+        payload: Dict[str, Any],
+        session_id: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        local: Optional[bool] = False,
+        user_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Invoke deployed Bedrock AgentCore endpoint.
+
+        Args:
+            payload: Dictionary payload to send
+            session_id: Optional session ID for conversation continuity
+            bearer_token: Optional bearer token for HTTP authentication
+            local: Send request to a running local container
+            user_id: User id for authorization flows
+
+        Returns:
+            Response from the Bedrock AgentCore endpoint
+        """
+        if not self._config_path:
+            raise ValueError("Must configure and launch first.")
+
+        result = invoke_bedrock_agentcore(
+            config_path=self._config_path,
+            payload=payload,
+            session_id=session_id,
+            bearer_token=bearer_token,
+            local_mode=local,
+            user_id=user_id,
+        )
+        return result.response
+
+    def status(self) -> StatusResult:
+        """Get Bedrock AgentCore status including config and runtime details.
+
+        Returns:
+            StatusResult with configuration, agent, and endpoint status
+        """
+        if not self._config_path:
+            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

bedrock_agentcore_starter_toolkit/operations/__init__.py

@@ -0,0 +1 @@
+"""BedrockAgentCore Starter Toolkit operations."""

bedrock_agentcore_starter_toolkit/operations/gateway/README.md

@@ -0,0 +1,277 @@
+# Bedrock AgentCore Gateway
+
+Bedrock AgentCore Gateway is a primitive within the Bedrock AgentCore SDK that enables you to:
+- Convert REST APIs (OpenAPI) into MCP tools
+- Expose Lambda functions as MCP tools
+- Handle authentication automatically with EZ Auth
+- Enable semantic search across your tools
+
+## Quick Start
+
+### Using the CLI (Recommended)
+
+```bash
+# Create a Gateway to use with targets defined in OpenAPI or Smithy
+agentcore create_mcp_gateway \
+--region us-west-2 \
+--name gateway-name
+
+# 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 \
+--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 \
+--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 \
+--credentials "{\"api_key\": \"Bearer 123234bc\", \"credential_location\": \"HEADER\", \"credential_parameter_name\": \"Authorization\"}" \
+--target-payload "{\"s3\": { \"uri\": \"s3://openapischemas/sample-openapi-schema.json\", \"bucketOwnerAccountId\": \"012345678912\"}}"
+
+# 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 \
+--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 \
+--credentials "{\"oauth2_provider_config\": { \"customOauth2ProviderConfig\": {\"oauthDiscovery\" : {\"authorizationServerMetadata\" : {\"issuer\" : \"<issuer>\",\"authorizationEndpoint\" : \"<authorizationEndpoint>\",\"tokenEndpoint\" : \"<tokenEndpoint>\"}},\"clientId\" : \"<clientId>\",\"clientSecret\" : \"<clientSecret>\" }}}" \
+--target-payload "{\"s3\": { \"uri\": \"s3://openapischemas/sample-openapi-schema.json\", \"bucketOwnerAccountId\": \"012345678912\"}}"
+```
+
+The CLI automatically:
+- Detects target type from ARN patterns or file extensions
+- Sets up Cognito OAuth (EZ Auth)
+- Detects your AWS region and account
+- Builds full role ARN from role name
+
+
+### Using the SDK
+
+For programmatic access in scripts, notebooks, or CI/CD:
+
+```python
+from bedrock_agentcore_starter_toolkit.operations.gateway.client import GatewayClient
+import json
+
+# Initialize client
+client = GatewayClient(region_name='us-west-2')
+
+# EZ Auth - automatically sets up Cognito OAuth
+cognito_result = client.create_oauth_authorizer_with_cognito("my-gateway")
+
+# Create Gateway with OpenAPI schema target
+gateway = client.create_mcp_gateway(
+    name="my-gateway",
+    role_arn="arn:aws:iam::123:role/BedrockAgentCoreGatewayExecutionRole",
+    authorizer_config=cognito_result['authorizer_config']
+)
+
+target = client.create_mcp_gateway_target(
+    gateway=gateway,
+    name="sample_target",
+    target_type='openApiSchema',
+    target_payload= {
+        "s3": {
+            "uri": "s3://openapischemas/sample-openapi-schema.json",
+            "bucketOwnerAccountId": "012345678912"
+        }
+    },
+    credentials={
+        "api_key": "abc123",
+        "credential_location": "HEADER",
+        "credential_parameter_name": "Authorization"
+    }
+)
+print(f"MCP Endpoint: {gateway['gatewayUrl']}")
+print(f"OAuth Credentials:")
+print(f"  Client ID: {cognito_result['client_info']['client_id']}")
+print(f"  Client Secret: {cognito_result['client_info']['client_secret']}")
+print(f"  Scope: {cognito_result['client_info']['scope']}")
+```
+
+## Key Features
+
+### EZ Auth
+Eliminates the complexity of OAuth setup:
+```python
+# Without EZ Auth: 8+ manual steps
+# With EZ Auth: 1 line
+cognito_result = client.create_oauth_authorizer_with_cognito("my-gateway")
+```
+
+### Semantic Search
+Enable intelligent tool discovery:
+```python
+gateway = client.create_mcp_gateway(
+    name="my-gateway",
+    role_arn="arn:aws:iam::123:role/BedrockAgentCoreGatewayExecutionRole",
+    authorizer_config=cognito_result['authorizer_config'],
+    enable_semantic_search=True # Enable semantic search.
+)
+```
+
+### Multiple Target Types
+
+#### Lambda Functions
+```python
+# Auto-generated schema (default)
+gateway = client.create_mcp_gateway(
+    name="my-gateway",
+    role_arn="arn:aws:iam::123:role/BedrockAgentCoreGatewayExecutionRole",
+    authorizer_config=cognito_result['authorizer_config']
+)
+
+# Create a lambda target
+lambda_target = client.create_mcp_gateway_target(
+    name="lambda-target",
+    gateway=gateway,
+    target_type='lambda'
+)
+```
+
+#### OpenAPI (REST APIs)
+```python
+# Inline OpenAPI
+openapi_spec = {
+    "openapi": "3.0.0",
+    "info": {"title": "My API", "version": "1.0.0"},
+    "servers": [{"url": "https://api.example.com"}],
+    "paths": {
+        "/users": {
+            "get": {
+                "operationId": "listUsers",
+                "responses": {"200": {"description": "Success"}}
+            }
+        }
+    }
+}
+openAPI_inline_target = client.create_mcp_gateway_target(
+    name="inlineTarget",
+    gateway=gateway,
+    credentials={
+        "api_key": "abc123",
+        "credential_location": "HEADER",
+        "credential_parameter_name": "Authorization"
+    },
+    target_type='openApiSchema',
+    target_payload= {
+        "inlinePayload": openapi_spec
+    }
+)
+
+# From S3
+openAPI_target = client.create_mcp_gateway_target(
+    name="s3target",
+    gateway=gateway,
+    credentials={
+        "api_key": "abc123",
+        "credential_location": "HEADER",
+        "credential_parameter_name": "Authorization"
+    },
+    target_type='openApiSchema',
+    target_payload= {
+        "s3": {
+            "uri": "s3://openapischemas/sample-openapi-schema.json",
+            "bucketOwnerAccountId": "012345678912"
+        }
+    }
+)
+```
+
+## MCP Integration
+
+Once created, use any MCP client to interact with your Gateway:
+
+```python
+import httpx
+
+# Get token
+token = client.get_access_token_for_cognito(cognito_result['client_info'])
+
+# List tools
+async with httpx.AsyncClient() as http:
+    response = await http.post(
+        gateway['gatewayUrl'],
+        headers={"Authorization": f"Bearer {token}"},
+        json={
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/list",
+            "params": {}
+        }
+    )
+    tools = response.json()
+
+# Invoke a tool
+response = await http.post(
+    gateway['gatewayUrl'],
+    headers={"Authorization": f"Bearer {token}"},
+    json={
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "tools/call",
+        "params": {
+            "name": "listUsers",
+            "arguments": {}
+        }
+    }
+)
+```
+
+## Prerequisites
+
+**AWS Account**: Must be allowlisted for Bedrock AgentCore beta
+**IAM Execution Role**: With trust relationship to BedrockAgentCore service
+**Permissions**: Role needs access to your backends (Lambda invoke, S3 read, etc.)
+**Custom Boto3 SDK**: Download from Bedrock AgentCore documentation
+
+## Testing
+
+See `tests/bedrock_agentcore/gateway/` for integration tests covering all target types.
+
+## API Reference
+
+### GatewayClient
+
+- `create_oauth_authorizer_with_cognito(gateway_name)` - Set up Cognito OAuth automatically
+- `create_mcp_gateway(...)` - Create a gateway
+- `create_mcp_gateway_target(...)` - Create a gateway target
+- `get_test_token_for_cognito(client_info)` - Get OAuth token for testing
+
+### List of all builtin schemas
+```doc
+1. confluence
+2. onedrive
+3. dynamodb
+4. cloudwatch
+5. slack
+6. smartsheet
+7. sap-business-partner
+8. tavily
+9. jira
+10. sap-product-master-data
+11. genericHTTP
+12. sap-material-stock
+13. sap-physical-inventory
+14. salesforce
+15. servicenow
+16. bambooHR
+17. brave-search
+18. msExchange
+19. sap-bill-of-material
+20. sharepoint
+21. asana
+22. zendesk
+23. msTeams
+24. pagerduty
+25. zoom
+26. bedrock-runtime
+27. bedrock-agent-runtime
+```

bedrock_agentcore_starter_toolkit/operations/gateway/__init__.py

@@ -0,0 +1,6 @@
+"""BedrockAgentCore Starter Toolkit cli gateway package."""
+
+from .client import GatewayClient
+from .exceptions import GatewayException, GatewaySetupException
+
+__all__ = ["GatewayClient", "GatewayException", "GatewaySetupException"]