aws / aws/bedrock-agentcore-starter-toolkit

feat: support uv workspace sources in direct_code_deploy

Open
#468 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.