feat/agentcore improvement (Faster MCP Load, AgentCore Gateway Support, etc)

docs/en/DEPLOY_OPTION.md

@@ -681,41 +681,44 @@ const envs: Record<string, Partial<StackInput>> = {
 }
 ```
 
-### Enabling AgentCore Use Cases
+### Enabling AgentCore Use Case
 
 This is a use case for integrating with agents created in AgentCore. (Experimental: Breaking changes may be made without notice)
 
 Enabling `createGenericAgentCoreRuntime` will deploy the default AgentCore Runtime.
-By default, it is deployed to the `modelRegion`, but you can override this by specifying `agentCoreRegion`.
+By default, it is deployed to `modelRegion`, but you can override it by specifying `agentCoreRegion`.
 
-The default agents available in AgentCore can utilize MCP servers defined in [mcp.json](https://github.com/aws-samples/generative-ai-use-cases/blob/main/packages/cdk/lambda-python/generic-agent-core-runtime/mcp.json).
-This default agent is available in Agent Builder, and users can create any agent from MCPs that administrators have permitted.
+The default agents available in AgentCore can use MCP servers defined in [generic.json](packages/cdk/lambda-python/generic-agent-core-runtime/mcp-configs/generic.json).
 
 The MCP servers defined by default are AWS-related MCP servers and MCP servers related to current time.
-For details, please refer to the documentation [here](https://awslabs.github.io/mcp/).
-When adding MCP servers, please add them to the aforementioned `mcp.json`.
-However, MCP servers that start with methods other than `uvx` require development work such as rewriting the Dockerfile.
+For more details, please refer to [this documentation](https://awslabs.github.io/mcp/).
+To add MCP servers, add them to the aforementioned `generic.json`.
 
-With `agentCoreExternalRuntimes`, you can use externally created AgentCore Runtimes.
+You can use externally created AgentCore Runtimes with `agentCoreExternalRuntimes`.
 
-To enable AgentCore use cases, the `docker` command must be executable.
+When accessing services outside AWS from AgentCore Runtime, use AgentCore Gateway.
+By specifying the Gateway ARN in `agentCoreGatewayArns`, an IAM policy following the principle of least privilege will be configured.
+After configuration, use `mcp-proxy-for-aws` in the MCP settings to specify the endpoint.
+For details, refer to the [mcp-proxy-for-aws documentation](https://github.com/aws-samples/mcp-proxy-for-aws).
+
+To enable the AgentCore use case, the `docker` command must be executable.
 
 > [!WARNING]
-> On Linux machines using x86_64 CPUs (Intel, AMD, etc.), run the following command before cdk deployment:
+> On Linux machines using x86_64 CPUs (Intel, AMD, etc.), execute the following command before deploying:
 >
 > ```
 > docker run --privileged --rm tonistiigi/binfmt --install arm64
 > ```
 >
-> If you do not run the above command, the following error will occur:  
-> During the deployment process, ARM-based container images used by AgentCore Runtime are built. When building ARM container images on x86_64 CPUs, errors occur due to CPU architecture differences.
+> If you do not execute the above command, the following error will occur.
+> During the deployment process, ARM-based container images used by AgentCore Runtime are built. When building ARM container images on x86_64 CPUs, errors occur due to differences in CPU architecture.
 >
 > ```
 > ERROR: failed to solve: process "/bin/sh -c apt-get update -y && apt-get install curl nodejs npm graphviz -y" did not complete successfully: exit code: 255
 > AgentCoreStack: fail: docker build --tag cdkasset-64ba68f71e3d29f5b84d8e8d062e841cb600c436bb68a540d6fce32fded36c08 --platform linux/arm64 . exited with error code 1: #0 building with "default" instance using docker driver
 > ```
 >
-> Running this command makes temporary configuration changes to the host Linux Kernel. It registers QEMU emulator custom handlers in Binary Format Miscellaneous (binfmt_misc), enabling ARM container image builds. The configuration returns to its original state after reboot, so the command must be re-executed before re-deployments.
+> Executing this command makes temporary configuration changes to the host's Linux Kernel. By registering QEMU custom handlers in Binary Format Miscellaneous (binfmt_misc), ARM container images can be built. The configuration reverts after a reboot, so re-execution is required when deploying again.
 
 **Edit [parameter.ts](/packages/cdk/parameter.ts)**
 
@@ -725,6 +728,9 @@ const envs: Record<string, Partial<StackInput>> = {
   dev: {
     createGenericAgentCoreRuntime: true,
     agentCoreRegion: 'us-west-2',
+    agentCoreGatewayArns: [
+      'arn:aws:bedrock-agentcore:us-west-2:<account>:gateway/<gateway-id>',
+    ],
     agentCoreExternalRuntimes: [
       {
         name: 'AgentCore1',
@@ -744,6 +750,9 @@ const envs: Record<string, Partial<StackInput>> = {
   "context": {
     "createGenericAgentCoreRuntime": true,
     "agentCoreRegion": "us-west-2",
+    "agentCoreGatewayArns": [
+      "arn:aws:bedrock-agentcore:us-west-2:<account>:gateway/<gateway-id>"
+    ],
     "agentCoreExternalRuntimes": [
       {
         "name": "AgentCore1",
@@ -754,6 +763,51 @@ const envs: Record<string, Partial<StackInput>> = {
 }
 ```
 
+### Enabling AgentBuilder Use Case
+
+This is a use case where users can freely create Agents for each use case by configuring system prompts and arbitrary MCPs. (Experimental: Breaking changes may be made without notice)
+
+Similar to the AgentCore use case, administrators pre-register MCPs in [agent-builder.json](packages/cdk/lambda-python/generic-agent-core-runtime/mcp-configs/agent-builder.json). Users can selectively use their preferred MCPs from those registered by administrators.
+
+Enabling `agentBuilderEnabled` will deploy the AgentCore Runtime for Agent Builder.
+By default, it is deployed to `modelRegion`, but you can override it by specifying `agentCoreRegion`.
+
+When accessing services outside AWS, use AgentCore Gateway.
+By specifying the Gateway ARN in `agentCoreGatewayArns`, an IAM policy following the principle of least privilege will be configured.
+After configuration, use `mcp-proxy-for-aws` in the MCP settings to specify the endpoint.
+For details, refer to the [mcp-proxy-for-aws documentation](https://github.com/aws-samples/mcp-proxy-for-aws).
+
+**Edit [parameter.ts](/packages/cdk/parameter.ts)**
+
+```typescript
+// parameter.ts
+const envs: Record<string, Partial<StackInput>> = {
+  dev: {
+    agentBuilderEnabled: true,
+    agentCoreRegion: 'us-west-2',
+    agentCoreGatewayArns: [
+      'arn:aws:bedrock-agentcore:us-west-2:<account>:gateway/<gateway-id>',
+    ],
+  },
+};
+```
+
+**Edit [packages/cdk/cdk.json](/packages/cdk/cdk.json)**
+
+```json
+// cdk.json
+
+{
+  "context": {
+    "agentBuilderEnabled": true,
+    "agentCoreRegion": "us-west-2",
+    "agentCoreGatewayArns": [
+      "arn:aws:bedrock-agentcore:us-west-2:<account>:gateway/<gateway-id>"
+    ]
+  }
+}
+```
+
 ### Enabling Voice Chat Use Case
 
 > [!NOTE]

docs/ja/DEPLOY_OPTION.md

@@ -703,16 +703,19 @@ AgentCore で作成したエージェントと連携するユースケースで
 `createGenericAgentCoreRuntime` を有効化するとデフォルトの AgentCore Runtime がデプロイされます。
 デフォルトでは `modelRegion` にデプロイされますが、`agentCoreRegion` を指定し上書きすることが可能です。
 
-AgentCore で使用できるデフォルトのエージェントは、[mcp.json](https://github.com/aws-samples/generative-ai-use-cases/blob/main/packages/cdk/lambda-python/generic-agent-core-runtime/mcp.json) で定義する MCP サーバーを利用することができます。
-このデフォルトのエージェントは Agent Builder で利用でき、ユーザーは管理者が許可した MCP から任意のエージェントを作成することができます。
+AgentCore で使用できるデフォルトのエージェントは、[generic.json](packages/cdk/lambda-python/generic-agent-core-runtime/mcp-configs/generic.json) で定義する MCP サーバーを利用することができます。
 
 デフォルトで定義されている MCP サーバーは、AWS に関連する MCP サーバー及び、現在時刻に関連する MCP サーバーです。
 詳細は[こちら](https://awslabs.github.io/mcp/)のドキュメントをご参照ください。
-MCP サーバーを追加する場合は上述の `mcp.json` に追記してください。
-ただし、`uvx` 以外で起動する MCP サーバーは Dockefile の書き換え等開発が必要です。
+MCP サーバーを追加する場合は上述の `generic.json` に追記してください。
 
 `agentCoreExternalRuntimes` で外部で作成した AgentCore Runtime を利用することが可能です。
 
+AgentCore Runtime から AWS 外部のサービスにアクセスする場合、AgentCore Gateway を使用します。
+`agentCoreGatewayArns` に Gateway の ARN を指定することで、最小権限の原則に従った IAM ポリシーが設定されます。
+設定後、MCP 設定で `mcp-proxy-for-aws` を使用してエンドポイントを指定します。
+詳細は [mcp-proxy-for-aws のドキュメント](https://github.com/aws-samples/mcp-proxy-for-aws)を参照してください。
+
 AgentCore ユースケースを有効化するためには、`docker` コマンドが実行可能である必要があります。
 
 > [!WARNING]
@@ -740,6 +743,9 @@ const envs: Record<string, Partial<StackInput>> = {
   dev: {
     createGenericAgentCoreRuntime: true,
     agentCoreRegion: 'us-west-2',
+    agentCoreGatewayArns: [
+      'arn:aws:bedrock-agentcore:us-west-2:<account>:gateway/<gateway-id>',
+    ],
     agentCoreExternalRuntimes: [
       {
         name: 'AgentCore1',
@@ -759,6 +765,9 @@ const envs: Record<string, Partial<StackInput>> = {
   "context": {
     "createGenericAgentCoreRuntime": true,
     "agentCoreRegion": "us-west-2",
+    "agentCoreGatewayArns": [
+      "arn:aws:bedrock-agentcore:us-west-2:<account>:gateway/<gateway-id>"
+    ],
     "agentCoreExternalRuntimes": [
       {
         "name": "AgentCore1",
@@ -769,6 +778,51 @@ const envs: Record<string, Partial<StackInput>> = {
 }
 ```
 
+### AgentBuilder ユースケースの有効化
+
+ユーザーがシステムプロンプトと任意の MCP を設定することでユースケースごとの Agent を自由に作成できるユースケースです。(Experimental: 予告なく破壊的変更を行うことがあります)
+
+AgentCore ユースケースと同様に [agent-builder.json](packages/cdk/lambda-python/generic-agent-core-runtime/mcp-configs/agent-builder.json) にて管理者がわで MCP を事前に登録します。管理者が登録したものからユーザーが好きな MCP を選択式で利用できます。
+
+`agentBuilderEnabled` を有効化すると Agent Builder 向けの AgentCore Runtime がデプロイされます。
+デフォルトでは `modelRegion` にデプロイされますが、`agentCoreRegion` を指定し上書きすることが可能です。
+
+AWS 外部のサービスにアクセスする場合、AgentCore Gateway を使用します。
+`agentCoreGatewayArns` に Gateway の ARN を指定することで、最小権限の原則に従った IAM ポリシーが設定されます。
+設定後、MCP 設定で `mcp-proxy-for-aws` を使用してエンドポイントを指定します。
+詳細は [mcp-proxy-for-aws のドキュメント](https://github.com/aws-samples/mcp-proxy-for-aws)を参照してください。
+
+**[parameter.ts](/packages/cdk/parameter.ts) を編集**
+
+```typescript
+// parameter.ts
+const envs: Record<string, Partial<StackInput>> = {
+  dev: {
+    agentBuilderEnabled: true,
+    agentCoreRegion: 'us-west-2',
+    agentCoreGatewayArns: [
+      'arn:aws:bedrock-agentcore:us-west-2:<account>:gateway/<gateway-id>',
+    ],
+  },
+};
+```
+
+**[packages/cdk/cdk.json](/packages/cdk/cdk.json) を編集**
+
+```json
+// cdk.json
+
+{
+  "context": {
+    "agentBuilderEnabled": true,
+    "agentCoreRegion": "us-west-2",
+    "agentCoreGatewayArns": [
+      "arn:aws:bedrock-agentcore:us-west-2:<account>:gateway/<gateway-id>"
+    ]
+  }
+}
+```
+
 ### 音声チャットユースケースの有効化
 
 > [!NOTE]

docs/overrides/hooks/anchors.py

@@ -1,28 +1,29 @@
 import re
-from mkdocs import utils as mkdocs_utils
+
 
 # Override absolute path to start with edit_uri
 def override_absolute_path(html, page, config, files):
-    absolute_path_replace_uri = config.get('extra', {}).get('absolute_path_replace_uri')
+    absolute_path_replace_uri = config.get("extra", {}).get("absolute_path_replace_uri")
     if not absolute_path_replace_uri:
         return html
 
-    if absolute_path_replace_uri.endswith('/'):
+    if absolute_path_replace_uri.endswith("/"):
         absolute_path_replace_uri = absolute_path_replace_uri[:-1]
 
     link_pattern = r'<a\s+(?:.*?\s+)?href="(.*?)"'
     links = re.findall(link_pattern, html)
     for link in links:
         url = link.strip()
-        if url.startswith('/'):
+        if url.startswith("/"):
             new_url = f"{absolute_path_replace_uri}{url}"
             html = html.replace(f'href="{url}"', f'href="{new_url}"')
 
     return html
 
+
 # Replace link to file included by mkdocs-include-markdown-plugin (README.md and README_ja.md) to parent importing file (ABOUT.md)
 def override_include_markdown_link(html, page, config, files):
-    replace_dict = config.get('extra', {}).get('replace_dict')
+    replace_dict = config.get("extra", {}).get("replace_dict")
     if not replace_dict:
         return html
 
@@ -34,6 +35,7 @@ def override_include_markdown_link(html, page, config, files):
             html = html.replace(link, replace_dict[url])
     return html
 
+
 def on_page_content(html, page, config, files):
     html = override_absolute_path(html, page, config, files)
     html = override_include_markdown_link(html, page, config, files)

packages/cdk/cdk.json

@@ -68,6 +68,7 @@
     "createGenericAgentCoreRuntime": false,
     "agentCoreRegion": null,
     "agentCoreExternalRuntimes": [],
+    "agentCoreGatewayArns": [],
     "allowedIpV4AddressRanges": null,
     "allowedIpV6AddressRanges": null,
     "allowedCountryCodes": null,

packages/cdk/lambda-python/generic-agent-core-runtime/Dockerfile

@@ -14,15 +14,19 @@ ENV UV_PROJECT_ENVIRONMENT=/tmp/.venv
 RUN apt-get update -y && apt-get install curl nodejs npm graphviz -y
 RUN curl -LsSf https://astral.sh/uv/install.sh | sh
 
+# Pre-install mcp-remote for faster startup
+RUN npm install -g mcp-remote
+
 # Copy dependency files
 COPY pyproject.toml .python-version uv.lock ./
-
 # Install Python dependencies
 RUN uv sync
 
 # Copy application files
 COPY app.py ./
 COPY src/ ./src/
+COPY mcp-configs ./mcp-configs
+
 
 # Expose port 8080 as required by AgentCore
 EXPOSE 8080

packages/cdk/assets/mcp-configs/agent-builder.json → packages/cdk/lambda-python/generic-agent-core-runtime/mcp-configs/agent-builder.json

@@ -74,6 +74,14 @@
         "category": "Search",
         "description": "Web search and research capabilities powered by Tavily"
       }
+    },
+    "tavily-gateway": {
+      "command": "uvx",
+      "args": ["mcp-proxy-for-aws", "<AgentCore Gateway Endpoint>"],
+      "metadata": {
+        "category": "Search",
+        "description": "Web search and research capabilities powered by Tavily"
+      }
     }
   }
 }