aws / aws/bedrock-agentcore-starter-toolkit
feat: support uv workspace sources in direct_code_deploy
- Dominant language
- Python
- Stars
- 508
- Forks
- 155
- Avg merge
- 8h 50m
- Merged PRs (30d)
- 4
Description
## Summary
`agentcore launch` (direct_code_deploy) does not resolve `[tool.uv.sources]` workspace dependencies when building the deployment package, causing `ModuleNotFoundError` at runtime for any package that lives in the same repo as a workspace member.
## Current behavior
When a project uses a [uv workspace](https://docs.astral.sh/uv/concepts/workspaces/) to share a local library across agents, the `pyproject.toml` for each agent declares the dependency like this:
```toml
[project]
dependencies = ["shared-utils"]
[tool.uv.sources]
shared-utils = { workspace = true }
```
This works perfectly for local development (`uv sync` resolves the workspace member and installs it as an editable package). However, when `agentcore launch` runs, it builds `dependencies.zip` by executing:
```
uv pip install --target \
--python-version 3.12 \
--python-platform aarch64-manylinux2014 \
--only-binary :all: \
-r requirements.txt
```
This bare `uv pip install` call has no awareness of the workspace — `[tool.uv.sources]` is silently ignored. The local package is never installed, never bundled, and the agent fails at runtime with:
```
ModuleNotFoundError: No module named 'shared_utils'
```
## Why the pyproject.toml fallback also fails
If `requirements.txt` is absent, agentcore falls back to `pyproject.toml` and runs `uv pip compile pyproject.toml`. This also fails:
```
error: Failed to parse entry: `shared-utils`
Caused by: `shared-utils` references a workspace in `tool.uv.sources`
but is not a workspace member
```
`uv pip compile` requires the package to be listed in the workspace root's `[tool.uv.workspace].members`. Agent subdirectories are typically not registered as workspace members, so this path is a dead end.
## Root cause
`agentcore launch` treats the agent directory as self-contained. The existing `expand_source_path_for_dependencies` utility in `bedrock_agentcore_starter_toolkit/utils/paths.py` has the right idea — it expands the build context to the common root when a dependency is outside the source dir — but it is not wired up to handle workspace sources declared in `[tool.uv.sources]`.
## Expected behavior
When agentcore detects a `[tool.uv.sources]` workspace entry in `pyproject.toml`, it should:
1. Resolve the workspace root (walk up directories until a `pyproject.toml` with `[tool.uv.workspace]` is found).
2. Expand the build context to include the workspace package directory (consistent with what `expand_source_path_for_dependencies` already does for path deps).
3. Pass the resolved path to `uv pip compile` / `uv pip install` so the local package is installed into `dependencies.zip`.
Alternatively, running `uv pip compile` with the workspace root as CWD (rather than the agent directory) would allow uv to resolve workspace members correctly.
## Workaround
Until this is fixed, the only reliable workaround is to build a wheel manually before each deployment and reference it by relative path in `requirements.txt`:
```bash
# Build wheel (not committed to git)
uv build --package shared-utils --out-dir packages/shared-utils/dist/
# requirements.txt in each agent:
../../../../packages/shared-utils/dist/shared_utils-0.1.0-py3-none-any.whl
```
This is fragile, requires a manual pre-deploy step, and defeats the purpose of having a workspace.
## Environment
- `bedrock-agentcore-starter-toolkit` version: 0.2.4
- Deployment type: `direct_code_deploy`
- Runtime: `PYTHON_3_12`
Contributor guide
Research direction
Start at agentcore launch and trace direct_code_deploy packaging in bedrock_agentcore_starter_toolkit/utils/paths.py, especially expand_source_path_for_dependencies. Review how requirements.txt and pyproject.toml are passed to uv pip compile or uv pip install. Done means workspace sources resolve from the workspace root and the local package is included in dependencies.zip without the manual wheel workaround.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, cli, cloud
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100