From 1a010293541ca8cffe3992e24970d45814d68703 Mon Sep 17 00:00:00 2001 From: notgitika Date: Wed, 18 Feb 2026 16:43:40 -0500 Subject: [PATCH 1/2] docs: add container build documentation --- docs/commands.md | 56 +++++++++++---------- docs/container-builds.md | 100 ++++++++++++++++++++++++++++++++++++++ docs/local-development.md | 7 +++ 3 files changed, 136 insertions(+), 27 deletions(-) create mode 100644 docs/container-builds.md diff --git a/docs/commands.md b/docs/commands.md index e841186b..87a3e4b9 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -30,21 +30,22 @@ agentcore create --name MyProject --no-agent agentcore create --name MyProject --defaults --dry-run ``` -| Flag | Description | -| ---------------------- | ------------------------------------------------------------- | -| `--name ` | Project name (alphanumeric, max 23 chars) | -| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) | -| `--no-agent` | Skip agent creation | -| `--language ` | `Python` or `TypeScript` | -| `--framework ` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` | -| `--model-provider

` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` | -| `--api-key ` | API key for non-Bedrock providers | -| `--memory ` | `none`, `shortTerm`, `longAndShortTerm` | -| `--output-dir

` | Output directory | -| `--skip-git` | Skip git initialization | -| `--skip-python-setup` | Skip venv setup | -| `--dry-run` | Preview without creating | -| `--json` | JSON output | +| Flag | Description | +| ---------------------- | -------------------------------------------------------------------------------- | +| `--name ` | Project name (alphanumeric, max 23 chars) | +| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) | +| `--no-agent` | Skip agent creation | +| `--language ` | `Python` or `TypeScript` | +| `--framework ` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` | +| `--model-provider

` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` | +| `--build ` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) | +| `--api-key ` | API key for non-Bedrock providers | +| `--memory ` | `none`, `shortTerm`, `longAndShortTerm` | +| `--output-dir

` | Output directory | +| `--skip-git` | Skip git initialization | +| `--skip-python-setup` | Skip venv setup | +| `--dry-run` | Preview without creating | +| `--json` | JSON output | ### deploy @@ -117,18 +118,19 @@ agentcore add agent \ --model-provider Bedrock ``` -| Flag | Description | -| ------------------------ | ------------------------------------- | -| `--name ` | Agent name | -| `--type ` | `create` (default) or `byo` | -| `--language ` | `Python`, `TypeScript`, `Other` (BYO) | -| `--framework ` | Agent framework | -| `--model-provider

` | Model provider | -| `--api-key ` | API key for non-Bedrock | -| `--memory ` | Memory option (create only) | -| `--code-location ` | Code path (BYO only) | -| `--entrypoint ` | Entry file (BYO only) | -| `--json` | JSON output | +| Flag | Description | +| ------------------------ | -------------------------------------------------------------------------------- | +| `--name ` | Agent name | +| `--type ` | `create` (default) or `byo` | +| `--build ` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) | +| `--language ` | `Python`, `TypeScript`, `Other` (BYO) | +| `--framework ` | Agent framework | +| `--model-provider

` | Model provider | +| `--api-key ` | API key for non-Bedrock | +| `--memory ` | Memory option (create only) | +| `--code-location ` | Code path (BYO only) | +| `--entrypoint ` | Entry file (BYO only) | +| `--json` | JSON output | ### add memory diff --git a/docs/container-builds.md b/docs/container-builds.md new file mode 100644 index 00000000..51ba3440 --- /dev/null +++ b/docs/container-builds.md @@ -0,0 +1,100 @@ +# 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. + +## 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 | diff --git a/docs/local-development.md b/docs/local-development.md index 9a8ba1d0..42b4e5f4 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -95,6 +95,13 @@ uv sync The dev server watches for file changes and automatically reloads. Edit your agent code and the changes take effect immediately. +### Container Agents + +For container agents, the dev server builds a Docker image and runs it with your source directory mounted as a volume. +Changes to your code are picked up by uvicorn's `--reload` inside the container — no image rebuild needed. + +See [Container Builds](container-builds.md) for full details on container development. + ## Dev vs Deployed Behavior | Aspect | Local Dev | Deployed | From 8dc08bd2908b51e77768d8842f5ffb37ca667d48 Mon Sep 17 00:00:00 2001 From: notgitika Date: Wed, 18 Feb 2026 17:44:55 -0500 Subject: [PATCH 2/2] docs: add note about converting existing CodeZip agents --- docs/container-builds.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/container-builds.md b/docs/container-builds.md index 51ba3440..de4e2007 100644 --- a/docs/container-builds.md +++ b/docs/container-builds.md @@ -65,6 +65,10 @@ In `agentcore.json`, set `"build": "Container"`: 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