@aws/agentcore 1.0.0-preview.11 → 1.0.0-preview.13

package/dist/assets/cdk/bin/cdk.ts

@@ -28,12 +28,14 @@ async function main() {
   const spec = await configIO.readProjectSpec();
   const targets = await configIO.readAWSDeploymentTargets();
 
-  // Extract MCP configuration from project spec.
-  // Gateway fields are stored in agentcore.json but may not yet be on the
-  // AgentCoreProjectSpec type from @aws/agentcore-cdk, so we read them
-  // dynamically and cast the resulting object.
+  // The vended CDK project compiles against the published @aws/agentcore-cdk
+  // schema type, which may lag the CLI's own AgentCoreProjectSpec (e.g. payments,
+  // harnesses, gateway fields). Cast once so those fields are reachable.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const specAny = spec as any;
+
+  // Extract MCP configuration from project spec.
+  // Gateway fields are stored in agentcore.json but may not yet be on the
   const mcpSpec = specAny.agentCoreGateways?.length
     ? {
         agentCoreGateways: specAny.agentCoreGateways,
@@ -66,6 +68,9 @@ async function main() {
     codeLocation?: string;
     tools?: { type: string; name: string }[];
     apiKeyArn?: string;
+    efsAccessPoints?: { accessPointArn: string; mountPath: string }[];
+    s3AccessPoints?: { accessPointArn: string; mountPath: string }[];
+    apiFormat?: 'converse_stream' | 'responses' | 'chat_completions';
   }[] = [];
   for (const entry of specAny.harnesses ?? []) {
     const harnessDir = path.resolve(projectRoot, entry.path);
@@ -82,6 +87,9 @@ async function main() {
         codeLocation: harnessSpec.dockerfile ? harnessDir : undefined,
         tools: harnessSpec.tools,
         apiKeyArn: harnessSpec.model?.apiKeyArn,
+        efsAccessPoints: harnessSpec.efsAccessPoints,
+        s3AccessPoints: harnessSpec.s3AccessPoints,
+        apiFormat: harnessSpec.model?.apiFormat,
       });
     } catch (err) {
       throw new Error(
@@ -105,11 +113,51 @@ async function main() {
       | Record<string, { credentialProviderArn: string; clientSecretArn?: string }>
       | undefined;
 
+    // Payment credential provider ARNs live in the same credentials map as identity credentials
+    const paymentCredentials = credentials;
+
+    const paymentSpec = specAny.payments?.length
+      ? specAny.payments.map(
+          (p: {
+            name: string;
+            description?: string;
+            authorizerType: 'AWS_IAM' | 'CUSTOM_JWT';
+            authorizerConfiguration?: unknown;
+            autoPayment?: boolean;
+            paymentToolAllowlist?: string[];
+            networkPreferences?: string[];
+            connectors: { name: string; provider?: string; credentialName: string }[];
+          }) => ({
+            name: p.name,
+            description: p.description,
+            authorizerType: p.authorizerType,
+            authorizerConfiguration: p.authorizerConfiguration,
+            autoPayment: p.autoPayment,
+            paymentToolAllowlist: p.paymentToolAllowlist,
+            networkPreferences: p.networkPreferences,
+            connectors: p.connectors.map(c => {
+              const credentialProviderArn = paymentCredentials?.[c.credentialName]?.credentialProviderArn;
+              if (!credentialProviderArn) {
+                // Fail fast with an actionable message rather than passing an empty
+                // ARN that fails opaquely server-side at CreatePaymentConnector.
+                throw new Error(
+                  `Payment connector "${c.name}" on manager "${p.name}" references credential ` +
+                    `"${c.credentialName}", but no deployed credential provider was found for it. ` +
+                    `Run \`agentcore deploy\` so the credential provider is created first.`
+                );
+              }
+              return { name: c.name, provider: c.provider, credentialProviderArn };
+            }),
+          })
+        )
+      : undefined;
+
     new AgentCoreStack(app, stackName, {
       spec,
       mcpSpec,
       credentials,
       harnesses: harnessConfigs.length > 0 ? harnessConfigs : undefined,
+      paymentSpec,
       env,
       description: `AgentCore stack for ${spec.name} deployed to ${target.name} (${target.region})`,
       tags: {
@@ -124,5 +172,5 @@ async function main() {
 
 main().catch((error: unknown) => {
   console.error('AgentCore CDK synthesis failed:', error instanceof Error ? error.message : error);
-  process.exitCode = 1;
+  process.exit(1);
 });

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

@@ -1,10 +1,14 @@
 import {
   AgentCoreApplication,
   AgentCoreMcp,
+  AgentCorePaymentManager,
+  AgentCorePaymentConnector,
   type AgentCoreProjectSpec,
   type AgentCoreMcpSpec,
+  type CustomJWTAuthorizerConfig,
 } from '@aws/agentcore-cdk';
 import { CfnOutput, Stack, type StackProps } from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
 import { Construct } from 'constructs';
 
 export interface HarnessConfig {
@@ -17,6 +21,25 @@ export interface HarnessConfig {
   codeLocation?: string;
   tools?: { type: string; name: string }[];
   apiKeyArn?: string;
+  efsAccessPoints?: { accessPointArn: string; mountPath: string }[];
+  s3AccessPoints?: { accessPointArn: string; mountPath: string }[];
+}
+
+export interface PaymentConnectorSpec {
+  name: string;
+  provider: 'CoinbaseCDP' | 'StripePrivy';
+  credentialProviderArn: string;
+}
+
+export interface PaymentSpec {
+  name: string;
+  description?: string;
+  authorizerType: 'AWS_IAM' | 'CUSTOM_JWT';
+  authorizerConfiguration?: { customJWTAuthorizer: CustomJWTAuthorizerConfig };
+  autoPayment?: boolean;
+  paymentToolAllowlist?: string[];
+  networkPreferences?: string[];
+  connectors: PaymentConnectorSpec[];
 }
 
 export interface AgentCoreStackProps extends StackProps {
@@ -36,6 +59,30 @@ export interface AgentCoreStackProps extends StackProps {
    * Harness role configurations.
    */
   harnesses?: HarnessConfig[];
+  /**
+   * Payment specifications with resolved credential provider ARNs.
+   */
+  paymentSpec?: PaymentSpec[];
+}
+
+function toCdkId(name: string): string {
+  return name.replace(/_/g, '');
+}
+
+/**
+ * Decide whether a deployed runtime should receive payment env vars + IAM grants.
+ * Payments today only ships a runtime shim for Python HTTP runtimes; injecting
+ * AGENTCORE_PAYMENT_* env vars into TypeScript / MCP / A2A / AGUI runtimes
+ * would surface env vars they cannot consume and would dilute least-privilege
+ * IAM grants for runtimes that never call ProcessPayment.
+ */
+function isPaymentEligibleAgent(agent: { entrypoint?: string; protocol?: string }): boolean {
+  if (agent.protocol && agent.protocol !== 'HTTP') {
+    return false;
+  }
+  const entrypoint = typeof agent.entrypoint === 'string' ? agent.entrypoint : '';
+  const entrypointFile = entrypoint.split(':')[0] ?? '';
+  return entrypointFile.endsWith('.py');
 }
 
 /**
@@ -51,7 +98,7 @@ export class AgentCoreStack extends Stack {
   constructor(scope: Construct, id: string, props: AgentCoreStackProps) {
     super(scope, id, props);
 
-    const { spec, mcpSpec, credentials, harnesses } = props;
+    const { spec, mcpSpec, credentials, harnesses, paymentSpec } = props;
 
     // Create AgentCoreApplication with all agents and harness roles
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -72,6 +119,122 @@ export class AgentCoreStack extends Stack {
       });
     }
 
+    // Create payment infrastructure via CFN constructs
+    if (paymentSpec && paymentSpec.length > 0) {
+      for (const payment of paymentSpec) {
+        const mgrId = toCdkId(payment.name);
+        const manager = new AgentCorePaymentManager(this, `Payment${mgrId}`, {
+          projectName: spec.name,
+          name: payment.name,
+          authorizerType: payment.authorizerType,
+          description: payment.description,
+          authorizerConfiguration: payment.authorizerConfiguration,
+          tags: spec.tags,
+        });
+
+        const prefix = `AGENTCORE_PAYMENT_${payment.name.toUpperCase().replace(/-/g, '_')}`;
+
+        // Wire env vars from construct output tokens into eligible agent environments only.
+        // See isPaymentEligibleAgent — non-Python or non-HTTP runtimes have no shim that
+        // can consume these env vars, and giving them sts:AssumeRole on the
+        // ProcessPaymentRole would broaden the privilege surface unnecessarily.
+        for (const env of this.application.environments.values()) {
+          if (!isPaymentEligibleAgent(env.agent)) {
+            continue;
+          }
+          env.runtime.addEnvironmentVariable(`${prefix}_MANAGER_ARN`, manager.paymentManagerArn);
+          env.runtime.addEnvironmentVariable(`${prefix}_PROCESS_PAYMENT_ROLE_ARN`, manager.processPaymentRoleArn);
+
+          // Grant runtime execution role permission to assume the ProcessPaymentRole.
+          // The ProcessPaymentRole's trust policy allows AccountRootPrincipal, but the
+          // caller still needs sts:AssumeRole on its own role to perform the assumption.
+          env.runtime.role.addToPrincipalPolicy(
+            new iam.PolicyStatement({
+              actions: ['sts:AssumeRole'],
+              resources: [manager.processPaymentRoleArn],
+            })
+          );
+
+          // Grant payment data-plane actions directly to the runtime role.
+          //
+          // NOTE: This deviates from the canonical role model in the AgentCore Payments
+          // beta guide, which assigns Get/List/Create instrument+session actions to a
+          // separate ManagementRole and limits the agent's role to ProcessPayment only.
+          // The current SDK plugin (AgentCorePaymentsPlugin.generate_payment_header)
+          // calls GetPaymentInstrument internally during the 402 auto-pay path, so the
+          // runtime role needs read access. CreatePaymentSession is included so
+          // `agentcore invoke --auto-session` works without a separate ManagementRole
+          // call. Tighten this if the SDK is updated to accept pre-fetched instrument
+          // details and split create-session into a backend-only flow.
+          env.runtime.role.addToPrincipalPolicy(
+            new iam.PolicyStatement({
+              actions: [
+                'bedrock-agentcore:GetPaymentInstrument',
+                'bedrock-agentcore:ListPaymentInstruments',
+                'bedrock-agentcore:GetPaymentInstrumentBalance',
+                'bedrock-agentcore:GetPaymentSession',
+                'bedrock-agentcore:ListPaymentSessions',
+                'bedrock-agentcore:CreatePaymentSession',
+                'bedrock-agentcore:ProcessPayment',
+              ],
+              resources: [manager.paymentManagerArn, `${manager.paymentManagerArn}/*`],
+            })
+          );
+
+          if (payment.autoPayment !== undefined) {
+            env.runtime.addEnvironmentVariable(`${prefix}_AUTO_PAYMENT`, String(payment.autoPayment));
+          }
+          if (payment.paymentToolAllowlist) {
+            env.runtime.addEnvironmentVariable(`${prefix}_TOOL_ALLOWLIST`, payment.paymentToolAllowlist.join(','));
+          }
+          if (payment.networkPreferences) {
+            env.runtime.addEnvironmentVariable(`${prefix}_NETWORK_PREFERENCES`, payment.networkPreferences.join(','));
+          }
+          if (payment.authorizerType === 'CUSTOM_JWT') {
+            env.runtime.addEnvironmentVariable(`${prefix}_AUTH_MODE`, 'bearer');
+          }
+        }
+
+        // Create connectors for this manager
+        for (const connector of payment.connectors) {
+          const connId = toCdkId(connector.name);
+          const conn = new AgentCorePaymentConnector(this, `Payment${mgrId}${connId}`, {
+            projectName: spec.name,
+            paymentManager: manager,
+            connectorName: connector.name,
+            connectorType: connector.provider,
+            credentialProviderArn: connector.credentialProviderArn,
+          });
+
+          // Wire first connector's ID as env var (eligible agents only)
+          if (connector === payment.connectors[0]) {
+            for (const env of this.application.environments.values()) {
+              if (!isPaymentEligibleAgent(env.agent)) continue;
+              env.runtime.addEnvironmentVariable(`${prefix}_CONNECTOR_ID`, conn.paymentConnectorId);
+            }
+          }
+
+          new CfnOutput(this, `Payment${mgrId}${connId}ConnectorId`, {
+            value: conn.paymentConnectorId,
+          });
+        }
+
+        // CFN Outputs for post-deploy state parsing
+        new CfnOutput(this, `Payment${mgrId}ManagerArn`, {
+          value: manager.paymentManagerArn,
+        });
+        new CfnOutput(this, `Payment${mgrId}ManagerId`, {
+          value: manager.paymentManagerId,
+        });
+        new CfnOutput(this, `Payment${mgrId}ProcessPaymentRoleArn`, {
+          value: manager.processPaymentRoleArn,
+        });
+        new CfnOutput(this, `Payment${mgrId}ResourceRetrievalRoleArn`, {
+          value: manager.resourceRetrievalRoleArn,
+        });
+      }
+    }
+
     // Stack-level output
     new CfnOutput(this, 'StackNameOutput', {
       description: 'Name of the CloudFormation Stack',

package/dist/assets/cdk/package.json

@@ -18,7 +18,7 @@
     "@types/node": "^24.10.1",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",
-    "aws-cdk": "2.1100.1",
+    "aws-cdk": "2.1126.0",
     "prettier": "^3.4.2",
     "typescript": "~5.9.3"
   },

package/dist/assets/cdk/test/cdk.test.ts

@@ -15,6 +15,8 @@ test('AgentCoreStack synthesizes with empty spec', () => {
       evaluators: [],
       onlineEvalConfigs: [],
       policyEngines: [],
+      payments: [],
+      configBundles: [],
       agentCoreGateways: [],
       mcpRuntimeTools: [],
       unassignedTargets: [],

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

@@ -1,4 +1,6 @@
+{{#if needsOs}}
 import os
+{{/if}}
 from google.adk.agents import Agent
 from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
 from google.adk.runners import Runner
@@ -17,18 +19,21 @@ def add_numbers(a: int, b: int) -> int:
 
 tools = [add_numbers]
 
-{{#if sessionStorageMountPath}}
-SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
 
 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")
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
     return resolved
 
 def file_read(path: str) -> str:
-    """Read a file from persistent storage. The path is relative to the storage root."""
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         with open(full_path) as f:
@@ -39,7 +44,7 @@ def file_read(path: str) -> str:
         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."""
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         parent = os.path.dirname(full_path)
@@ -53,25 +58,28 @@ def file_write(path: str, content: str) -> str:
     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."""
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
     try:
-        target = _safe_resolve(directory)
-        entries = os.listdir(target)
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
         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}"
+        return f"Error listing '{path}': {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}}
+{{#if needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}
 """
 
 agent = Agent(

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

@@ -1,4 +1,6 @@
+{{#if needsOs}}
 import os
+{{/if}}
 from langchain_core.tools import tool
 from langgraph.prebuilt import create_react_agent
 from opentelemetry.instrumentation.langchain import LangchainInstrumentor
@@ -21,19 +23,22 @@ def add_numbers(a: int, b: int) -> int:
 
 tools = [add_numbers]
 
-{{#if sessionStorageMountPath}}
-SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
 
 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")
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
     return resolved
 
 @tool
 def file_read(path: str) -> str:
-    """Read a file from persistent storage. The path is relative to the storage root."""
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         with open(full_path) as f:
@@ -45,7 +50,7 @@ def file_read(path: str) -> str:
 
 @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."""
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         parent = os.path.dirname(full_path)
@@ -60,25 +65,28 @@ def file_write(path: str, content: str) -> str:
         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."""
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
     try:
-        target = _safe_resolve(directory)
-        entries = os.listdir(target)
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
         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}"
+        return f"Error listing '{path}': {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 needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}
 """
 
 model = load_model()

package/dist/assets/python/a2a/langchain_langgraph/base/pyproject.toml

@@ -17,7 +17,7 @@ dependencies = [
     {{/if}}{{#if (eq modelProvider "OpenAI")}}"langchain-openai >= 0.2.0",
     {{/if}}"aws-opentelemetry-distro",
     "opentelemetry-instrumentation-langchain >= 0.59.0",
-    "bedrock-agentcore[a2a] >= 1.0.3",
+    "bedrock-agentcore[a2a] >= 1.8.0",
     "botocore[crt] >= 1.35.0",
     "langgraph >= 0.2.0",
 ]

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

@@ -5,7 +5,7 @@ from model.load import load_model
 {{#if hasMemory}}
 from memory.session import get_memory_session_manager
 {{/if}}
-{{#if sessionStorageMountPath}}
+{{#if needsOs}}
 import os
 {{/if}}
 
@@ -18,19 +18,22 @@ def add_numbers(a: int, b: int) -> int:
 
 tools = [add_numbers]
 
-{{#if sessionStorageMountPath}}
-SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
 
 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")
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
     return resolved
 
 @tool
 def file_read(path: str) -> str:
-    """Read a file from persistent storage. The path is relative to the storage root."""
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         with open(full_path) as f:
@@ -42,7 +45,7 @@ def file_read(path: str) -> str:
 
 @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."""
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         parent = os.path.dirname(full_path)
@@ -57,25 +60,28 @@ def file_write(path: str, content: str) -> str:
         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."""
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
     try:
-        target = _safe_resolve(directory)
-        entries = os.listdir(target)
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
         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}"
+        return f"Error listing '{path}': {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 needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}
 """
 
 {{#if hasMemory}}

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

@@ -1,16 +1,76 @@
 import os
 import uvicorn
 from google.adk.agents import LlmAgent
+from google.adk.tools import FunctionTool
 from ag_ui_adk import ADKAgent, AGUIToolset, create_adk_app
 from model.load import load_model
 
 load_model()
 
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
+
+def _safe_resolve(path: str) -> str:
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
+    return resolved
+
+def file_read(path: str) -> str:
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    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 a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    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(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
+    try:
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
+        return "\n".join(entries) if entries else "(empty directory)"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error listing '{path}': {e.strerror}"
+
+_fs_tools = [FunctionTool(file_read), FunctionTool(file_write), FunctionTool(list_files)]
+{{/if}}
+
 agent = LlmAgent(
     name="{{ name }}",
     model="gemini-2.5-flash",
-    instruction="You are a helpful assistant.",
-    tools=[AGUIToolset()],
+    instruction="""You are a helpful assistant.
+{{#if needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}""",
+    tools=[AGUIToolset(), {{#if needsOs}}*_fs_tools{{/if}}],
 )
 
 adk_agent = ADKAgent(