@aws/agentcore 0.8.2 → 0.10.0

package/dist/assets/__tests__/__snapshots__/dockerfile-render.test.ts.snap

@@ -0,0 +1,77 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Dockerfile enableOtel rendering > renders opentelemetry-instrument CMD when enableOtel is true > Dockerfile-enableOtel-true 1`] = `
+"FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+ARG UV_DEFAULT_INDEX
+ARG UV_INDEX
+
+WORKDIR /app
+
+ENV UV_SYSTEM_PYTHON=1 \\
+    UV_COMPILE_BYTECODE=1 \\
+    UV_NO_PROGRESS=1 \\
+    PYTHONUNBUFFERED=1 \\
+    DOCKER_CONTAINER=1 \\
+    UV_DEFAULT_INDEX=\${UV_DEFAULT_INDEX} \\
+    UV_INDEX=\${UV_INDEX} \\
+    PATH="/app/.venv/bin:$PATH"
+
+RUN useradd -m -u 1000 bedrock_agentcore
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY --chown=bedrock_agentcore:bedrock_agentcore . .
+RUN uv sync --frozen --no-dev
+
+USER bedrock_agentcore
+
+# AgentCore Runtime service contract ports
+# https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html
+# 8080: HTTP Mode
+# 8000: MCP Mode
+# 9000: A2A Mode
+EXPOSE 8080 8000 9000
+
+CMD ["opentelemetry-instrument", "python", "-m", "main"]
+"
+`;
+
+exports[`Dockerfile enableOtel rendering > renders plain python CMD when enableOtel is false > Dockerfile-enableOtel-false 1`] = `
+"FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+ARG UV_DEFAULT_INDEX
+ARG UV_INDEX
+
+WORKDIR /app
+
+ENV UV_SYSTEM_PYTHON=1 \\
+    UV_COMPILE_BYTECODE=1 \\
+    UV_NO_PROGRESS=1 \\
+    PYTHONUNBUFFERED=1 \\
+    DOCKER_CONTAINER=1 \\
+    UV_DEFAULT_INDEX=\${UV_DEFAULT_INDEX} \\
+    UV_INDEX=\${UV_INDEX} \\
+    PATH="/app/.venv/bin:$PATH"
+
+RUN useradd -m -u 1000 bedrock_agentcore
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY --chown=bedrock_agentcore:bedrock_agentcore . .
+RUN uv sync --frozen --no-dev
+
+USER bedrock_agentcore
+
+# AgentCore Runtime service contract ports
+# https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html
+# 8080: HTTP Mode
+# 8000: MCP Mode
+# 9000: A2A Mode
+EXPOSE 8080 8000 9000
+
+CMD ["python", "-m", "main"]
+"
+`;

package/dist/assets/__tests__/dockerfile-render.test.ts

@@ -0,0 +1,24 @@
+import * as fs from 'fs';
+import Handlebars from 'handlebars';
+import * as path from 'path';
+import { describe, expect, it } from 'vitest';
+
+const DOCKERFILE_PATH = path.resolve(__dirname, '..', 'container', 'python', 'Dockerfile');
+
+describe('Dockerfile enableOtel rendering', () => {
+  const template = Handlebars.compile(fs.readFileSync(DOCKERFILE_PATH, 'utf-8'));
+
+  it('renders opentelemetry-instrument CMD when enableOtel is true', () => {
+    const rendered = template({ entrypoint: 'main', enableOtel: true });
+    expect(rendered).toMatchSnapshot('Dockerfile-enableOtel-true');
+    expect(rendered).toContain('opentelemetry-instrument');
+    expect(rendered).not.toContain('CMD ["python", "-m"');
+  });
+
+  it('renders plain python CMD when enableOtel is false', () => {
+    const rendered = template({ entrypoint: 'main', enableOtel: false });
+    expect(rendered).toMatchSnapshot('Dockerfile-enableOtel-false');
+    expect(rendered).toContain('CMD ["python", "-m"');
+    expect(rendered).not.toContain('opentelemetry-instrument');
+  });
+});

package/dist/assets/agents/AGENTS.md

@@ -2,103 +2,114 @@
 
 This project contains configuration and infrastructure for an Amazon Bedrock AgentCore application.
 
-The `agentcore/` directory serves as a declarative model of an AgentCore project along with a concrete implementation
-through the `agentcore/cdk/` project which is modeled to take the configs as input. The project uses a **flat resource
-model** where agents, memories, and credentials are top-level arrays.
+The `agentcore/` directory is a declarative model of the project. The `agentcore/cdk/` subdirectory uses the
+`@aws/agentcore-cdk` L3 constructs to deploy the configuration to AWS.
 
 ## Mental Model
 
-The project uses a **flat resource model**. Agents, memories, and credentials are independent top-level arrays in
-`agentcore.json`. There is no binding or attachment between resources in the schema — each resource is provisioned
-independently. To use a memory or credential from an agent, the application code discovers the resource at runtime
-(e.g., via environment variables or SDK calls). Tags defined in `agentcore.json` flow through to deployed CloudFormation resources.
+The project uses a **flat resource model**. Agents, memories, credentials, gateways, evaluators, and policies are
+independent top-level arrays in `agentcore.json`. There is no binding between resources in the schema — each resource is
+provisioned independently. Agents discover memories and credentials at runtime via environment variables or SDK calls.
+Tags defined in `agentcore.json` flow through to deployed CloudFormation resources.
 
 ## Critical Invariants
 
-1. **Schema-First Authority:** The `.json` files are the absolute source of truth. Do not attempt to modify agent
-   behavior by editing the generated CDK code in `cdk/`.
-2. **Resource Identity:** The `name` field in the schema determines the CloudFormation Logical ID.
-   - **Renaming** an agent or target will **destroy and recreate** that resource.
-   - **Modifying** other fields (descriptions, config) will update the resource **in-place**.
-3. **1:1 Validation:** The schema maps directly to valid CloudFormation. If your JSON conforms to the types in
-   `.llm-context/`, it will deploy successfully.
-4. **Resource Removal:** To remove all resources, use `agentcore remove all`. To tear down deployed infrastructure, run
-   `agentcore deploy` after removal — it will detect the empty state and offer a teardown flow.
+1. **Schema-First Authority:** The `.json` files are the source of truth. Do not modify agent behavior by editing
+   generated CDK code in `cdk/`.
+2. **Resource Identity:** The `name` field determines the CloudFormation Logical ID.
+   - **Renaming** a resource will **destroy and recreate** it.
+   - **Modifying** other fields will update the resource **in-place**.
+3. **Schema Validation:** If your JSON conforms to the types in `.llm-context/`, it will deploy successfully. Run
+   `agentcore validate` to check.
+4. **Resource Removal:** Use `agentcore remove` to remove resources. Run `agentcore deploy` after removal to tear down
+   deployed infrastructure.
 
 ## Directory Structure
 
 ```
-myNewProject/
-├── AGENTS.md               # This file - AI coding assistant context
-├── agentcore/              # AgentCore configuration directory
+myProject/
+├── AGENTS.md               # This file — AI coding assistant context
+├── agentcore/
 │   ├── agentcore.json      # Main project config (AgentCoreProjectSpec)
-│   ├── aws-targets.json    # Deployment targets
-│   ├── .llm-context/       # TypeScript type definitions for AI coding assistants
-│   │   ├── README.md       # Guide to using the schema files
+│   ├── aws-targets.json    # Deployment targets (account + region)
+│   ├── .env.local          # Secrets — API keys (gitignored)
+│   ├── .llm-context/       # TypeScript type definitions for AI assistants
+│   │   ├── README.md       # Guide to using schema files
 │   │   ├── agentcore.ts    # AgentCoreProjectSpec types
-│   │   └── aws-targets.ts  # AWS deployment target types
-│   └── cdk/                # AWS CDK project for deployment
-└── app/                    # Application code (if agents were created)
+│   │   ├── aws-targets.ts  # AWS deployment target types
+│   │   └── mcp.ts          # Gateway and MCP tool types
+│   └── cdk/                # AWS CDK project (@aws/agentcore-cdk L3 constructs)
+├── app/                    # Agent application code
+└── evaluators/             # Custom evaluator code (if any)
 ```
 
 ## Schema Reference
 
 The `agentcore/.llm-context/` directory contains TypeScript type definitions optimized for AI coding assistants. Each
-file maps to a JSON config file and includes validation constraints as comments.
+file maps to a JSON config file and includes validation constraints as comments (`@regex`, `@min`, `@max`).
 
-| JSON Config                  | Schema File                             | Root Type               |
-| ---------------------------- | --------------------------------------- | ----------------------- |
-| `agentcore/agentcore.json`   | `agentcore/.llm-context/agentcore.ts`   | `AgentCoreProjectSpec`  |
-| `agentcore/aws-targets.json` | `agentcore/.llm-context/aws-targets.ts` | `AWSDeploymentTarget[]` |
+| JSON Config | Schema File | Root Type |
+| --- | --- | --- |
+| `agentcore/agentcore.json` | `agentcore/.llm-context/agentcore.ts` | `AgentCoreProjectSpec` |
+| `agentcore/agentcore.json` (gateways) | `agentcore/.llm-context/mcp.ts` | `AgentCoreMcpSpec` |
+| `agentcore/aws-targets.json` | `agentcore/.llm-context/aws-targets.ts` | `AwsDeploymentTarget[]` |
 
 ### Key Types
 
-- **AgentCoreProjectSpec**: Root project configuration with `agents`, `memories`, `credentials` arrays
-- **AgentEnvSpec**: Agent configuration (runtime, entrypoint, code location)
-- **Memory**: Memory resource with strategies and expiry
-- **Credential**: API key credential provider
+- **AgentCoreProjectSpec**: Root config with `runtimes`, `memories`, `credentials`, `agentCoreGateways`, `evaluators`, `onlineEvalConfigs`, `policyEngines` arrays
+- **AgentEnvSpec**: Agent configuration (build type, entrypoint, code location, runtime version, network mode)
+- **Memory**: Memory resource with strategies (SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC) and expiry
+- **Credential**: API key or OAuth credential provider
+- **AgentCoreGateway**: MCP gateway with targets (Lambda, MCP server, OpenAPI, Smithy, API Gateway)
+- **Evaluator**: LLM-as-a-Judge or code-based evaluator
+- **OnlineEvalConfig**: Continuous evaluation pipeline bound to an agent
 
 ### Common Enum Values
 
 - **BuildType**: `'CodeZip'` | `'Container'`
-- **NetworkMode**: `'PUBLIC'`
-- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'`
+- **NetworkMode**: `'PUBLIC'` | `'VPC'`
+- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'` | `'NODE_18'` | `'NODE_20'` | `'NODE_22'`
 - **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` | `'EPISODIC'`
+- **GatewayTargetType**: `'lambda'` | `'mcpServer'` | `'openApiSchema'` | `'smithyModel'` | `'apiGateway'` | `'lambdaFunctionArn'`
+- **ModelProvider**: `'Bedrock'` | `'Gemini'` | `'OpenAI'` | `'Anthropic'`
 
 ### Build Types
 
-- **CodeZip**: Python source is packaged as a zip artifact and deployed directly to AgentCore Runtime.
-- **Container**: Agent code is built as a Docker container image. Requires a `Dockerfile` in the agent's `codeLocation`
-  directory. At deploy time, the source is uploaded to S3, built in CodeBuild (ARM64), pushed to a per-agent ECR
-  repository, and the container URI is provided to the AgentCore Runtime. For local development (`agentcore dev`), the
-  container is built and run locally with volume-mounted hot-reload.
+- **CodeZip**: Python source packaged as a zip and deployed directly to AgentCore Runtime.
+- **Container**: Docker image built in CodeBuild (ARM64), pushed to a per-agent ECR repository. Requires a `Dockerfile`
+  in the agent's `codeLocation` directory. For local development (`agentcore dev`), the container is built and run
+  locally with volume-mounted hot-reload.
 
 ### Supported Frameworks (for template agents)
 
-- **Strands** - Works with Bedrock, Anthropic, OpenAI, Gemini
-- **LangChain_LangGraph** - Works with Bedrock, Anthropic, OpenAI, Gemini
-- **GoogleADK** - Gemini only
-- **OpenAIAgents** - OpenAI only
+- **Strands** — Bedrock, Anthropic, OpenAI, Gemini
+- **LangChain/LangGraph** — Bedrock, Anthropic, OpenAI, Gemini
+- **GoogleADK** — Gemini
+- **OpenAI Agents** — OpenAI
+- **Autogen** — Bedrock, Anthropic, OpenAI, Gemini
 
+### Protocols
 
-### Specific Context
-
-Directory pathing to local projects is required for runtimes. Both CodeZip (Python zip) and Container (Docker image)
-deployment options are available.
+- **HTTP** — Standard HTTP agent endpoint
+- **MCP** — Model Context Protocol server
+- **A2A** — Agent-to-Agent protocol (Google A2A)
 
 ## Deployment
 
-The `agentcore/cdk/` subdirectory contains an AWS CDK node project.
+Deployments are orchestrated through the CLI:
 
-Deployments of this project are primarily intended to be orchestrated through the `agentcore deploy` command in the CLI.
+```bash
+agentcore deploy    # Synthesizes CDK and deploys to AWS
+agentcore status    # Shows deployment status
+```
 
-Alternatively, the project can be deployed directly as a traditional CDK project:
+Alternatively, deploy directly via CDK:
 
 ```bash
 cd agentcore/cdk
 npm install
-npx cdk synth   # Preview CloudFormation template
-npx cdk deploy  # Deploy to AWS
+npx cdk synth
+npx cdk deploy
 ```
 
 ## Editing Schemas
@@ -109,4 +120,22 @@ When modifying JSON config files:
 2. Check validation constraint comments (`@regex`, `@min`, `@max`)
 3. Use exact enum values as string literals
 4. Use CloudFormation-safe names (alphanumeric, start with letter)
-5. Run `agentcore validate` command to verify changes.
+5. Run `agentcore validate` to verify changes
+
+## CLI Commands
+
+| Command | Description |
+| --- | --- |
+| `agentcore create` | Create a new project |
+| `agentcore add <resource>` | Add agent, memory, credential, gateway, evaluator, policy |
+| `agentcore remove <resource>` | Remove a resource |
+| `agentcore dev` | Run agent locally with hot-reload |
+| `agentcore deploy` | Deploy to AWS |
+| `agentcore status` | Show deployment status |
+| `agentcore invoke` | Invoke agent (local or deployed) |
+| `agentcore logs` | View agent logs |
+| `agentcore traces` | View agent traces |
+| `agentcore eval` | Run evaluations against an agent |
+| `agentcore package` | Package agent artifacts |
+| `agentcore validate` | Validate configuration |
+| `agentcore pause` / `resume` | Pause or resume a deployed agent |

package/dist/assets/cdk/cdk.json

@@ -9,7 +9,7 @@
     "@aws-cdk/aws-ecs-patterns:secGroupsDisablesImplicitOpenListener": true,
     "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
     "@aws-cdk/core:checkSecretUsage": true,
-    "@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
+    "@aws-cdk/core:target-partitions": ["aws", "aws-cn", "aws-us-gov"],
     "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
     "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
     "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,

package/dist/assets/cdk/package.json

@@ -23,7 +23,7 @@
     "typescript": "~5.9.3"
   },
   "dependencies": {
-    "@aws/agentcore-cdk": "0.1.0-alpha.19",
+    "@aws/agentcore-cdk": "^0.1.0-alpha.19",
     "aws-cdk-lib": "^2.248.0",
     "constructs": "^10.0.0"
   }

package/dist/assets/container/python/Dockerfile

@@ -31,4 +31,8 @@ USER bedrock_agentcore
 # 9000: A2A Mode
 EXPOSE 8080 8000 9000
 
+{{#if enableOtel}}
 CMD ["opentelemetry-instrument", "python", "-m", "{{entrypoint}}"]
+{{else}}
+CMD ["python", "-m", "{{entrypoint}}"]
+{{/if}}

package/dist/assets/evaluators/python-lambda/execution-role-policy.json

@@ -4,7 +4,7 @@
     {
       "Effect": "Allow",
       "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
-      "Resource": "arn:aws:logs:*:*:log-group:/aws/lambda/*"
+      "Resource": "arn:*:logs:*:*:log-group:/aws/lambda/*"
     }
   ]
 }

package/dist/assets/python/a2a/googleadk/base/main.py

@@ -1,3 +1,4 @@
+import os
 from google.adk.agents import Agent
 from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
 from google.adk.runners import Runner
@@ -6,18 +7,79 @@ from a2a.types import AgentCapabilities, AgentCard, AgentSkill
 from bedrock_agentcore.runtime import serve_a2a
 from model.load import load_model
 
+load_model()  # Sets GOOGLE_API_KEY env var (returns None)
+
 
 def add_numbers(a: int, b: int) -> int:
     """Return the sum of two numbers."""
     return a + b
 
 
+tools = [add_numbers]
+
+{{#if sessionStorageMountPath}}
+SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+
+def _safe_resolve(path: str) -> str:
+    """Resolve path safely within the storage boundary."""
+    resolved = os.path.realpath(os.path.join(SESSION_STORAGE_PATH, path.lstrip("/")))
+    if not resolved.startswith(os.path.realpath(SESSION_STORAGE_PATH)):
+        raise ValueError(f"Path '{path}' is outside the storage boundary")
+    return resolved
+
+def file_read(path: str) -> str:
+    """Read a file from persistent storage. The path is relative to the storage root."""
+    try:
+        full_path = _safe_resolve(path)
+        with open(full_path) as f:
+            return f.read()
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error reading '{path}': {e.strerror}"
+
+def file_write(path: str, content: str) -> str:
+    """Write content to a file in persistent storage. The path is relative to the storage root."""
+    try:
+        full_path = _safe_resolve(path)
+        parent = os.path.dirname(full_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(full_path, "w") as f:
+            f.write(content)
+        return f"Written to {path}"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error writing '{path}': {e.strerror}"
+
+def list_files(directory: str = "") -> str:
+    """List files in persistent storage. The directory is relative to the storage root."""
+    try:
+        target = _safe_resolve(directory)
+        entries = os.listdir(target)
+        return "\n".join(entries) if entries else "(empty directory)"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error listing '{directory}': {e.strerror}"
+
+tools.extend([file_read, file_write, list_files])
+{{/if}}
+
+AGENT_INSTRUCTION = """
+You are a helpful assistant. Use tools when appropriate.
+{{#if sessionStorageMountPath}}
+You have persistent storage at {{sessionStorageMountPath}}. Use file tools to read and write files. Data persists across sessions.
+{{/if}}
+"""
+
 agent = Agent(
-    model=load_model(),
+    model="gemini-2.5-flash",
     name="{{ name }}",
     description="A helpful assistant that can use tools.",
-    instruction="You are a helpful assistant. Use tools when appropriate.",
-    tools=[add_numbers],
+    instruction=AGENT_INSTRUCTION,
+    tools=tools,
 )
 
 runner = Runner(

package/dist/assets/python/a2a/langchain_langgraph/base/main.py

@@ -1,3 +1,4 @@
+import os
 from langchain_core.tools import tool
 from langgraph.prebuilt import create_react_agent
 from opentelemetry.instrumentation.langchain import LangchainInstrumentor
@@ -18,8 +19,70 @@ def add_numbers(a: int, b: int) -> int:
     return a + b
 
 
+tools = [add_numbers]
+
+{{#if sessionStorageMountPath}}
+SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+
+def _safe_resolve(path: str) -> str:
+    """Resolve path safely within the storage boundary."""
+    resolved = os.path.realpath(os.path.join(SESSION_STORAGE_PATH, path.lstrip("/")))
+    if not resolved.startswith(os.path.realpath(SESSION_STORAGE_PATH)):
+        raise ValueError(f"Path '{path}' is outside the storage boundary")
+    return resolved
+
+@tool
+def file_read(path: str) -> str:
+    """Read a file from persistent storage. The path is relative to the storage root."""
+    try:
+        full_path = _safe_resolve(path)
+        with open(full_path) as f:
+            return f.read()
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error reading '{path}': {e.strerror}"
+
+@tool
+def file_write(path: str, content: str) -> str:
+    """Write content to a file in persistent storage. The path is relative to the storage root."""
+    try:
+        full_path = _safe_resolve(path)
+        parent = os.path.dirname(full_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(full_path, "w") as f:
+            f.write(content)
+        return f"Written to {path}"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error writing '{path}': {e.strerror}"
+
+@tool
+def list_files(directory: str = "") -> str:
+    """List files in persistent storage. The directory is relative to the storage root."""
+    try:
+        target = _safe_resolve(directory)
+        entries = os.listdir(target)
+        return "\n".join(entries) if entries else "(empty directory)"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error listing '{directory}': {e.strerror}"
+
+tools.extend([file_read, file_write, list_files])
+{{/if}}
+
+SYSTEM_PROMPT = """
+You are a helpful assistant. Use tools when appropriate.
+{{#if sessionStorageMountPath}}
+You have persistent storage at {{sessionStorageMountPath}}. Use file tools to read and write files. Data persists across sessions.
+{{/if}}
+"""
+
 model = load_model()
-graph = create_react_agent(model, tools=[add_numbers])
+graph = create_react_agent(model, tools=tools, prompt=SYSTEM_PROMPT)
 
 
 class LangGraphA2AExecutor(AgentExecutor):

package/dist/assets/python/a2a/strands/base/main.py

@@ -5,6 +5,9 @@ from model.load import load_model
 {{#if hasMemory}}
 from memory.session import get_memory_session_manager
 {{/if}}
+{{#if sessionStorageMountPath}}
+import os
+{{/if}}
 
 
 @tool
@@ -15,6 +18,66 @@ def add_numbers(a: int, b: int) -> int:
 
 tools = [add_numbers]
 
+{{#if sessionStorageMountPath}}
+SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+
+def _safe_resolve(path: str) -> str:
+    """Resolve path safely within the storage boundary."""
+    resolved = os.path.realpath(os.path.join(SESSION_STORAGE_PATH, path.lstrip("/")))
+    if not resolved.startswith(os.path.realpath(SESSION_STORAGE_PATH)):
+        raise ValueError(f"Path '{path}' is outside the storage boundary")
+    return resolved
+
+@tool
+def file_read(path: str) -> str:
+    """Read a file from persistent storage. The path is relative to the storage root."""
+    try:
+        full_path = _safe_resolve(path)
+        with open(full_path) as f:
+            return f.read()
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error reading '{path}': {e.strerror}"
+
+@tool
+def file_write(path: str, content: str) -> str:
+    """Write content to a file in persistent storage. The path is relative to the storage root."""
+    try:
+        full_path = _safe_resolve(path)
+        parent = os.path.dirname(full_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(full_path, "w") as f:
+            f.write(content)
+        return f"Written to {path}"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error writing '{path}': {e.strerror}"
+
+@tool
+def list_files(directory: str = "") -> str:
+    """List files in persistent storage. The directory is relative to the storage root."""
+    try:
+        target = _safe_resolve(directory)
+        entries = os.listdir(target)
+        return "\n".join(entries) if entries else "(empty directory)"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error listing '{directory}': {e.strerror}"
+
+tools.extend([file_read, file_write, list_files])
+{{/if}}
+
+SYSTEM_PROMPT = """
+You are a helpful assistant. Use tools when appropriate.
+{{#if sessionStorageMountPath}}
+You have persistent storage at {{sessionStorageMountPath}}. Use file tools to read and write files. Data persists across sessions.
+{{/if}}
+"""
+
 {{#if hasMemory}}
 def agent_factory():
     cache = {}
@@ -24,7 +87,7 @@ def agent_factory():
             cache[key] = Agent(
                 model=load_model(),
                 session_manager=get_memory_session_manager(session_id, user_id),
-                system_prompt="You are a helpful assistant. Use tools when appropriate.",
+                system_prompt=SYSTEM_PROMPT,
                 tools=tools,
             )
         return cache[key]
@@ -35,7 +98,7 @@ agent = get_or_create_agent("default-session", "default-user")
 {{else}}
 agent = Agent(
     model=load_model(),
-    system_prompt="You are a helpful assistant. Use tools when appropriate.",
+    system_prompt=SYSTEM_PROMPT,
     tools=tools,
 )
 {{/if}}

package/dist/assets/python/agui/googleadk/base/README.md

@@ -0,0 +1,30 @@
+# {{ name }}
+
+An AG-UI agent deployed on Amazon Bedrock AgentCore using Google ADK.
+
+## Overview
+
+This agent implements the AG-UI protocol using Google's Agent Development Kit, enabling rich agent-user interaction via the AG-UI event stream.
+
+## Local Development
+
+```bash
+uv sync
+uv run python main.py
+```
+
+The agent starts on port 8080 and serves requests at `/invocations`.
+
+## Health Check
+
+```
+GET /ping
+```
+
+Returns `{"status": "healthy"}`.
+
+## Deploy
+
+```bash
+agentcore deploy
+```

package/dist/assets/python/agui/googleadk/base/gitignore.template

@@ -0,0 +1,41 @@
+# Environment variables
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db