Packager silently excludes */agentcore/* subpackages from deployment zip #902

Description

Summary

The agentcore deploy command produces a zip that is missing any Python package
subdirectory named agentcore, causing ModuleNotFoundError at Lambda cold-start
for packages such as langgraph-checkpoint-aws >= 1.0.7 whose public API lives in
langgraph_checkpoint_aws/agentcore/.

Affected versions

Symptoms

Lambda cold-start traceback in CloudWatch:

File "/var/task/main.py", line 5, in <module>
    from langgraph_checkpoint_aws import AgentCoreMemorySaver
  File "/var/task/langgraph_checkpoint_aws/__init__.py", line 9, in <module>
    from langgraph_checkpoint_aws.agentcore.saver import (
ModuleNotFoundError: No module named 'langgraph_checkpoint_aws.agentcore'

The agent works correctly with agentcore dev (local Docker run) because the local
.venv is intact. Only agentcore deploy is affected.

Root cause

The file responsible for building the deployment zip is:

node_modules/@aws/agentcore-cdk/dist/lib/packaging/helpers.js

It contains a hardcoded exclusion set used by collectFilesSync when walking the
staging directory to build the zip:

// ~line 31
const EXCLUDED_ENTRIES = new Set([
    'agentcore',      // <-- the problem
    '.git',
    '.venv',
    '__pycache__',
    '.pytest_cache',
    '.DS_Store',
    'node_modules',
]);

The intent of 'agentcore' is to prevent the project's own agentcore/ config
directory from being bundled into the zip. However, the check is applied by
entry name only at every level of the directory tree, not just at the root:

for (const entry of entries) {
    if (EXCLUDED_ENTRIES.has(entry.name))
        continue;   // skips ANY directory named 'agentcore' anywhere in the tree
    ...
}

Because langgraph_checkpoint_aws/agentcore/ is a legitimate Python subpackage
installed into the staging directory, it is silently dropped from the zip.

The langgraph_checkpoint_aws/__init__.py imports unconditionally from this subpackage:

from langgraph_checkpoint_aws.agentcore.saver import AgentCoreMemorySaver
from langgraph_checkpoint_aws.agentcore.store import AgentCoreMemoryStore

So the deployed Lambda fails on import immediately at cold-start.

Crucially, the agentcore/ project config directory is never present in the
staging directory in the first place — only installed Python packages end up there.
The exclusion is therefore both unnecessary and harmful.

Suggested fix (upstream)

Remove 'agentcore' from EXCLUDED_ENTRIES in helpers.js. The agentcore/
project config directory is never present in the staging directory, so the entry
serves no purpose and only causes harm.

 const EXCLUDED_ENTRIES = new Set([
-    'agentcore',
     '.git',
     '.venv',
     '__pycache__',
     '.pytest_cache',
     '.DS_Store',
     'node_modules',
 ]);

If the intent is to guard against the project config directory specifically, a
safer alternative would be to only exclude entries at the top level of the
staging directory walk, rather than recursively at every depth.

Temporary local workaround

This patch must be applied to the installed node_modules (it will be reverted by
npm install — see re-application instructions below).

File to edit:

agentcore/cdk/node_modules/@aws/agentcore-cdk/dist/lib/packaging/helpers.js

Remove 'agentcore', from the EXCLUDED_ENTRIES set (around line 32):

 const EXCLUDED_ENTRIES = new Set([
-    'agentcore',
     '.git',
     '.venv',

After patching, delete the stale CDK output so CDK does not reuse the previously
hashed (broken) zip, then redeploy:

rm -rf agentcore/cdk/cdk.out
agentcore deploy

Verify the fix:

unzip -l agentcore/cdk/cdk.out/asset.*.zip | grep langgraph_checkpoint_aws/agentcore
# should now list: agentcore/saver.py, agentcore/store.py, etc.

Re-applying the patch after npm install

Running npm install inside agentcore/cdk/ will overwrite node_modules and
lose the patch. Re-apply it with:

sed -i "" "/'agentcore',/d" \
  agentcore/cdk/node_modules/@aws/agentcore-cdk/dist/lib/packaging/helpers.js
rm -rf agentcore/cdk/cdk.out
agentcore deploy

Notes

• This bug will affect any Python package that ships a subpackage named
  agentcore — not just langgraph-checkpoint-aws.
• agentcore dev is unaffected because it mounts the local .venv directly.
• The uv pip install step in the packager runs correctly and populates the
  staging directory with the full package including the agentcore/ subpackage.
  The bug is exclusively in the zip-creation step that follows.
• The staging directory at agentcore/.cache/<AgentName>/staging/ can be inspected
  to confirm the package is installed correctly before the zip is built.

Steps to Reproduce

1. Create an AgentCore project using the CodeZip build type with Python 3.12.
2. Add langgraph-checkpoint-aws==1.0.7 as a dependency in pyproject.toml.
3. Import AgentCoreMemorySaver from langgraph_checkpoint_aws in main.py.
4. Run agentcore deploy.
5. Invoke the deployed agent — observe the ModuleNotFoundError in CloudWatch.

Verify the zip is broken before deploying:

unzip -l agentcore/cdk/cdk.out/asset.*.zip | grep langgraph_checkpoint_aws/agentcore
# produces no output — directory is absent from the zip

Expected Behavior

• After deploying the Agent to AgentCore, there should be no 'ModuleNotFoundError'

Actual Behavior

Lambda cold-start traceback in CloudWatch:

File "/var/task/main.py", line 5, in <module>
    from langgraph_checkpoint_aws import AgentCoreMemorySaver
  File "/var/task/langgraph_checkpoint_aws/__init__.py", line 9, in <module>
    from langgraph_checkpoint_aws.agentcore.saver import (
ModuleNotFoundError: No module named 'langgraph_checkpoint_aws.agentcore'

The agent works correctly with agentcore dev (local Docker run) because the local
.venv is intact. Only agentcore deploy is affected.

CLI Version

0.9.1

Operating System

macOS

Additional Context

No response