generated from amazon-archives/__template_Apache-2.0
-
Notifications
You must be signed in to change notification settings - Fork 5
docs: add container build documentation #340
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
notgitika
wants to merge
2
commits into
main
Choose a base branch
from
docs/container-build
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| # Container Builds | ||
|
|
||
| Container builds package your agent as a Docker container image instead of a code ZIP. Use containers when you need | ||
| system-level dependencies, custom native libraries, or full control over the runtime environment. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| A container runtime is required for local development (`agentcore dev`) and packaging (`agentcore package`). Supported | ||
| runtimes: | ||
|
|
||
| 1. [Docker](https://docker.com) | ||
| 2. [Podman](https://podman.io) | ||
| 3. [Finch](https://runfinch.com) | ||
|
|
||
| The CLI auto-detects the first working runtime in the order listed above. If multiple are installed, the | ||
| highest-priority one wins. | ||
|
|
||
| > A local runtime is **not** required for `agentcore deploy` — AWS CodeBuild builds the image remotely. | ||
|
|
||
| ## Getting Started | ||
|
|
||
| ```bash | ||
| # New project with container build | ||
| agentcore create --name MyProject --build Container | ||
|
|
||
| # Add container agent to existing project | ||
| agentcore add agent --name MyAgent --build Container --framework Strands --model-provider Bedrock | ||
| ``` | ||
|
|
||
| Both commands generate a `Dockerfile` and `.dockerignore` in the agent's code directory: | ||
|
|
||
| ``` | ||
| app/MyAgent/ | ||
| ├── Dockerfile | ||
| ├── .dockerignore | ||
| ├── pyproject.toml | ||
| └── main.py | ||
| ``` | ||
|
|
||
| ## Generated Dockerfile | ||
|
|
||
| The template uses `ghcr.io/astral-sh/uv:python3.12-bookworm-slim` as the base image with these design choices: | ||
|
|
||
| - **Layer caching**: Dependencies (`pyproject.toml`) are installed before copying application code | ||
| - **Non-root**: Runs as `bedrock_agentcore` (UID 1000) | ||
| - **Observability**: Default CMD wraps the agent with `opentelemetry-instrument` | ||
| - **Fast installs**: Uses `uv pip install` for dependency resolution | ||
|
|
||
| You can customize the Dockerfile freely — add system packages, change the base image, or use multi-stage builds. | ||
|
|
||
| ## Configuration | ||
|
|
||
| In `agentcore.json`, set `"build": "Container"`: | ||
|
|
||
| ```json | ||
| { | ||
| "type": "AgentCoreRuntime", | ||
| "name": "MyAgent", | ||
| "build": "Container", | ||
| "entrypoint": "main.py", | ||
| "codeLocation": "app/MyAgent/", | ||
| "runtimeVersion": "PYTHON_3_12" | ||
| } | ||
| ``` | ||
|
|
||
| All other fields work the same as CodeZip agents. | ||
|
|
||
| > **Converting an existing CodeZip agent?** Changing the `build` field in `agentcore.json` alone is not enough — you | ||
| > must also add a `Dockerfile` and `.dockerignore` to the agent's code directory. The easiest way is to create a | ||
| > throwaway container agent with `agentcore add agent --build Container` and copy the generated files. | ||
|
|
||
| ## Local Development | ||
|
|
||
| ```bash | ||
| agentcore dev | ||
| ``` | ||
|
|
||
| For container agents, the dev server: | ||
|
|
||
| 1. Builds the container image and adds a dev layer with `uvicorn` | ||
| 2. Runs the container with your source directory volume-mounted at `/app` | ||
| 3. Enables hot reload via `uvicorn --reload` — code changes apply without rebuilding | ||
|
|
||
| AWS credentials are forwarded automatically (environment variables and `~/.aws` mounted read-only). | ||
|
|
||
| ## Packaging and Deployment | ||
|
|
||
| ```bash | ||
| agentcore package # Build image locally, validate < 1 GB | ||
| agentcore deploy -y --progress # Build via CodeBuild, push to ECR | ||
| ``` | ||
|
|
||
| Local packaging validates the image size (1 GB limit). If no local runtime is available, packaging is skipped and | ||
| deployment handles the build remotely. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| | Error | Fix | | ||
| | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | No container runtime found | Install Docker, Podman, or Finch | | ||
| | Runtime not ready | Docker: start Docker Desktop / `sudo systemctl start docker`. Podman: `podman machine start`. Finch: `finch vm init && finch vm start` | | ||
| | Dockerfile not found | Ensure `Dockerfile` exists in the agent's `codeLocation` directory | | ||
| | Image exceeds 1 GB | Use multi-stage builds, minimize packages, review `.dockerignore` | | ||
| | Build fails | Check `pyproject.toml` is valid; verify network access for dependency installation | | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If they do this for an existing Agent, they'll need a Dockerfile too right?
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes. good point. added a note