@aws/nx-plugin 1.0.0-rc.71 → 1.0.0-rc.73

package/src/py/agent/a2a-connection/generator.js

@@ -4,7 +4,7 @@
  */ import { generateFiles, joinPathFragments, OverwriteStrategy, updateProjectConfiguration } from "@nx/devkit";
 import { addPyDependencies } from "../../../utils/add-dependencies.js";
 import { AGENT_CONNECTION_PY_DEPENDENCIES, addPythonCoreClient, addPythonReExport, ensurePythonAgentConnectionProject, getPythonAgentConnectionModuleName, getPythonAgentConnectionProject, getPythonAgentConnectionProjectDir, PY_CLIENT_NAMING, resolveAgentFramework } from "../../../utils/agent-connection/agent-connection.js";
-import { addPythonDestructuredImport, applyGritQL, matchGritQL } from "../../../utils/ast.js";
+import { addPythonDestructuredImport, appendToArrayViaGritQL, applyGritQL, matchGritQL } from "../../../utils/ast.js";
 import { declareDependencies, ownedElsewhere } from "../../../utils/declared-dependencies.js";
 import { formatFilesInSubtree } from "../../../utils/format.js";
 import { installDependencies } from "../../../utils/install.js";
@@ -169,16 +169,10 @@ export const pyAgentA2aConnectionGenerator = async (tree, options)=>{
  * Scoped to the framework's agent constructor so unrelated `tools=` keyword
  * arguments elsewhere in the file are not touched.
  */ const addToolToAgent = async (tree, filePath, toolName, framework)=>{
-    const scope = AGENT_CONSTRUCTOR[framework];
-    await applyGritQL(tree, filePath, py(`\`tools=$old\` where {
-  $old <: within \`${scope}\`,
-  $old <: not contains \`${toolName}\`,
-  if ($old <: \`[]\`) {
-    $old => \`[${toolName}]\`
-  } else {
-    $old <: \`[$items]\` where { $items += \`, ${toolName}\` }
-  }
-}`));
+    await appendToArrayViaGritQL(tree, filePath, 'tools=', toolName, {
+        scope: AGENT_CONSTRUCTOR[framework],
+        language: 'py'
+    });
 };
 /**
  * Wrap the get_agent body so the remote A2A client is created and exposed

package/src/py/agent/a2a-connection/generator.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/py/agent/a2a-connection/generator.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  type GeneratorCallback,\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { addPyDependencies } from '../../../utils/add-dependencies';\nimport {\n  AGENT_CONNECTION_PY_DEPENDENCIES,\n  type AgentFramework,\n  addPythonCoreClient,\n  addPythonReExport,\n  ensurePythonAgentConnectionProject,\n  getPythonAgentConnectionModuleName,\n  getPythonAgentConnectionProject,\n  getPythonAgentConnectionProjectDir,\n  PY_CLIENT_NAMING,\n  resolveAgentFramework,\n} from '../../../utils/agent-connection/agent-connection';\nimport {\n  addPythonDestructuredImport,\n  applyGritQL,\n  matchGritQL,\n} from '../../../utils/ast';\nimport {\n  declareDependencies,\n  ownedElsewhere,\n} from '../../../utils/declared-dependencies';\nimport { formatFilesInSubtree } from '../../../utils/format';\nimport { installDependencies } from '../../../utils/install';\nimport { addGeneratorMetricsIfApplicable } from '../../../utils/metrics';\nimport { snakeCase } from '../../../utils/names';\nimport {\n  addComponentGeneratorMetadata,\n  addDependencyToTargetIfNotPresent,\n  getGeneratorInfo,\n  type NxGeneratorInfo,\n  readProjectConfigurationUnqualified,\n} from '../../../utils/nx';\nimport { toProjectRelativePath } from '../../../utils/paths';\nimport { addWorkspaceDependencyToPyProject } from '../../../utils/py';\nimport type { PyAgentA2aConnectionGeneratorSchema } from './schema';\n\n/** Prefix a GritQL pattern with `language python` */\nconst py = (pattern: string) => `language python\\n${pattern}`;\n\n/** The module each framework imports the `tool` decorator from. */\nconst TOOL_IMPORT_MODULE: Record<AgentFramework, string> = {\n  strands: 'strands',\n  langchain: 'langchain_core.tools',\n};\n\n/** The GritQL pattern matching each framework's agent constructor. */\nconst AGENT_CONSTRUCTOR: Record<AgentFramework, string> = {\n  strands: 'yield Agent($_)',\n  langchain: 'create_agent($_)',\n};\n\n/** The metadata this generator records, which its predicates read. */\nexport interface PyAgentA2aConnectionMetadata {\n  readonly framework: AgentFramework;\n}\n\n// Each framework's Layer-2 client needs its own A2A transport: Strands wraps\n// strands' `A2AAgent` (strands-agents[a2a]); LangChain drives the a2a SDK\n// directly (a2a-sdk) and must not pull Strands in.\nexport const DEPENDENCIES = declareDependencies<PyAgentA2aConnectionMetadata>()(\n  {\n    py: [\n      { name: 'boto3' },\n      { name: 'httpx' },\n      { name: 'strands-agents[a2a]', when: (m) => m.framework === 'strands' },\n      { name: 'a2a-sdk', when: (m) => m.framework === 'langchain' },\n      ...ownedElsewhere(AGENT_CONNECTION_PY_DEPENDENCIES),\n    ],\n  },\n);\n\nexport const PY_AGENT_A2A_CONNECTION_GENERATOR_INFO: NxGeneratorInfo =\n  getGeneratorInfo(import.meta.filename);\n\nexport const pyAgentA2aConnectionGenerator = async (\n  tree: Tree,\n  options: PyAgentA2aConnectionGeneratorSchema,\n): Promise<GeneratorCallback> => {\n  const sourceProject = readProjectConfigurationUnqualified(\n    tree,\n    options.sourceProject,\n  );\n  const targetProject = readProjectConfigurationUnqualified(\n    tree,\n    options.targetProject,\n  );\n\n  const agentComponent = options.sourceComponent;\n  const targetAgentComponent = options.targetComponent;\n\n  if (!agentComponent || !targetAgentComponent) {\n    throw new Error(\n      'Both sourceComponent and targetComponent must be provided for py#agent -> a2a connections',\n    );\n  }\n\n  if ((targetAgentComponent.protocol ?? '').toLowerCase() !== 'a2a') {\n    throw new Error(\n      `Target agent '${targetAgentComponent.name}' uses the ${targetAgentComponent.protocol ?? 'http'} protocol — only A2A agents can be connected as tools.`,\n    );\n  }\n\n  if (\n    targetAgentComponent.auth &&\n    targetAgentComponent.auth.toLowerCase() !== 'iam'\n  ) {\n    throw new Error(\n      `A2A agent connection currently only supports IAM authentication, but '${targetAgentComponent.name}' uses '${targetAgentComponent.auth}' authentication.`,\n    );\n  }\n\n  const targetAgentComponentName = targetAgentComponent.name ?? 'agent';\n  const targetAgentClassName = targetAgentComponent.rc as string;\n  const targetAgentSnakeCase = snakeCase(targetAgentClassName);\n  const targetAgentPort = targetAgentComponent.port ?? 9000;\n\n  // The source agent's framework drives everything that varies: the client\n  // naming + app template (shared with the mcp/gateway generators via\n  // PY_CLIENT_NAMING), the A2A transport dep (see DEPENDENCIES), and the\n  // agent.py transform below. Each framework wraps its own A2A Layer-2 client\n  // (Strands' A2AAgent vs an a2a-sdk-only client) over the shared,\n  // framework-agnostic A2A client config. Keyed on the framework, not a\n  // boolean, so a third framework stays additive.\n  const framework = resolveAgentFramework(agentComponent.framework);\n  const naming = PY_CLIENT_NAMING[framework];\n\n  // Recorded below and read by the declaration's predicates, so the packages\n  // added here are exactly the ones the version sync will own.\n  const metadata: PyAgentA2aConnectionMetadata = { framework };\n\n  // 1. Ensure the shared Python agent-connection project exists + has the\n  //    A2A core client (framework Layer-2) and its shared SigV4 auth helper.\n  await ensurePythonAgentConnectionProject(tree, DEPENDENCIES);\n  await addPythonCoreClient(tree, 'a2a', DEPENDENCIES, framework);\n\n  const agentConnectionProjectDir = getPythonAgentConnectionProjectDir(tree);\n  const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);\n\n  // A2A client config + shared auth helper deps, plus the framework's A2A\n  // transport dep. These belong to the shared agent-connection project, which\n  // holds the client.\n  addPyDependencies(tree, DEPENDENCIES, {\n    metadata,\n    projectRoot: agentConnectionProjectDir,\n  });\n\n  // 2. Generate the per-connection client into the shared agent-connection project\n  const appDir = joinPathFragments(\n    agentConnectionProjectDir,\n    agentConnectionModuleName,\n    'app',\n  );\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', naming.appTemplateSubdir),\n    appDir,\n    {\n      targetAgentSnakeCase,\n      targetAgentClassName,\n      targetAgentPort,\n      agentConnectionModuleName,\n    },\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n\n  // Ensure app/__init__.py exists\n  const appInitPath = joinPathFragments(appDir, '__init__.py');\n  if (!tree.exists(appInitPath)) {\n    tree.write(appInitPath, '');\n  }\n\n  // Add re-export to module __init__.py\n  const moduleInitPath = joinPathFragments(\n    agentConnectionProjectDir,\n    agentConnectionModuleName,\n    '__init__.py',\n  );\n  await addPythonReExport(\n    tree,\n    moduleInitPath,\n    `.app.${targetAgentSnakeCase}_client_${naming.clientModuleSuffix}`,\n    `${targetAgentClassName}Client${naming.clientClassSuffix}`,\n  );\n\n  // 3. Transform agent.py to add the A2A client import + wrap it as a tool\n  const agentSourceDir = joinPathFragments(\n    sourceProject.root,\n    agentComponent.path ?? 'src',\n  );\n  const agentFilePath = joinPathFragments(agentSourceDir, 'agent.py');\n\n  if (tree.exists(agentFilePath)) {\n    const clientClassName = `${targetAgentClassName}Client${naming.clientClassSuffix}`;\n    const clientVarName = targetAgentSnakeCase;\n    const toolName = `ask_${targetAgentSnakeCase}`;\n\n    await addImportToAgentFile(\n      tree,\n      agentFilePath,\n      agentConnectionModuleName,\n      clientClassName,\n      framework,\n    );\n    await addToolToAgent(tree, agentFilePath, toolName, framework);\n    await addClientToolToGetAgent(\n      tree,\n      agentFilePath,\n      clientClassName,\n      clientVarName,\n      toolName,\n      targetAgentClassName,\n      framework,\n    );\n  }\n\n  // 4. Add workspace dependency from agent project to agent-connection project\n  addWorkspaceDependencyToPyProject(\n    tree,\n    sourceProject,\n    getPythonAgentConnectionProject(tree),\n  );\n\n  // 5. Set up dev target dependencies — chain onto the target agent\n  const agentName = agentComponent.name ?? 'agent';\n  const devTargetName = `${agentName}-dev`;\n  const targetDevTargetName = `${targetAgentComponentName}-dev`;\n\n  if (sourceProject.targets?.[devTargetName]) {\n    addDependencyToTargetIfNotPresent(sourceProject, devTargetName, {\n      projects: [targetProject.name],\n      target: targetDevTargetName,\n    });\n    updateProjectConfiguration(tree, sourceProject.name, sourceProject);\n  }\n\n  // Recorded so the version sync knows this connection's dependencies are ours.\n  addComponentGeneratorMetadata(\n    tree,\n    sourceProject.name,\n    PY_AGENT_A2A_CONNECTION_GENERATOR_INFO,\n    toProjectRelativePath(sourceProject, agentFilePath),\n    targetAgentClassName,\n    // `sourcePath` names the source component this connection is made from, so\n    // the pair is identifiable rather than just the two projects.\n    { ...metadata, sourcePath: options.sourceComponent?.path },\n  );\n\n  await addGeneratorMetricsIfApplicable(tree, [\n    PY_AGENT_A2A_CONNECTION_GENERATOR_INFO,\n  ]);\n\n  await formatFilesInSubtree(tree);\n  return () =>\n    installDependencies(tree, options.preferInstallDependencies, {\n      languages: ['typescript'],\n    });\n};\n\n/**\n * Add imports to agent.py:\n *  - `tool` (from `strands`, or `langchain_core.tools` for LangChain agents)\n *  - the per-connection client class from the shared agent-connection module\n */\nconst addImportToAgentFile = async (\n  tree: Tree,\n  filePath: string,\n  agentConnectionModuleName: string,\n  clientClassName: string,\n  framework: AgentFramework,\n): Promise<void> => {\n  await addPythonDestructuredImport(\n    tree,\n    filePath,\n    ['tool'],\n    TOOL_IMPORT_MODULE[framework],\n  );\n  await addPythonDestructuredImport(\n    tree,\n    filePath,\n    [clientClassName],\n    agentConnectionModuleName,\n  );\n};\n\n/**\n * Add the A2A tool to the Agent's tools array using GritQL.\n *\n * Scoped to the framework's agent constructor so unrelated `tools=` keyword\n * arguments elsewhere in the file are not touched.\n */\nconst addToolToAgent = async (\n  tree: Tree,\n  filePath: string,\n  toolName: string,\n  framework: AgentFramework,\n): Promise<void> => {\n  const scope = AGENT_CONSTRUCTOR[framework];\n  await applyGritQL(\n    tree,\n    filePath,\n    py(`\\`tools=$old\\` where {\n  $old <: within \\`${scope}\\`,\n  $old <: not contains \\`${toolName}\\`,\n  if ($old <: \\`[]\\`) {\n    $old => \\`[${toolName}]\\`\n  } else {\n    $old <: \\`[$items]\\` where { $items += \\`, ${toolName}\\` }\n  }\n}`),\n  );\n};\n\n/**\n * Wrap the get_agent body so the remote A2A client is created and exposed\n * as a `@tool`-decorated closure before constructing the Agent.\n *\n * Unlike MCP clients, A2A clients aren't context managers — we don't need\n * a `with` block around them. Creation + tool definition happen at the\n * top of the function body, anchored on the framework's agent constructor.\n */\nconst addClientToolToGetAgent = async (\n  tree: Tree,\n  filePath: string,\n  clientClassName: string,\n  clientVarName: string,\n  toolName: string,\n  targetAgentClassName: string,\n  framework: AgentFramework,\n): Promise<void> => {\n  if (await matchGritQL(tree, filePath, py(`\\`${clientClassName}.create\\``))) {\n    return;\n  }\n\n  // Both frameworks' tools are @tool-decorated callables (the decorator's\n  // import differs, handled in addImportToAgentFile), defined inline in\n  // get_agent. The client is directly callable, returning the remote's reply.\n  const toolBlock = `${clientVarName} = ${clientClassName}.create()\n\n    @tool\n    def ${toolName}(prompt: str) -> str:\n        \"\"\"Delegate a question to the remote ${targetAgentClassName} A2A agent and return its reply.\"\"\"\n        return str(${clientVarName}(prompt))\n`;\n\n  // Prepend client creation + tool definition to the function body, anchored on\n  // the framework's agent constructor. This works whether or not a prior MCP\n  // block is present since we insert before any existing statements.\n  const anchor = AGENT_CONSTRUCTOR[framework];\n  await applyGritQL(\n    tree,\n    filePath,\n    py(`\\`def get_agent($params):\n    $body\\` where {\n  $body <: contains \\`${anchor}\\`,\n  $body <: not contains \\`${clientClassName}.create\\`\n} => \\`def get_agent($params):\n    ${toolBlock}\n    $body\\``),\n  );\n};\n\nexport default pyAgentA2aConnectionGenerator;\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","updateProjectConfiguration","addPyDependencies","AGENT_CONNECTION_PY_DEPENDENCIES","addPythonCoreClient","addPythonReExport","ensurePythonAgentConnectionProject","getPythonAgentConnectionModuleName","getPythonAgentConnectionProject","getPythonAgentConnectionProjectDir","PY_CLIENT_NAMING","resolveAgentFramework","addPythonDestructuredImport","applyGritQL","matchGritQL","declareDependencies","ownedElsewhere","formatFilesInSubtree","installDependencies","addGeneratorMetricsIfApplicable","snakeCase","addComponentGeneratorMetadata","addDependencyToTargetIfNotPresent","getGeneratorInfo","readProjectConfigurationUnqualified","toProjectRelativePath","addWorkspaceDependencyToPyProject","py","pattern","TOOL_IMPORT_MODULE","strands","langchain","AGENT_CONSTRUCTOR","DEPENDENCIES","name","when","m","framework","PY_AGENT_A2A_CONNECTION_GENERATOR_INFO","filename","pyAgentA2aConnectionGenerator","tree","options","sourceProject","targetProject","agentComponent","sourceComponent","targetAgentComponent","targetComponent","Error","protocol","toLowerCase","auth","targetAgentComponentName","targetAgentClassName","rc","targetAgentSnakeCase","targetAgentPort","port","naming","metadata","agentConnectionProjectDir","agentConnectionModuleName","projectRoot","appDir","dirname","appTemplateSubdir","overwriteStrategy","KeepExisting","appInitPath","exists","write","moduleInitPath","clientModuleSuffix","clientClassSuffix","agentSourceDir","root","path","agentFilePath","clientClassName","clientVarName","toolName","addImportToAgentFile","addToolToAgent","addClientToolToGetAgent","agentName","devTargetName","targetDevTargetName","targets","projects","target","sourcePath","preferInstallDependencies","languages","filePath","scope","toolBlock","anchor"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/py/agent/a2a-connection/generator.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  type GeneratorCallback,\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { addPyDependencies } from '../../../utils/add-dependencies';\nimport {\n  AGENT_CONNECTION_PY_DEPENDENCIES,\n  type AgentFramework,\n  addPythonCoreClient,\n  addPythonReExport,\n  ensurePythonAgentConnectionProject,\n  getPythonAgentConnectionModuleName,\n  getPythonAgentConnectionProject,\n  getPythonAgentConnectionProjectDir,\n  PY_CLIENT_NAMING,\n  resolveAgentFramework,\n} from '../../../utils/agent-connection/agent-connection';\nimport {\n  addPythonDestructuredImport,\n  appendToArrayViaGritQL,\n  applyGritQL,\n  matchGritQL,\n} from '../../../utils/ast';\nimport {\n  declareDependencies,\n  ownedElsewhere,\n} from '../../../utils/declared-dependencies';\nimport { formatFilesInSubtree } from '../../../utils/format';\nimport { installDependencies } from '../../../utils/install';\nimport { addGeneratorMetricsIfApplicable } from '../../../utils/metrics';\nimport { snakeCase } from '../../../utils/names';\nimport {\n  addComponentGeneratorMetadata,\n  addDependencyToTargetIfNotPresent,\n  getGeneratorInfo,\n  type NxGeneratorInfo,\n  readProjectConfigurationUnqualified,\n} from '../../../utils/nx';\nimport { toProjectRelativePath } from '../../../utils/paths';\nimport { addWorkspaceDependencyToPyProject } from '../../../utils/py';\nimport type { PyAgentA2aConnectionGeneratorSchema } from './schema';\n\n/** Prefix a GritQL pattern with `language python` */\nconst py = (pattern: string) => `language python\\n${pattern}`;\n\n/** The module each framework imports the `tool` decorator from. */\nconst TOOL_IMPORT_MODULE: Record<AgentFramework, string> = {\n  strands: 'strands',\n  langchain: 'langchain_core.tools',\n};\n\n/** The GritQL pattern matching each framework's agent constructor. */\nconst AGENT_CONSTRUCTOR: Record<AgentFramework, string> = {\n  strands: 'yield Agent($_)',\n  langchain: 'create_agent($_)',\n};\n\n/** The metadata this generator records, which its predicates read. */\nexport interface PyAgentA2aConnectionMetadata {\n  readonly framework: AgentFramework;\n}\n\n// Each framework's Layer-2 client needs its own A2A transport: Strands wraps\n// strands' `A2AAgent` (strands-agents[a2a]); LangChain drives the a2a SDK\n// directly (a2a-sdk) and must not pull Strands in.\nexport const DEPENDENCIES = declareDependencies<PyAgentA2aConnectionMetadata>()(\n  {\n    py: [\n      { name: 'boto3' },\n      { name: 'httpx' },\n      { name: 'strands-agents[a2a]', when: (m) => m.framework === 'strands' },\n      { name: 'a2a-sdk', when: (m) => m.framework === 'langchain' },\n      ...ownedElsewhere(AGENT_CONNECTION_PY_DEPENDENCIES),\n    ],\n  },\n);\n\nexport const PY_AGENT_A2A_CONNECTION_GENERATOR_INFO: NxGeneratorInfo =\n  getGeneratorInfo(import.meta.filename);\n\nexport const pyAgentA2aConnectionGenerator = async (\n  tree: Tree,\n  options: PyAgentA2aConnectionGeneratorSchema,\n): Promise<GeneratorCallback> => {\n  const sourceProject = readProjectConfigurationUnqualified(\n    tree,\n    options.sourceProject,\n  );\n  const targetProject = readProjectConfigurationUnqualified(\n    tree,\n    options.targetProject,\n  );\n\n  const agentComponent = options.sourceComponent;\n  const targetAgentComponent = options.targetComponent;\n\n  if (!agentComponent || !targetAgentComponent) {\n    throw new Error(\n      'Both sourceComponent and targetComponent must be provided for py#agent -> a2a connections',\n    );\n  }\n\n  if ((targetAgentComponent.protocol ?? '').toLowerCase() !== 'a2a') {\n    throw new Error(\n      `Target agent '${targetAgentComponent.name}' uses the ${targetAgentComponent.protocol ?? 'http'} protocol — only A2A agents can be connected as tools.`,\n    );\n  }\n\n  if (\n    targetAgentComponent.auth &&\n    targetAgentComponent.auth.toLowerCase() !== 'iam'\n  ) {\n    throw new Error(\n      `A2A agent connection currently only supports IAM authentication, but '${targetAgentComponent.name}' uses '${targetAgentComponent.auth}' authentication.`,\n    );\n  }\n\n  const targetAgentComponentName = targetAgentComponent.name ?? 'agent';\n  const targetAgentClassName = targetAgentComponent.rc as string;\n  const targetAgentSnakeCase = snakeCase(targetAgentClassName);\n  const targetAgentPort = targetAgentComponent.port ?? 9000;\n\n  // The source agent's framework drives everything that varies: the client\n  // naming + app template (shared with the mcp/gateway generators via\n  // PY_CLIENT_NAMING), the A2A transport dep (see DEPENDENCIES), and the\n  // agent.py transform below. Each framework wraps its own A2A Layer-2 client\n  // (Strands' A2AAgent vs an a2a-sdk-only client) over the shared,\n  // framework-agnostic A2A client config. Keyed on the framework, not a\n  // boolean, so a third framework stays additive.\n  const framework = resolveAgentFramework(agentComponent.framework);\n  const naming = PY_CLIENT_NAMING[framework];\n\n  // Recorded below and read by the declaration's predicates, so the packages\n  // added here are exactly the ones the version sync will own.\n  const metadata: PyAgentA2aConnectionMetadata = { framework };\n\n  // 1. Ensure the shared Python agent-connection project exists + has the\n  //    A2A core client (framework Layer-2) and its shared SigV4 auth helper.\n  await ensurePythonAgentConnectionProject(tree, DEPENDENCIES);\n  await addPythonCoreClient(tree, 'a2a', DEPENDENCIES, framework);\n\n  const agentConnectionProjectDir = getPythonAgentConnectionProjectDir(tree);\n  const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);\n\n  // A2A client config + shared auth helper deps, plus the framework's A2A\n  // transport dep. These belong to the shared agent-connection project, which\n  // holds the client.\n  addPyDependencies(tree, DEPENDENCIES, {\n    metadata,\n    projectRoot: agentConnectionProjectDir,\n  });\n\n  // 2. Generate the per-connection client into the shared agent-connection project\n  const appDir = joinPathFragments(\n    agentConnectionProjectDir,\n    agentConnectionModuleName,\n    'app',\n  );\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', naming.appTemplateSubdir),\n    appDir,\n    {\n      targetAgentSnakeCase,\n      targetAgentClassName,\n      targetAgentPort,\n      agentConnectionModuleName,\n    },\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n\n  // Ensure app/__init__.py exists\n  const appInitPath = joinPathFragments(appDir, '__init__.py');\n  if (!tree.exists(appInitPath)) {\n    tree.write(appInitPath, '');\n  }\n\n  // Add re-export to module __init__.py\n  const moduleInitPath = joinPathFragments(\n    agentConnectionProjectDir,\n    agentConnectionModuleName,\n    '__init__.py',\n  );\n  await addPythonReExport(\n    tree,\n    moduleInitPath,\n    `.app.${targetAgentSnakeCase}_client_${naming.clientModuleSuffix}`,\n    `${targetAgentClassName}Client${naming.clientClassSuffix}`,\n  );\n\n  // 3. Transform agent.py to add the A2A client import + wrap it as a tool\n  const agentSourceDir = joinPathFragments(\n    sourceProject.root,\n    agentComponent.path ?? 'src',\n  );\n  const agentFilePath = joinPathFragments(agentSourceDir, 'agent.py');\n\n  if (tree.exists(agentFilePath)) {\n    const clientClassName = `${targetAgentClassName}Client${naming.clientClassSuffix}`;\n    const clientVarName = targetAgentSnakeCase;\n    const toolName = `ask_${targetAgentSnakeCase}`;\n\n    await addImportToAgentFile(\n      tree,\n      agentFilePath,\n      agentConnectionModuleName,\n      clientClassName,\n      framework,\n    );\n    await addToolToAgent(tree, agentFilePath, toolName, framework);\n    await addClientToolToGetAgent(\n      tree,\n      agentFilePath,\n      clientClassName,\n      clientVarName,\n      toolName,\n      targetAgentClassName,\n      framework,\n    );\n  }\n\n  // 4. Add workspace dependency from agent project to agent-connection project\n  addWorkspaceDependencyToPyProject(\n    tree,\n    sourceProject,\n    getPythonAgentConnectionProject(tree),\n  );\n\n  // 5. Set up dev target dependencies — chain onto the target agent\n  const agentName = agentComponent.name ?? 'agent';\n  const devTargetName = `${agentName}-dev`;\n  const targetDevTargetName = `${targetAgentComponentName}-dev`;\n\n  if (sourceProject.targets?.[devTargetName]) {\n    addDependencyToTargetIfNotPresent(sourceProject, devTargetName, {\n      projects: [targetProject.name],\n      target: targetDevTargetName,\n    });\n    updateProjectConfiguration(tree, sourceProject.name, sourceProject);\n  }\n\n  // Recorded so the version sync knows this connection's dependencies are ours.\n  addComponentGeneratorMetadata(\n    tree,\n    sourceProject.name,\n    PY_AGENT_A2A_CONNECTION_GENERATOR_INFO,\n    toProjectRelativePath(sourceProject, agentFilePath),\n    targetAgentClassName,\n    // `sourcePath` names the source component this connection is made from, so\n    // the pair is identifiable rather than just the two projects.\n    { ...metadata, sourcePath: options.sourceComponent?.path },\n  );\n\n  await addGeneratorMetricsIfApplicable(tree, [\n    PY_AGENT_A2A_CONNECTION_GENERATOR_INFO,\n  ]);\n\n  await formatFilesInSubtree(tree);\n  return () =>\n    installDependencies(tree, options.preferInstallDependencies, {\n      languages: ['typescript'],\n    });\n};\n\n/**\n * Add imports to agent.py:\n *  - `tool` (from `strands`, or `langchain_core.tools` for LangChain agents)\n *  - the per-connection client class from the shared agent-connection module\n */\nconst addImportToAgentFile = async (\n  tree: Tree,\n  filePath: string,\n  agentConnectionModuleName: string,\n  clientClassName: string,\n  framework: AgentFramework,\n): Promise<void> => {\n  await addPythonDestructuredImport(\n    tree,\n    filePath,\n    ['tool'],\n    TOOL_IMPORT_MODULE[framework],\n  );\n  await addPythonDestructuredImport(\n    tree,\n    filePath,\n    [clientClassName],\n    agentConnectionModuleName,\n  );\n};\n\n/**\n * Add the A2A tool to the Agent's tools array using GritQL.\n *\n * Scoped to the framework's agent constructor so unrelated `tools=` keyword\n * arguments elsewhere in the file are not touched.\n */\nconst addToolToAgent = async (\n  tree: Tree,\n  filePath: string,\n  toolName: string,\n  framework: AgentFramework,\n): Promise<void> => {\n  await appendToArrayViaGritQL(tree, filePath, 'tools=', toolName, {\n    scope: AGENT_CONSTRUCTOR[framework],\n    language: 'py',\n  });\n};\n\n/**\n * Wrap the get_agent body so the remote A2A client is created and exposed\n * as a `@tool`-decorated closure before constructing the Agent.\n *\n * Unlike MCP clients, A2A clients aren't context managers — we don't need\n * a `with` block around them. Creation + tool definition happen at the\n * top of the function body, anchored on the framework's agent constructor.\n */\nconst addClientToolToGetAgent = async (\n  tree: Tree,\n  filePath: string,\n  clientClassName: string,\n  clientVarName: string,\n  toolName: string,\n  targetAgentClassName: string,\n  framework: AgentFramework,\n): Promise<void> => {\n  if (await matchGritQL(tree, filePath, py(`\\`${clientClassName}.create\\``))) {\n    return;\n  }\n\n  // Both frameworks' tools are @tool-decorated callables (the decorator's\n  // import differs, handled in addImportToAgentFile), defined inline in\n  // get_agent. The client is directly callable, returning the remote's reply.\n  const toolBlock = `${clientVarName} = ${clientClassName}.create()\n\n    @tool\n    def ${toolName}(prompt: str) -> str:\n        \"\"\"Delegate a question to the remote ${targetAgentClassName} A2A agent and return its reply.\"\"\"\n        return str(${clientVarName}(prompt))\n`;\n\n  // Prepend client creation + tool definition to the function body, anchored on\n  // the framework's agent constructor. This works whether or not a prior MCP\n  // block is present since we insert before any existing statements.\n  const anchor = AGENT_CONSTRUCTOR[framework];\n  await applyGritQL(\n    tree,\n    filePath,\n    py(`\\`def get_agent($params):\n    $body\\` where {\n  $body <: contains \\`${anchor}\\`,\n  $body <: not contains \\`${clientClassName}.create\\`\n} => \\`def get_agent($params):\n    ${toolBlock}\n    $body\\``),\n  );\n};\n\nexport default pyAgentA2aConnectionGenerator;\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","updateProjectConfiguration","addPyDependencies","AGENT_CONNECTION_PY_DEPENDENCIES","addPythonCoreClient","addPythonReExport","ensurePythonAgentConnectionProject","getPythonAgentConnectionModuleName","getPythonAgentConnectionProject","getPythonAgentConnectionProjectDir","PY_CLIENT_NAMING","resolveAgentFramework","addPythonDestructuredImport","appendToArrayViaGritQL","applyGritQL","matchGritQL","declareDependencies","ownedElsewhere","formatFilesInSubtree","installDependencies","addGeneratorMetricsIfApplicable","snakeCase","addComponentGeneratorMetadata","addDependencyToTargetIfNotPresent","getGeneratorInfo","readProjectConfigurationUnqualified","toProjectRelativePath","addWorkspaceDependencyToPyProject","py","pattern","TOOL_IMPORT_MODULE","strands","langchain","AGENT_CONSTRUCTOR","DEPENDENCIES","name","when","m","framework","PY_AGENT_A2A_CONNECTION_GENERATOR_INFO","filename","pyAgentA2aConnectionGenerator","tree","options","sourceProject","targetProject","agentComponent","sourceComponent","targetAgentComponent","targetComponent","Error","protocol","toLowerCase","auth","targetAgentComponentName","targetAgentClassName","rc","targetAgentSnakeCase","targetAgentPort","port","naming","metadata","agentConnectionProjectDir","agentConnectionModuleName","projectRoot","appDir","dirname","appTemplateSubdir","overwriteStrategy","KeepExisting","appInitPath","exists","write","moduleInitPath","clientModuleSuffix","clientClassSuffix","agentSourceDir","root","path","agentFilePath","clientClassName","clientVarName","toolName","addImportToAgentFile","addToolToAgent","addClientToolToGetAgent","agentName","devTargetName","targetDevTargetName","targets","projects","target","sourcePath","preferInstallDependencies","languages","filePath","scope","language","toolBlock","anchor"],"mappings":"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"}

package/src/py/agent/files/deploy/Dockerfile.template

@@ -1,5 +1,12 @@
 FROM <%- pythonBaseImage %>
 
+# Apply the distribution's security updates: base image tags lag behind the
+# security suite, so its OS packages carry fixed HIGH/CRITICAL vulnerabilities
+# flagged by the image scan.
+RUN apt-get update && \
+    apt-get upgrade -y --no-install-recommends && \
+    rm -rf /var/lib/apt/lists/*
+
 # Remove the base image's pip: the agent runs from the bundled environment and
 # never needs it at runtime, and pip's vendored packages carry known
 # HIGH/CRITICAL vulnerabilities flagged by the image scan.

package/src/py/agent/files/langchain/common/agent.py.template

@@ -3,7 +3,8 @@ import os
 from langchain.agents import create_agent
 from langchain_aws import ChatBedrockConverse
 from langchain_core.tools import tool
-from langgraph.checkpoint.memory import InMemorySaver
+
+from .session import get_checkpointer
 
 REGION = os.environ.get("AWS_REGION", "us-east-1")
 MODEL_ID = os.environ.get("MODEL_ID", "global.anthropic.claude-haiku-4-5-20251001-v1:0")
@@ -17,7 +18,6 @@ def subtract(a: int, b: int) -> int:
 
 def get_agent():
     model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
-    # Swap InMemorySaver for a durable checkpointer in a multi-replica deployment.
     return create_agent(
         model=model,
         tools=[subtract],
@@ -26,5 +26,5 @@ You are a mathematical wizard.
 Use your tools for mathematical tasks.
 Refer to tools as your 'spellbook'.
 """,
-        checkpointer=InMemorySaver(),
+        checkpointer=get_checkpointer(),
     )

package/src/py/agent/files/langchain/common/session.py.template

@@ -0,0 +1,61 @@
+import os
+
+<%_ if (session === 's3') { _%>
+import boto3
+<%_ } _%>
+import aiosqlite
+from langgraph.checkpoint.base import BaseCheckpointSaver
+<%_ if (session === 'in-memory') { _%>
+from langgraph.checkpoint.memory import InMemorySaver
+<%_ } _%>
+from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+<%_ if (session === 's3') { _%>
+from <%- agentConnectionModuleName %>.core.s3_checkpoint_saver_langchain import S3CheckpointSaver
+<%_ } else if (session === 'dynamodb-s3') { _%>
+from langgraph_checkpoint_aws import DynamoDBSaver
+<%_ } _%>
+<%_ if (session === 's3' || session === 'dynamodb-s3') { _%>
+from <%- agentConnectionModuleName %>.core.runtime_config import get_agentcore_runtime_config
+<%_ } _%>
+
+
+def get_checkpointer() -> BaseCheckpointSaver:
+    """Returns a LangGraph checkpointer for persisting conversation state across
+    invocations. Local development always uses a local SQLite database for
+    convenience, regardless of the configured session option.
+    """
+    if os.environ.get("LOCAL_DEV") == "true":
+        os.makedirs("<%- localSessionsDir %>", exist_ok=True)
+        conn = aiosqlite.connect(os.path.join("<%- localSessionsDir %>", "checkpoints.sqlite"))
+        return AsyncSqliteSaver(conn)
+
+<%_ if (session === 's3') { _%>
+    config = get_agentcore_runtime_config()
+    session_config = (config.get("agentRuntimes") or {}).get("<%- agentNameClassName %>", {}).get("session", {})
+    bucket_name = session_config.get("bucketName")
+    if not bucket_name:
+        raise RuntimeError(
+            "No S3 checkpoint bucket configured for this agent in runtime configuration."
+        )
+    return S3CheckpointSaver(
+        bucket_name=bucket_name,
+        prefix="checkpoints/",
+        s3_client=boto3.client("s3"),
+    )
+<%_ } else if (session === 'dynamodb-s3') { _%>
+    config = get_agentcore_runtime_config()
+    session_config = (config.get("agentRuntimes") or {}).get("<%- agentNameClassName %>", {}).get("session", {})
+    table_name = session_config.get("tableName")
+    bucket_name = session_config.get("bucketName")
+    if not table_name or not bucket_name:
+        raise RuntimeError(
+            "No DynamoDB checkpoint table or S3 offload bucket configured for this agent in runtime configuration."
+        )
+    return DynamoDBSaver(
+        table_name=table_name,
+        region_name=os.environ.get("AWS_REGION"),
+        s3_offload_config={"bucket_name": bucket_name},
+    )
+<%_ } else { _%>
+    return InMemorySaver()
+<%_ } _%>

package/src/py/agent/files/strands/ag-ui/main.py.template

@@ -4,7 +4,7 @@ from contextlib import asynccontextmanager
 
 from ag_ui.core import EventType, RunAgentInput, RunErrorEvent
 from ag_ui.encoder import EventEncoder
-from ag_ui_strands import StrandsAgent
+from ag_ui_strands import StrandsAgent, StrandsAgentConfig
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
@@ -12,6 +12,7 @@ from <%- agentConnectionModuleName %> import get_current_session_id, session_id_
 from starlette.middleware.base import BaseHTTPMiddleware
 
 from .agent import get_agent
+from .session import get_session_manager
 
 logging.basicConfig(level=logging.INFO)
 
@@ -25,6 +26,9 @@ async def lifespan(app: FastAPI):
             agent=agent,
             name="<%= agentNameClassName %>",
             description="A Strands Agent exposed via the AG-UI protocol.",
+            # A per-thread session manager, not the template Agent's own, since
+            # AG-UI caches one Strands agent per thread_id.
+            config=StrandsAgentConfig(session_manager_provider=lambda _input_data: get_session_manager()),
         )
         yield
 

package/src/py/agent/files/strands/common/agent.py.template

@@ -2,7 +2,11 @@ from contextlib import contextmanager
 
 from strands import Agent, tool
 from strands_tools import current_time
-from <%- agentConnectionModuleName %> import log_model_errors
+from <%- agentConnectionModuleName %> import log_model_errors, log_tool_errors
+<%_ if (protocol !== 'ag-ui') { _%>
+
+from .session import get_session_manager
+<%_ } _%>
 
 
 @tool
@@ -21,5 +25,8 @@ Use your tools for mathematical tasks.
 Refer to tools as your 'spellbook'.
 """,
         tools=[subtract, current_time],
-        hooks=[log_model_errors],
+        hooks=[log_model_errors, log_tool_errors],
+<%_ if (protocol !== 'ag-ui') { _%>
+        session_manager=get_session_manager(),
+<%_ } _%>
     )

package/src/py/agent/files/strands/common/session.py.template

@@ -0,0 +1,36 @@
+import os
+
+from strands.session import FileSessionManager, SessionManager<% if (session === 's3') { %>, S3SessionManager<% } %>
+
+from <%- agentConnectionModuleName %> import get_current_session_id
+<%_ if (session === 's3') { _%>
+from <%- agentConnectionModuleName %>.core.runtime_config import get_agentcore_runtime_config
+<%_ } _%>
+
+
+def get_session_manager() -> SessionManager | None:
+    """Returns a SessionManager for persisting conversation state across
+    invocations. Local development always uses local file storage for
+    convenience, regardless of the configured session option. Without a
+    configured session option, conversation state is kept in memory only and
+    does not survive process restarts.
+    """
+    session_id = get_current_session_id()
+    if not session_id:
+        raise RuntimeError(
+            "No current session id — cannot resolve a SessionManager outside of a request scope."
+        )
+    if os.environ.get("LOCAL_DEV") == "true":
+        return FileSessionManager(session_id=session_id, storage_dir="<%- localSessionsDir %>")
+
+<%_ if (session === 's3') { _%>
+    config = get_agentcore_runtime_config()
+    bucket_name = (
+        (config.get("agentRuntimes") or {}).get("<%- agentNameClassName %>", {}).get("session", {}).get("bucketName")
+    )
+    if not bucket_name:
+        raise RuntimeError("No S3 bucket configured for this agent's session in runtime configuration.")
+    return S3SessionManager(session_id=session_id, bucket=bucket_name)
+<%_ } else { _%>
+    return None
+<%_ } _%>

package/src/py/agent/generator.d.ts

@@ -5,7 +5,7 @@
 import { type GeneratorCallback, type Tree } from '@nx/devkit';
 import { type NxGeneratorInfo } from '../../utils/nx';
 import type { IacMetadata } from '../../utils/shared-constructs-constants';
-import type { AgentProtocol, PyAgentFramework, PyAgentGeneratorSchema } from './schema';
+import type { AgentProtocol, PyAgentFramework, PyAgentGeneratorSchema, PyAgentSession } from './schema';
 /** The metadata this generator records, which its predicates read. */
 export interface PyAgentMetadata extends IacMetadata {
     readonly port: number;
@@ -17,6 +17,7 @@ export interface PyAgentMetadata extends IacMetadata {
      * Strands vs LangChain Layer-2 client + agent.py transform.
      */
     readonly framework: PyAgentFramework;
+    readonly session: PyAgentSession;
 }
 export declare const DEPENDENCIES: import("../../utils/declared-dependencies").DependencyDeclaration<readonly [{
     readonly name: "agent-chat-cli";
@@ -120,6 +121,15 @@ export declare const DEPENDENCIES: import("../../utils/declared-dependencies").D
 }, {
     readonly name: "langgraph";
     readonly when: (m: PyAgentMetadata) => boolean;
+}, {
+    readonly name: "langgraph-checkpoint-sqlite";
+    readonly when: (m: PyAgentMetadata) => boolean;
+}, {
+    readonly name: "aiosqlite";
+    readonly when: (m: PyAgentMetadata) => boolean;
+}, {
+    readonly name: "langgraph-checkpoint-aws";
+    readonly when: (m: PyAgentMetadata) => boolean;
 }, {
     readonly name: "ag-ui-protocol";
     readonly when: (m: PyAgentMetadata) => boolean;

package/src/py/agent/generator.js

@@ -6,7 +6,7 @@ import { ensureLicenseExceptions } from "../../license/config.js";
 import { AG_UI_LANGGRAPH_EXCEPTIONS } from "../../license/known-exceptions.js";
 import { addPyDependencies, addTsDependencies } from "../../utils/add-dependencies.js";
 import { addAgentChatScripts } from "../../utils/agent-chat/agent-chat.js";
-import { AGENT_CONNECTION_PY_DEPENDENCIES, addPythonFrameworkBase, ensurePythonAgentConnectionProject, getPythonAgentConnectionModuleName, getPythonAgentConnectionProject } from "../../utils/agent-connection/agent-connection.js";
+import { AGENT_CONNECTION_PY_DEPENDENCIES, addPythonFrameworkBase, ensureLangchainS3CheckpointSaver, ensurePythonAgentConnectionProject, getPythonAgentConnectionModuleName, getPythonAgentConnectionProject } from "../../utils/agent-connection/agent-connection.js";
 import { addAgentInfra } from "../../utils/agent-core-constructs/agent-core-constructs.js";
 import { addPythonBundleTarget } from "../../utils/bundle/bundle.js";
 import { resolveContainers } from "../../utils/containers.js";
@@ -22,7 +22,7 @@ import { kebabCase, toClassName, toSnakeCase } from "../../utils/names.js";
 import { getNpmScope } from "../../utils/npm-scope.js";
 import { addComponentDevTarget, addComponentGeneratorMetadata, addDependencyToTargetIfNotPresent, getGeneratorInfo, normalizeTargetKeyOrder, readProjectConfigurationUnqualified } from "../../utils/nx.js";
 import { sortObjectKeys } from "../../utils/object.js";
-import { toProjectRelativePath } from "../../utils/paths.js";
+import { getRelativePathToRootByDirectory, toProjectRelativePath } from "../../utils/paths.js";
 import { assignPort } from "../../utils/port.js";
 import { addWorkspaceDependencyToPyProject } from "../../utils/py.js";
 import { SHARED_CONSTRUCTS_DEPENDENCIES, sharedConstructsGenerator } from "../../utils/shared-constructs.js";
@@ -117,6 +117,22 @@ export const DEPENDENCIES = declareDependencies()({
             name: 'langgraph',
             when: (m)=>m.framework === 'langchain'
         },
+        // Local dev uses a SQLite-backed checkpointer for convenience (parity
+        // with the strands framework's local FileSessionManager).
+        {
+            name: 'langgraph-checkpoint-sqlite',
+            when: (m)=>m.framework === 'langchain'
+        },
+        // AsyncSqliteSaver's driver, required alongside langgraph-checkpoint-sqlite.
+        {
+            name: 'aiosqlite',
+            when: (m)=>m.framework === 'langchain'
+        },
+        // Provides DynamoDBSaver (with S3 offloading for large checkpoints).
+        {
+            name: 'langgraph-checkpoint-aws',
+            when: (m)=>m.framework === 'langchain' && m.session === 'dynamodb-s3'
+        },
         {
             name: 'ag-ui-protocol',
             when: (m)=>m.framework === 'langchain' && m.protocol === 'ag-ui'
@@ -131,25 +147,25 @@ export const DEPENDENCIES = declareDependencies()({
         },
         {
             name: 'strands-agents[a2a]',
-            when: (m)=>m.framework !== 'langchain' && m.protocol === 'a2a'
+            when: (m)=>m.framework === 'strands' && m.protocol === 'a2a'
         },
         {
             name: 'strands-agents',
-            when: (m)=>m.framework !== 'langchain' && m.protocol !== 'a2a'
+            when: (m)=>m.framework === 'strands' && m.protocol !== 'a2a'
         },
         {
             name: 'strands-agents-tools',
-            when: (m)=>m.framework !== 'langchain'
+            when: (m)=>m.framework === 'strands'
         },
         // Declared again here so a Strands AG-UI agent lists it in the same order
         // the generated pyproject.toml had before.
         {
             name: 'ag-ui-protocol',
-            when: (m)=>m.framework !== 'langchain' && m.protocol === 'ag-ui'
+            when: (m)=>m.framework === 'strands' && m.protocol === 'ag-ui'
         },
         {
             name: 'ag-ui-strands',
-            when: (m)=>m.framework !== 'langchain' && m.protocol === 'ag-ui'
+            when: (m)=>m.framework === 'strands' && m.protocol === 'ag-ui'
         },
         {
             name: 'uvicorn'
@@ -193,9 +209,41 @@ export const pyAgentGenerator = async (tree, options)=>{
         console.warn('Warning: auth is ignored when no infrastructure is configured (no infrastructure is generated)');
     }
     const auth = options.auth ?? 'iam';
-    // Only 'in-memory' is currently supported for Python agents (session manager
-    // support for Python is not yet implemented).
-    const session = options.session ?? 'in-memory';
+    // Session backends are framework-specific: Strands' SessionManager only has
+    // an S3-backed implementation here (via strands.session.S3SessionManager),
+    // while LangChain uses dedicated S3 and DynamoDB checkpointer libraries.
+    // 'in-memory' is valid for both.
+    const SESSIONS_BY_FRAMEWORK = {
+        strands: [
+            's3',
+            'in-memory'
+        ],
+        langchain: [
+            's3',
+            'dynamodb-s3',
+            'in-memory'
+        ]
+    };
+    if (options.session && !SESSIONS_BY_FRAMEWORK[framework].includes(options.session)) {
+        throw new Error(`Unsupported combination: session '${options.session}' is not implemented for the ${framework} framework (supported: ${SESSIONS_BY_FRAMEWORK[framework].join(', ')}).`);
+    }
+    const session = options.session ?? 's3';
+    // With infra=none there's no CDK/Terraform construct to provision a bucket
+    // or table or set RUNTIME_CONFIG_APP_ID, so session.py's non-local-dev
+    // branch has nothing to read from AppConfig at runtime — the generated code
+    // still honors `session`, but only works outside local dev if the caller
+    // wires up matching infra/runtime config themselves.
+    if (infra === 'none' && session !== 'in-memory') {
+        console.warn(`Warning: session '${session}' requires infrastructure to configure it automatically (no infrastructure is generated for infra=none) — outside local dev this will fail unless you configure matching runtime config yourself`);
+    }
+    // Local-dev session storage lives at the workspace root
+    // (`tmp/agents/<framework>/<agent-name>`), not inside the project, so each
+    // agent gets its own storage directory — shared by both frameworks
+    // (Strands' FileSessionManager, LangChain's SqliteSaver). The
+    // `-dev`/`-serve` targets run with cwd={projectRoot}, so compute that
+    // directory relative to the project root here rather than resolving it at
+    // runtime.
+    const localSessionsDir = joinPathFragments(getRelativePathToRootByDirectory(project.root), `tmp/agents/${framework}/${name}`);
     // Ensure the shared agent-connection project exists so the server entry
     // point can import `session_id_context` and propagate the AgentCore
     // session ID to any downstream MCP / A2A clients a later connection
@@ -203,8 +251,8 @@ export const pyAgentGenerator = async (tree, options)=>{
     await ensurePythonAgentConnectionProject(tree, DEPENDENCIES);
     // The agent server imports the framework base helpers (session cache + model
     // error logging) regardless of whether a connection client is wired in. The
-    // langchain framework has no base layer (its AG-UI foundation reuses only the
-    // framework-agnostic session context), so this is a no-op for langchain.
+    // LangChain framework has no base layer (its AG-UI foundation reuses only the
+    // framework-agnostic session context), so this is a no-op for LangChain.
     await addPythonFrameworkBase(tree, DEPENDENCIES, framework);
     const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);
     addWorkspaceDependencyToPyProject(tree, project, getPythonAgentConnectionProject(tree));
@@ -214,27 +262,28 @@ export const pyAgentGenerator = async (tree, options)=>{
         agentNameClassName,
         moduleName,
         agentConnectionModuleName,
-        framework
+        framework,
+        protocol,
+        session,
+        localSessionsDir
     };
-    // Generate common files shared by both protocols. The agent module (agent.py)
-    // is framework-specific (Strands yields a contextmanaged Agent; LangChain
-    // returns a compiled create_agent graph), so it comes from a per-framework
-    // dir. The package __init__.py is framework-agnostic (it stays in `common`).
+    // Files live under a per-framework dir (files/strands, files/langchain),
+    // mirrored one-for-one — including files that don't vary by framework
+    // (e.g. the empty package __init__.py) — so there's a single, uniform
+    // <framework>/<protocol> layout with no cross-framework fallbacks.
+    // `framework` is itself the directory name.
+    // Common files shared by both protocols: the agent module (Strands yields a
+    // contextmanaged Agent with a session.py sibling; LangChain returns a
+    // compiled create_agent graph) and the package __init__.py.
     generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', framework, 'common'), targetSourceDir, templateContext, {
         overwriteStrategy: OverwriteStrategy.KeepExisting
     });
-    if (framework === 'langchain') {
-        // langchain/common only carries agent.py; the empty package __init__.py is
-        // framework-agnostic, so emit it from the strands `common` dir.
-        generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'strands', 'common'), targetSourceDir, templateContext, {
-            overwriteStrategy: OverwriteStrategy.KeepExisting
-        });
+    if (framework === 'langchain' && session === 's3') {
+        ensureLangchainS3CheckpointSaver(tree);
     }
-    // Generate protocol-specific files. Each protocol's server entry point (and,
-    // for HTTP, its init.py building the FastAPI app + lifespan) is
-    // framework-specific (Strands yields a contextmanaged Agent; LangChain drives
-    // a compiled create_agent graph), so it comes from a per-framework,
-    // per-protocol dir: `files/<framework>/<protocol>`.
+    // Protocol-specific files. Each protocol's server entry point is
+    // framework-specific (Strands yields a contextmanaged Agent; LangChain
+    // drives a compiled create_agent graph).
     const protocolLower = protocol.toLowerCase();
     generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', framework, protocolLower), targetSourceDir, templateContext, {
         overwriteStrategy: OverwriteStrategy.KeepExisting
@@ -325,6 +374,7 @@ export const pyAgentGenerator = async (tree, options)=>{
         auth,
         protocol,
         framework,
+        session,
         ...iac ? {
             iac
         } : {}