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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of bedrock-agentcore-starter-toolkit might be problematic. Click here for more details.

Files changed (50) hide show
  1. bedrock_agentcore_starter_toolkit/__init__.py +5 -0
  2. bedrock_agentcore_starter_toolkit/cli/cli.py +32 -0
  3. bedrock_agentcore_starter_toolkit/cli/common.py +44 -0
  4. bedrock_agentcore_starter_toolkit/cli/gateway/__init__.py +1 -0
  5. bedrock_agentcore_starter_toolkit/cli/gateway/commands.py +88 -0
  6. bedrock_agentcore_starter_toolkit/cli/runtime/__init__.py +1 -0
  7. bedrock_agentcore_starter_toolkit/cli/runtime/commands.py +651 -0
  8. bedrock_agentcore_starter_toolkit/cli/runtime/configuration_manager.py +133 -0
  9. bedrock_agentcore_starter_toolkit/notebook/__init__.py +5 -0
  10. bedrock_agentcore_starter_toolkit/notebook/runtime/__init__.py +1 -0
  11. bedrock_agentcore_starter_toolkit/notebook/runtime/bedrock_agentcore.py +239 -0
  12. bedrock_agentcore_starter_toolkit/operations/__init__.py +1 -0
  13. bedrock_agentcore_starter_toolkit/operations/gateway/README.md +277 -0
  14. bedrock_agentcore_starter_toolkit/operations/gateway/__init__.py +6 -0
  15. bedrock_agentcore_starter_toolkit/operations/gateway/client.py +456 -0
  16. bedrock_agentcore_starter_toolkit/operations/gateway/constants.py +152 -0
  17. bedrock_agentcore_starter_toolkit/operations/gateway/create_lambda.py +85 -0
  18. bedrock_agentcore_starter_toolkit/operations/gateway/create_role.py +90 -0
  19. bedrock_agentcore_starter_toolkit/operations/gateway/exceptions.py +13 -0
  20. bedrock_agentcore_starter_toolkit/operations/runtime/__init__.py +26 -0
  21. bedrock_agentcore_starter_toolkit/operations/runtime/configure.py +241 -0
  22. bedrock_agentcore_starter_toolkit/operations/runtime/create_role.py +404 -0
  23. bedrock_agentcore_starter_toolkit/operations/runtime/invoke.py +129 -0
  24. bedrock_agentcore_starter_toolkit/operations/runtime/launch.py +439 -0
  25. bedrock_agentcore_starter_toolkit/operations/runtime/models.py +79 -0
  26. bedrock_agentcore_starter_toolkit/operations/runtime/status.py +66 -0
  27. bedrock_agentcore_starter_toolkit/services/codebuild.py +332 -0
  28. bedrock_agentcore_starter_toolkit/services/ecr.py +84 -0
  29. bedrock_agentcore_starter_toolkit/services/runtime.py +473 -0
  30. bedrock_agentcore_starter_toolkit/utils/endpoints.py +32 -0
  31. bedrock_agentcore_starter_toolkit/utils/logging_config.py +72 -0
  32. bedrock_agentcore_starter_toolkit/utils/runtime/config.py +129 -0
  33. bedrock_agentcore_starter_toolkit/utils/runtime/container.py +310 -0
  34. bedrock_agentcore_starter_toolkit/utils/runtime/entrypoint.py +197 -0
  35. bedrock_agentcore_starter_toolkit/utils/runtime/logs.py +33 -0
  36. bedrock_agentcore_starter_toolkit/utils/runtime/policy_template.py +74 -0
  37. bedrock_agentcore_starter_toolkit/utils/runtime/schema.py +151 -0
  38. bedrock_agentcore_starter_toolkit/utils/runtime/templates/Dockerfile.j2 +44 -0
  39. bedrock_agentcore_starter_toolkit/utils/runtime/templates/dockerignore.template +68 -0
  40. bedrock_agentcore_starter_toolkit/utils/runtime/templates/execution_role_policy.json.j2 +98 -0
  41. bedrock_agentcore_starter_toolkit/utils/runtime/templates/execution_role_trust_policy.json.j2 +21 -0
  42. bedrock_agentcore_starter_toolkit-0.1.1.dist-info/METADATA +137 -0
  43. bedrock_agentcore_starter_toolkit-0.1.1.dist-info/RECORD +47 -0
  44. bedrock_agentcore_starter_toolkit-0.1.1.dist-info/entry_points.txt +2 -0
  45. bedrock_agentcore_starter_toolkit-0.1.1.dist-info/licenses/NOTICE.txt +190 -0
  46. bedrock_agentcore_starter_toolkit/init.py +0 -3
  47. bedrock_agentcore_starter_toolkit-0.0.1.dist-info/METADATA +0 -26
  48. bedrock_agentcore_starter_toolkit-0.0.1.dist-info/RECORD +0 -5
  49. {bedrock_agentcore_starter_toolkit-0.0.1.dist-info → bedrock_agentcore_starter_toolkit-0.1.1.dist-info}/WHEEL +0 -0
  50. /bedrock_agentcore_starter_toolkit-0.0.1.dist-info/licenses/LICENSE → /bedrock_agentcore_starter_toolkit-0.1.1.dist-info/licenses/LICENSE.txt +0 -0
@@ -0,0 +1,133 @@
1
+ """Configuration management for BedrockAgentCore runtime."""
2
+
3
+ import os
4
+ from pathlib import Path
5
+ from typing import Dict, Optional
6
+
7
+ from ..common import _handle_error, _print_success, _prompt_with_default, console
8
+
9
+
10
+ class ConfigurationManager:
11
+ """Manages interactive configuration prompts with existing configuration defaults."""
12
+
13
+ def __init__(self, config_path: Path):
14
+ """Initialize the ConfigPrompt with a configuration path.
15
+
16
+ Args:
17
+ config_path: Path to the configuration file
18
+ """
19
+ from ...utils.runtime.config import load_config_if_exists
20
+
21
+ project_config = load_config_if_exists(config_path)
22
+ self.existing_config = project_config.get_agent_config() if project_config else None
23
+
24
+ def prompt_execution_role(self) -> Optional[str]:
25
+ """Prompt for execution role. Returns role name/ARN or None for auto-creation."""
26
+ console.print("\n🔐 [cyan]Execution Role[/cyan]")
27
+ console.print(
28
+ "[dim]Press Enter to auto-create execution role, or provide execution role ARN/name to use existing[/dim]"
29
+ )
30
+
31
+ # Show existing config info but don't use as default
32
+ if self.existing_config and self.existing_config.aws.execution_role:
33
+ console.print(f"[dim]Previously configured: {self.existing_config.aws.execution_role}[/dim]")
34
+
35
+ role = _prompt_with_default("Execution role ARN/name (or press Enter to auto-create)", "")
36
+
37
+ if role:
38
+ _print_success(f"Using existing execution role: [dim]{role}[/dim]")
39
+ return role
40
+ else:
41
+ _print_success("Will auto-create execution role")
42
+ return None
43
+
44
+ def prompt_ecr_repository(self) -> tuple[Optional[str], bool]:
45
+ """Prompt for ECR repository. Returns (repository, auto_create_flag)."""
46
+ console.print("\n🏗️ [cyan]ECR Repository[/cyan]")
47
+ console.print(
48
+ "[dim]Press Enter to auto-create ECR repository, or provide ECR Repository URI to use existing[/dim]"
49
+ )
50
+
51
+ # Show existing config info but don't use as default
52
+ if self.existing_config and self.existing_config.aws.ecr_repository:
53
+ console.print(f"[dim]Previously configured: {self.existing_config.aws.ecr_repository}[/dim]")
54
+
55
+ response = _prompt_with_default("ECR Repository URI (or press Enter to auto-create)", "")
56
+
57
+ if response:
58
+ _print_success(f"Using existing ECR repository: [dim]{response}[/dim]")
59
+ return response, False
60
+ else:
61
+ _print_success("Will auto-create ECR repository")
62
+ return None, True
63
+
64
+ def prompt_oauth_config(self) -> Optional[dict]:
65
+ """Prompt for OAuth configuration. Returns OAuth config dict or None."""
66
+ console.print("\n🔐 [cyan]Authorization Configuration[/cyan]")
67
+ console.print("[dim]By default, Bedrock AgentCore uses IAM authorization.[/dim]")
68
+
69
+ existing_oauth = self.existing_config and self.existing_config.authorizer_configuration
70
+ oauth_default = "yes" if existing_oauth else "no"
71
+
72
+ response = _prompt_with_default("Configure OAuth authorizer instead? (yes/no)", oauth_default)
73
+
74
+ if response.lower() in ["yes", "y"]:
75
+ return self._configure_oauth()
76
+ else:
77
+ _print_success("Using default IAM authorization")
78
+ return None
79
+
80
+ def _configure_oauth(self) -> dict:
81
+ """Configure OAuth settings and return config dict."""
82
+ console.print("\n📋 [cyan]OAuth Configuration[/cyan]")
83
+
84
+ # Get existing OAuth values
85
+ existing_discovery_url = ""
86
+ existing_client_ids = ""
87
+ existing_audience = ""
88
+
89
+ if (
90
+ self.existing_config
91
+ and self.existing_config.authorizer_configuration
92
+ and "customJWTAuthorizer" in self.existing_config.authorizer_configuration
93
+ ):
94
+ jwt_config = self.existing_config.authorizer_configuration["customJWTAuthorizer"]
95
+ existing_discovery_url = jwt_config.get("discoveryUrl", "")
96
+ existing_client_ids = ",".join(jwt_config.get("allowedClients", []))
97
+ existing_audience = ",".join(jwt_config.get("allowedAudience", []))
98
+
99
+ # Prompt for discovery URL
100
+ default_discovery_url = existing_discovery_url or os.getenv("BEDROCK_AGENTCORE_DISCOVERY_URL", "")
101
+ discovery_url = _prompt_with_default("Enter OAuth discovery URL", default_discovery_url)
102
+
103
+ if not discovery_url:
104
+ _handle_error("OAuth discovery URL is required")
105
+
106
+ # Prompt for client IDs
107
+ default_client_id = existing_client_ids or os.getenv("BEDROCK_AGENTCORE_CLIENT_ID", "")
108
+ client_ids_input = _prompt_with_default("Enter allowed OAuth client IDs (comma-separated)", default_client_id)
109
+ # Prompt for audience
110
+ default_audience = existing_audience or os.getenv("BEDROCK_AGENTCORE_AUDIENCE", "")
111
+ audience_input = _prompt_with_default("Enter allowed OAuth audience (comma-separated)", default_audience)
112
+
113
+ if not client_ids_input and not audience_input:
114
+ _handle_error("At least one client ID or one audience is required for OAuth configuration")
115
+
116
+ # Parse and return config
117
+ client_ids = [cid.strip() for cid in client_ids_input.split(",") if cid.strip()]
118
+ audience = [aud.strip() for aud in audience_input.split(", ") if aud.strip()]
119
+
120
+ config: Dict = {
121
+ "customJWTAuthorizer": {
122
+ "discoveryUrl": discovery_url,
123
+ }
124
+ }
125
+
126
+ if client_ids:
127
+ config["customJWTAuthorizer"]["allowedClients"] = client_ids
128
+
129
+ if audience:
130
+ config["customJWTAuthorizer"]["allowedAudience"] = audience
131
+
132
+ _print_success("OAuth authorizer configuration created")
133
+ return config
@@ -0,0 +1,5 @@
1
+ """Bedrock AgentCore Starter Toolkit notebook package."""
2
+
3
+ from .runtime.bedrock_agentcore import Runtime
4
+
5
+ __all__ = ["Runtime"]
@@ -0,0 +1 @@
1
+ """Bedrock AgentCore Starter Toolkit notebook runtime package."""
@@ -0,0 +1,239 @@
1
+ """Bedrock AgentCore Notebook - Jupyter notebook interface for Bedrock AgentCore."""
2
+
3
+ import logging
4
+ from pathlib import Path
5
+ from typing import Any, Dict, List, Literal, Optional
6
+
7
+ from ...operations.runtime import (
8
+ configure_bedrock_agentcore,
9
+ get_status,
10
+ invoke_bedrock_agentcore,
11
+ launch_bedrock_agentcore,
12
+ validate_agent_name,
13
+ )
14
+ from ...operations.runtime.models import ConfigureResult, LaunchResult, StatusResult
15
+
16
+ # Setup centralized logging for SDK usage (notebooks, scripts, imports)
17
+ from ...utils.logging_config import setup_toolkit_logging
18
+ from ...utils.runtime.entrypoint import parse_entrypoint
19
+
20
+ setup_toolkit_logging(mode="sdk")
21
+
22
+ # Configure logger for this module
23
+ log = logging.getLogger(__name__)
24
+
25
+
26
+ class Runtime:
27
+ """Bedrock AgentCore for Jupyter notebooks - simplified interface for file-based configuration."""
28
+
29
+ def __init__(self):
30
+ """Initialize Bedrock AgentCore notebook interface."""
31
+ self._config_path: Optional[Path] = None
32
+ self.name = None
33
+
34
+ def configure(
35
+ self,
36
+ entrypoint: str,
37
+ execution_role: Optional[str] = None,
38
+ agent_name: Optional[str] = None,
39
+ requirements: Optional[List[str]] = None,
40
+ requirements_file: Optional[str] = None,
41
+ ecr_repository: Optional[str] = None,
42
+ container_runtime: Optional[str] = None,
43
+ auto_create_ecr: bool = True,
44
+ auto_create_execution_role: bool = False,
45
+ authorizer_configuration: Optional[Dict[str, Any]] = None,
46
+ region: Optional[str] = None,
47
+ protocol: Optional[Literal["HTTP", "MCP"]] = None,
48
+ ) -> ConfigureResult:
49
+ """Configure Bedrock AgentCore from notebook using an entrypoint file.
50
+
51
+ Args:
52
+ entrypoint: Path to Python file with optional Bedrock AgentCore name
53
+ (e.g., "handler.py" or "handler.py:bedrock_agentcore")
54
+ execution_role: AWS IAM execution role ARN or name (optional if auto_create_execution_role=True)
55
+ agent_name: name of the agent
56
+ requirements: Optional list of requirements to generate requirements.txt
57
+ requirements_file: Optional path to existing requirements file
58
+ ecr_repository: Optional ECR repository URI
59
+ container_runtime: Optional container runtime (docker/podman)
60
+ auto_create_ecr: Whether to auto-create ECR repository
61
+ auto_create_execution_role: Whether to auto-create execution role (makes execution_role optional)
62
+ authorizer_configuration: JWT authorizer configuration dictionary
63
+ region: AWS region for deployment
64
+ protocol: agent server protocol, must be either HTTP or MCP
65
+
66
+ Returns:
67
+ ConfigureResult with configuration details
68
+ """
69
+ if protocol and protocol.upper() not in ["HTTP", "MCP"]:
70
+ raise ValueError("protocol must be either HTTP or MCP")
71
+
72
+ # Parse entrypoint to get agent name
73
+ file_path, file_name = parse_entrypoint(entrypoint)
74
+ agent_name = agent_name or file_name
75
+
76
+ valid, error = validate_agent_name(agent_name)
77
+ if not valid:
78
+ raise ValueError(error)
79
+
80
+ # Validate execution role configuration
81
+ if not execution_role and not auto_create_execution_role:
82
+ raise ValueError("Must provide either 'execution_role' or set 'auto_create_execution_role=True'")
83
+
84
+ # Update our name if not already set
85
+ if not self.name:
86
+ self.name = agent_name
87
+
88
+ # Handle requirements
89
+ final_requirements_file = requirements_file
90
+
91
+ if requirements and not requirements_file:
92
+ # Create requirements.txt in the same directory as the handler
93
+ handler_dir = Path(file_path).parent
94
+ req_file_path = handler_dir / "requirements.txt"
95
+
96
+ all_requirements = [] # "bedrock_agentcore" # Always include bedrock_agentcore
97
+ all_requirements.extend(requirements)
98
+
99
+ req_file_path.write_text("\n".join(all_requirements))
100
+ log.info("Generated requirements.txt: %s", req_file_path)
101
+
102
+ final_requirements_file = str(req_file_path)
103
+
104
+ # Configure using the operations module
105
+ result = configure_bedrock_agentcore(
106
+ agent_name=agent_name,
107
+ entrypoint_path=Path(file_path),
108
+ auto_create_execution_role=auto_create_execution_role,
109
+ execution_role=execution_role,
110
+ ecr_repository=ecr_repository,
111
+ container_runtime=container_runtime,
112
+ auto_create_ecr=auto_create_ecr,
113
+ requirements_file=final_requirements_file,
114
+ authorizer_configuration=authorizer_configuration,
115
+ region=region,
116
+ protocol=protocol.upper() if protocol else None,
117
+ )
118
+
119
+ self._config_path = result.config_path
120
+ log.info("Bedrock AgentCore configured: %s", self._config_path)
121
+ return result
122
+
123
+ def launch(
124
+ self,
125
+ local: bool = False,
126
+ push_ecr: bool = False,
127
+ use_codebuild: bool = False,
128
+ auto_update_on_conflict: bool = False,
129
+ env_vars: Optional[Dict] = None,
130
+ ) -> LaunchResult:
131
+ """Launch Bedrock AgentCore from notebook.
132
+
133
+ Args:
134
+ local: Whether to build for local execution only
135
+ push_ecr: Whether to push to ECR only (no deployment)
136
+ use_codebuild: Whether to use CodeBuild for ARM64 builds (cloud deployment only)
137
+ auto_update_on_conflict: Whether to automatically update resources on conflict (default: False)
138
+ env_vars: environment variables for agent container
139
+
140
+ Returns:
141
+ LaunchResult with deployment details
142
+ """
143
+ if not self._config_path:
144
+ raise ValueError("Must configure before launching. Call .configure() first.")
145
+
146
+ # Validate mutually exclusive options
147
+ exclusive_options = [local, push_ecr, use_codebuild]
148
+ if sum(exclusive_options) > 1:
149
+ raise ValueError("Only one of 'local', 'push_ecr', or 'use_codebuild' can be True")
150
+
151
+ result = launch_bedrock_agentcore(
152
+ self._config_path,
153
+ local=local,
154
+ push_ecr_only=push_ecr,
155
+ use_codebuild=use_codebuild,
156
+ auto_update_on_conflict=auto_update_on_conflict,
157
+ env_vars=env_vars,
158
+ )
159
+
160
+ if result.mode == "cloud":
161
+ log.info("Deployed to cloud: %s", result.agent_arn)
162
+ # Show log information for cloud deployments
163
+ if result.agent_id:
164
+ from ...utils.runtime.logs import get_agent_log_paths, get_aws_tail_commands
165
+
166
+ runtime_logs, otel_logs = get_agent_log_paths(result.agent_id)
167
+ follow_cmd, since_cmd = get_aws_tail_commands(runtime_logs)
168
+ log.info("🔍 Agent logs available at:")
169
+ log.info(" %s", runtime_logs)
170
+ log.info(" %s", otel_logs)
171
+ log.info("💡 Tail logs with: %s", follow_cmd)
172
+ log.info("💡 Or view recent logs: %s", since_cmd)
173
+ elif result.mode == "codebuild":
174
+ log.info("Built with CodeBuild: %s", result.codebuild_id)
175
+ log.info("Deployed to cloud: %s", result.agent_arn)
176
+ log.info("ECR image: %s", result.ecr_uri)
177
+ # Show log information for CodeBuild deployments
178
+ if result.agent_id:
179
+ from ...utils.runtime.logs import get_agent_log_paths, get_aws_tail_commands
180
+
181
+ runtime_logs, otel_logs = get_agent_log_paths(result.agent_id)
182
+ follow_cmd, since_cmd = get_aws_tail_commands(runtime_logs)
183
+ log.info("🔍 Agent logs available at:")
184
+ log.info(" %s", runtime_logs)
185
+ log.info(" %s", otel_logs)
186
+ log.info("💡 Tail logs with: %s", follow_cmd)
187
+ log.info("💡 Or view recent logs: %s", since_cmd)
188
+ elif result.mode == "push-ecr":
189
+ log.info("Pushed to ECR: %s", result.ecr_uri)
190
+ else:
191
+ log.info("Built for local: %s", result.tag)
192
+
193
+ return result
194
+
195
+ def invoke(
196
+ self,
197
+ payload: Dict[str, Any],
198
+ session_id: Optional[str] = None,
199
+ bearer_token: Optional[str] = None,
200
+ local: Optional[bool] = False,
201
+ user_id: Optional[str] = None,
202
+ ) -> Dict[str, Any]:
203
+ """Invoke deployed Bedrock AgentCore endpoint.
204
+
205
+ Args:
206
+ payload: Dictionary payload to send
207
+ session_id: Optional session ID for conversation continuity
208
+ bearer_token: Optional bearer token for HTTP authentication
209
+ local: Send request to a running local container
210
+ user_id: User id for authorization flows
211
+
212
+ Returns:
213
+ Response from the Bedrock AgentCore endpoint
214
+ """
215
+ if not self._config_path:
216
+ raise ValueError("Must configure and launch first.")
217
+
218
+ result = invoke_bedrock_agentcore(
219
+ config_path=self._config_path,
220
+ payload=payload,
221
+ session_id=session_id,
222
+ bearer_token=bearer_token,
223
+ local_mode=local,
224
+ user_id=user_id,
225
+ )
226
+ return result.response
227
+
228
+ def status(self) -> StatusResult:
229
+ """Get Bedrock AgentCore status including config and runtime details.
230
+
231
+ Returns:
232
+ StatusResult with configuration, agent, and endpoint status
233
+ """
234
+ if not self._config_path:
235
+ raise ValueError("Must configure first. Call .configure() first.")
236
+
237
+ result = get_status(self._config_path)
238
+ log.info("Retrieved Bedrock AgentCore status for: %s", self.name or "Bedrock AgentCore")
239
+ return result
@@ -0,0 +1 @@
1
+ """BedrockAgentCore Starter Toolkit operations."""
@@ -0,0 +1,277 @@
1
+ # Bedrock AgentCore Gateway
2
+
3
+ Bedrock AgentCore Gateway is a primitive within the Bedrock AgentCore SDK that enables you to:
4
+ - Convert REST APIs (OpenAPI) into MCP tools
5
+ - Expose Lambda functions as MCP tools
6
+ - Handle authentication automatically with EZ Auth
7
+ - Enable semantic search across your tools
8
+
9
+ ## Quick Start
10
+
11
+ ### Using the CLI (Recommended)
12
+
13
+ ```bash
14
+ # Create a Gateway to use with targets defined in OpenAPI or Smithy
15
+ agentcore create_mcp_gateway \
16
+ --region us-west-2 \
17
+ --name gateway-name
18
+
19
+ # Create a Gateway Target with predefined smithy model
20
+ agentcore create_mcp_gateway_target \
21
+ --region us-west-2 \
22
+ --gateway-arn arn:aws:bedrock-agentcore:us-west-2:123:gateway/gateway-id \
23
+ --gateway-url https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
24
+ --role-arn arn:aws:iam::123:role/BedrockAgentCoreGatewayRole \
25
+ --target-type smithyModel
26
+
27
+ # Create a Gateway Target with OpenAPI target (OAuth with API Key)
28
+ agentcore create_mcp_gateway_target \
29
+ --region us-west-2 \
30
+ --gateway-arn arn:aws:bedrock-agentcore:us-west-2:123:gateway/gateway-id \
31
+ --gateway-url https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
32
+ --role-arn arn:aws:iam::123:role/BedrockAgentCoreGatewayRole \
33
+ --target-type openApiSchema \
34
+ --credentials "{\"api_key\": \"Bearer 123234bc\", \"credential_location\": \"HEADER\", \"credential_parameter_name\": \"Authorization\"}" \
35
+ --target-payload "{\"s3\": { \"uri\": \"s3://openapischemas/sample-openapi-schema.json\", \"bucketOwnerAccountId\": \"012345678912\"}}"
36
+
37
+ # Create a Gateway Target with OpenAPI target (OAuth with credential provider)
38
+ agentcore create_mcp_gateway_target \
39
+ --region us-west-2 \
40
+ --gateway-arn arn:aws:bedrock-agentcore:us-west-2:123:gateway/gateway-id \
41
+ --gateway-url https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
42
+ --role-arn arn:aws:iam::123:role/BedrockAgentCoreGatewayRole \
43
+ --target-type openApiSchema \
44
+ --credentials "{\"oauth2_provider_config\": { \"customOauth2ProviderConfig\": {\"oauthDiscovery\" : {\"authorizationServerMetadata\" : {\"issuer\" : \"<issuer>\",\"authorizationEndpoint\" : \"<authorizationEndpoint>\",\"tokenEndpoint\" : \"<tokenEndpoint>\"}},\"clientId\" : \"<clientId>\",\"clientSecret\" : \"<clientSecret>\" }}}" \
45
+ --target-payload "{\"s3\": { \"uri\": \"s3://openapischemas/sample-openapi-schema.json\", \"bucketOwnerAccountId\": \"012345678912\"}}"
46
+ ```
47
+
48
+ The CLI automatically:
49
+ - Detects target type from ARN patterns or file extensions
50
+ - Sets up Cognito OAuth (EZ Auth)
51
+ - Detects your AWS region and account
52
+ - Builds full role ARN from role name
53
+
54
+
55
+ ### Using the SDK
56
+
57
+ For programmatic access in scripts, notebooks, or CI/CD:
58
+
59
+ ```python
60
+ from bedrock_agentcore_starter_toolkit.operations.gateway.client import GatewayClient
61
+ import json
62
+
63
+ # Initialize client
64
+ client = GatewayClient(region_name='us-west-2')
65
+
66
+ # EZ Auth - automatically sets up Cognito OAuth
67
+ cognito_result = client.create_oauth_authorizer_with_cognito("my-gateway")
68
+
69
+ # Create Gateway with OpenAPI schema target
70
+ gateway = client.create_mcp_gateway(
71
+ name="my-gateway",
72
+ role_arn="arn:aws:iam::123:role/BedrockAgentCoreGatewayExecutionRole",
73
+ authorizer_config=cognito_result['authorizer_config']
74
+ )
75
+
76
+ target = client.create_mcp_gateway_target(
77
+ gateway=gateway,
78
+ name="sample_target",
79
+ target_type='openApiSchema',
80
+ target_payload= {
81
+ "s3": {
82
+ "uri": "s3://openapischemas/sample-openapi-schema.json",
83
+ "bucketOwnerAccountId": "012345678912"
84
+ }
85
+ },
86
+ credentials={
87
+ "api_key": "abc123",
88
+ "credential_location": "HEADER",
89
+ "credential_parameter_name": "Authorization"
90
+ }
91
+ )
92
+ print(f"MCP Endpoint: {gateway['gatewayUrl']}")
93
+ print(f"OAuth Credentials:")
94
+ print(f" Client ID: {cognito_result['client_info']['client_id']}")
95
+ print(f" Client Secret: {cognito_result['client_info']['client_secret']}")
96
+ print(f" Scope: {cognito_result['client_info']['scope']}")
97
+ ```
98
+
99
+ ## Key Features
100
+
101
+ ### EZ Auth
102
+ Eliminates the complexity of OAuth setup:
103
+ ```python
104
+ # Without EZ Auth: 8+ manual steps
105
+ # With EZ Auth: 1 line
106
+ cognito_result = client.create_oauth_authorizer_with_cognito("my-gateway")
107
+ ```
108
+
109
+ ### Semantic Search
110
+ Enable intelligent tool discovery:
111
+ ```python
112
+ gateway = client.create_mcp_gateway(
113
+ name="my-gateway",
114
+ role_arn="arn:aws:iam::123:role/BedrockAgentCoreGatewayExecutionRole",
115
+ authorizer_config=cognito_result['authorizer_config'],
116
+ enable_semantic_search=True # Enable semantic search.
117
+ )
118
+ ```
119
+
120
+ ### Multiple Target Types
121
+
122
+ #### Lambda Functions
123
+ ```python
124
+ # Auto-generated schema (default)
125
+ gateway = client.create_mcp_gateway(
126
+ name="my-gateway",
127
+ role_arn="arn:aws:iam::123:role/BedrockAgentCoreGatewayExecutionRole",
128
+ authorizer_config=cognito_result['authorizer_config']
129
+ )
130
+
131
+ # Create a lambda target
132
+ lambda_target = client.create_mcp_gateway_target(
133
+ name="lambda-target",
134
+ gateway=gateway,
135
+ target_type='lambda'
136
+ )
137
+ ```
138
+
139
+ #### OpenAPI (REST APIs)
140
+ ```python
141
+ # Inline OpenAPI
142
+ openapi_spec = {
143
+ "openapi": "3.0.0",
144
+ "info": {"title": "My API", "version": "1.0.0"},
145
+ "servers": [{"url": "https://api.example.com"}],
146
+ "paths": {
147
+ "/users": {
148
+ "get": {
149
+ "operationId": "listUsers",
150
+ "responses": {"200": {"description": "Success"}}
151
+ }
152
+ }
153
+ }
154
+ }
155
+ openAPI_inline_target = client.create_mcp_gateway_target(
156
+ name="inlineTarget",
157
+ gateway=gateway,
158
+ credentials={
159
+ "api_key": "abc123",
160
+ "credential_location": "HEADER",
161
+ "credential_parameter_name": "Authorization"
162
+ },
163
+ target_type='openApiSchema',
164
+ target_payload= {
165
+ "inlinePayload": openapi_spec
166
+ }
167
+ )
168
+
169
+ # From S3
170
+ openAPI_target = client.create_mcp_gateway_target(
171
+ name="s3target",
172
+ gateway=gateway,
173
+ credentials={
174
+ "api_key": "abc123",
175
+ "credential_location": "HEADER",
176
+ "credential_parameter_name": "Authorization"
177
+ },
178
+ target_type='openApiSchema',
179
+ target_payload= {
180
+ "s3": {
181
+ "uri": "s3://openapischemas/sample-openapi-schema.json",
182
+ "bucketOwnerAccountId": "012345678912"
183
+ }
184
+ }
185
+ )
186
+ ```
187
+
188
+ ## MCP Integration
189
+
190
+ Once created, use any MCP client to interact with your Gateway:
191
+
192
+ ```python
193
+ import httpx
194
+
195
+ # Get token
196
+ token = client.get_access_token_for_cognito(cognito_result['client_info'])
197
+
198
+ # List tools
199
+ async with httpx.AsyncClient() as http:
200
+ response = await http.post(
201
+ gateway['gatewayUrl'],
202
+ headers={"Authorization": f"Bearer {token}"},
203
+ json={
204
+ "jsonrpc": "2.0",
205
+ "id": 1,
206
+ "method": "tools/list",
207
+ "params": {}
208
+ }
209
+ )
210
+ tools = response.json()
211
+
212
+ # Invoke a tool
213
+ response = await http.post(
214
+ gateway['gatewayUrl'],
215
+ headers={"Authorization": f"Bearer {token}"},
216
+ json={
217
+ "jsonrpc": "2.0",
218
+ "id": 2,
219
+ "method": "tools/call",
220
+ "params": {
221
+ "name": "listUsers",
222
+ "arguments": {}
223
+ }
224
+ }
225
+ )
226
+ ```
227
+
228
+ ## Prerequisites
229
+
230
+ **AWS Account**: Must be allowlisted for Bedrock AgentCore beta
231
+ **IAM Execution Role**: With trust relationship to BedrockAgentCore service
232
+ **Permissions**: Role needs access to your backends (Lambda invoke, S3 read, etc.)
233
+ **Custom Boto3 SDK**: Download from Bedrock AgentCore documentation
234
+
235
+ ## Testing
236
+
237
+ See `tests/bedrock_agentcore/gateway/` for integration tests covering all target types.
238
+
239
+ ## API Reference
240
+
241
+ ### GatewayClient
242
+
243
+ - `create_oauth_authorizer_with_cognito(gateway_name)` - Set up Cognito OAuth automatically
244
+ - `create_mcp_gateway(...)` - Create a gateway
245
+ - `create_mcp_gateway_target(...)` - Create a gateway target
246
+ - `get_test_token_for_cognito(client_info)` - Get OAuth token for testing
247
+
248
+ ### List of all builtin schemas
249
+ ```doc
250
+ 1. confluence
251
+ 2. onedrive
252
+ 3. dynamodb
253
+ 4. cloudwatch
254
+ 5. slack
255
+ 6. smartsheet
256
+ 7. sap-business-partner
257
+ 8. tavily
258
+ 9. jira
259
+ 10. sap-product-master-data
260
+ 11. genericHTTP
261
+ 12. sap-material-stock
262
+ 13. sap-physical-inventory
263
+ 14. salesforce
264
+ 15. servicenow
265
+ 16. bambooHR
266
+ 17. brave-search
267
+ 18. msExchange
268
+ 19. sap-bill-of-material
269
+ 20. sharepoint
270
+ 21. asana
271
+ 22. zendesk
272
+ 23. msTeams
273
+ 24. pagerduty
274
+ 25. zoom
275
+ 26. bedrock-runtime
276
+ 27. bedrock-agent-runtime
277
+ ```
@@ -0,0 +1,6 @@
1
+ """BedrockAgentCore Starter Toolkit cli gateway package."""
2
+
3
+ from .client import GatewayClient
4
+ from .exceptions import GatewayException, GatewaySetupException
5
+
6
+ __all__ = ["GatewayClient", "GatewayException", "GatewaySetupException"]