@aws/agentcore 0.8.2 → 1.0.0-preview.1

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/bin/cdk.ts

@@ -54,6 +54,40 @@ async function main() {
     throw new Error('No deployment targets configured. Please define targets in agentcore/aws-targets.json');
   }
 
+  // Read harness configs for role creation.
+  // Harness fields may not yet be on the AgentCoreProjectSpec type from @aws/agentcore-cdk,
+  // so we read them dynamically via specAny (same pattern as gateways above).
+  // Harness paths in agentcore.json are relative to the project root (parent of agentcore/).
+  const projectRoot = path.resolve(configRoot, '..');
+  const harnessConfigs: {
+    name: string;
+    executionRoleArn?: string;
+    memoryName?: string;
+    containerUri?: string;
+    hasDockerfile?: boolean;
+    tools?: { type: string; name: string }[];
+    apiKeyArn?: string;
+  }[] = [];
+  for (const entry of specAny.harnesses ?? []) {
+    const harnessPath = path.resolve(projectRoot, entry.path, 'harness.json');
+    try {
+      const harnessSpec = JSON.parse(fs.readFileSync(harnessPath, 'utf-8'));
+      harnessConfigs.push({
+        name: entry.name,
+        executionRoleArn: harnessSpec.executionRoleArn,
+        memoryName: harnessSpec.memory?.name,
+        containerUri: harnessSpec.containerUri,
+        hasDockerfile: !!harnessSpec.dockerfile,
+        tools: harnessSpec.tools,
+        apiKeyArn: harnessSpec.model?.apiKeyArn,
+      });
+    } catch (err) {
+      throw new Error(
+        `Could not read harness.json for "${entry.name}" at ${harnessPath}: ${err instanceof Error ? err.message : err}`
+      );
+    }
+  }
+
   const app = new App();
 
   for (const target of targets) {
@@ -73,6 +107,7 @@ async function main() {
       spec,
       mcpSpec,
       credentials,
+      harnesses: harnessConfigs.length > 0 ? harnessConfigs : undefined,
       env,
       description: `AgentCore stack for ${spec.name} deployed to ${target.name} (${target.region})`,
       tags: {

package/dist/assets/cdk/lib/cdk-stack.ts

@@ -20,6 +20,18 @@ export interface AgentCoreStackProps extends StackProps {
    * Credential provider ARNs from deployed state, keyed by credential name.
    */
   credentials?: Record<string, { credentialProviderArn: string; clientSecretArn?: string }>;
+  /**
+   * Harness role configurations. Each entry creates an IAM execution role for a harness.
+   */
+  harnesses?: {
+    name: string;
+    executionRoleArn?: string;
+    memoryName?: string;
+    containerUri?: string;
+    hasDockerfile?: boolean;
+    tools?: { type: string; name: string }[];
+    apiKeyArn?: string;
+  }[];
 }
 
 /**
@@ -35,11 +47,12 @@ export class AgentCoreStack extends Stack {
   constructor(scope: Construct, id: string, props: AgentCoreStackProps) {
     super(scope, id, props);
 
-    const { spec, mcpSpec, credentials } = props;
+    const { spec, mcpSpec, credentials, harnesses } = props;
 
-    // Create AgentCoreApplication with all agents
+    // Create AgentCoreApplication with all agents and harness roles
     this.application = new AgentCoreApplication(this, 'Application', {
       spec,
+      harnesses,
     });
 
     // Create AgentCoreMcp if there are gateways configured

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/harness/invoke.py.template

@@ -0,0 +1,74 @@
+"""
+Standalone invoke script for AgentCore Harness.
+Generated by: agentcore create --with-invoke-script
+
+Usage:
+  pip install boto3
+  export HARNESS_ARN="arn:aws:bedrock-agentcore:<region>:<account>:harness/<harness-id>"
+  python invoke.py "Hello, what can you do?"
+  python invoke.py --raw-events "Hello"
+"""
+
+import argparse
+import json
+import os
+import sys
+import uuid
+
+import boto3
+
+# --- Configuration ---
+HARNESS_ARN = os.environ.get("HARNESS_ARN", "{{HARNESS_ARN}}")
+REGION = os.environ.get("AWS_REGION", "{{REGION}}")
+SESSION_ID = os.environ.get("SESSION_ID", str(uuid.uuid4()))
+
+parser = argparse.ArgumentParser(description="Invoke an AgentCore Harness")
+parser.add_argument("prompt", nargs="?", default="Hello!", help="Prompt to send to the agent")
+parser.add_argument("--raw-events", action="store_true", help="Print raw streaming events as JSON")
+parser.add_argument("--session-id", default=SESSION_ID, help="Session ID for conversation continuity")
+args = parser.parse_args()
+
+client = boto3.client("bedrock-agentcore", region_name=REGION)
+
+response = client.invoke_harness(
+    harnessArn=HARNESS_ARN,
+    runtimeSessionId=args.session_id,
+    messages=[
+        {
+            "role": "user",
+            "content": [{"text": args.prompt}],
+        }
+    ],
+)
+
+for event in response["stream"]:
+    if args.raw_events:
+        print(json.dumps(event, default=str))
+    else:
+        if "contentBlockStart" in event:
+            start = event["contentBlockStart"].get("start", {})
+            if "toolUse" in start:
+                tool = start["toolUse"]
+                print(f"\n🔧 Tool: {tool.get('name', 'unknown')}", flush=True)
+        elif "contentBlockDelta" in event:
+            delta = event["contentBlockDelta"].get("delta", {})
+            if "text" in delta:
+                print(delta["text"], end="", flush=True)
+        elif "messageStop" in event:
+            stop_reason = event["messageStop"].get("stopReason", "")
+            if stop_reason == "end_turn":
+                print()
+        elif "metadata" in event:
+            usage = event["metadata"].get("usage", {})
+            metrics = event["metadata"].get("metrics", {})
+            latency = metrics.get("latencyMs", 0) / 1000
+            print(
+                f"\n⚡ {usage.get('inputTokens', 0)} in · "
+                f"{usage.get('outputTokens', 0)} out · "
+                f"{latency:.1f}s",
+                file=sys.stderr,
+            )
+        elif "internalServerException" in event:
+            print(f"\nError: {event['internalServerException']}", file=sys.stderr)
+
+print(f"\n🔗 Session: {args.session_id}", file=sys.stderr)

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):