Skip to content

Commit 6ed4411

Browse files
notgitikanotgitika
authored
docs: add container build documentation (#340)
* docs: add container build documentation * docs: add note about converting existing CodeZip agents
1 parent 0a1574a commit 6ed4411

File tree

3 files changed

+140
-27
lines changed

3 files changed

+140
-27
lines changed

‎docs/commands.md‎

Lines changed: 29 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -30,21 +30,22 @@ agentcore create --name MyProject --no-agent
3030
agentcore create --name MyProject --defaults --dry-run
3131
```
3232

33-
| Flag | Description |
34-
| ---------------------- | ------------------------------------------------------------- |
35-
| `--name <name>` | Project name (alphanumeric, max 23 chars) |
36-
| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) |
37-
| `--no-agent` | Skip agent creation |
38-
| `--language <lang>` | `Python` or `TypeScript` |
39-
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` |
40-
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
41-
| `--api-key <key>` | API key for non-Bedrock providers |
42-
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` |
43-
| `--output-dir <dir>` | Output directory |
44-
| `--skip-git` | Skip git initialization |
45-
| `--skip-python-setup` | Skip venv setup |
46-
| `--dry-run` | Preview without creating |
47-
| `--json` | JSON output |
33+
| Flag | Description |
34+
| ---------------------- | -------------------------------------------------------------------------------- |
35+
| `--name <name>` | Project name (alphanumeric, max 23 chars) |
36+
| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) |
37+
| `--no-agent` | Skip agent creation |
38+
| `--language <lang>` | `Python` or `TypeScript` |
39+
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` |
40+
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
41+
| `--build <type>` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) |
42+
| `--api-key <key>` | API key for non-Bedrock providers |
43+
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` |
44+
| `--output-dir <dir>` | Output directory |
45+
| `--skip-git` | Skip git initialization |
46+
| `--skip-python-setup` | Skip venv setup |
47+
| `--dry-run` | Preview without creating |
48+
| `--json` | JSON output |
4849

4950
### deploy
5051

@@ -117,18 +118,19 @@ agentcore add agent \
117118
--model-provider Bedrock
118119
```
119120

120-
| Flag | Description |
121-
| ------------------------ | ------------------------------------- |
122-
| `--name <name>` | Agent name |
123-
| `--type <type>` | `create` (default) or `byo` |
124-
| `--language <lang>` | `Python`, `TypeScript`, `Other` (BYO) |
125-
| `--framework <fw>` | Agent framework |
126-
| `--model-provider <p>` | Model provider |
127-
| `--api-key <key>` | API key for non-Bedrock |
128-
| `--memory <opt>` | Memory option (create only) |
129-
| `--code-location <path>` | Code path (BYO only) |
130-
| `--entrypoint <file>` | Entry file (BYO only) |
131-
| `--json` | JSON output |
121+
| Flag | Description |
122+
| ------------------------ | -------------------------------------------------------------------------------- |
123+
| `--name <name>` | Agent name |
124+
| `--type <type>` | `create` (default) or `byo` |
125+
| `--build <type>` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) |
126+
| `--language <lang>` | `Python`, `TypeScript`, `Other` (BYO) |
127+
| `--framework <fw>` | Agent framework |
128+
| `--model-provider <p>` | Model provider |
129+
| `--api-key <key>` | API key for non-Bedrock |
130+
| `--memory <opt>` | Memory option (create only) |
131+
| `--code-location <path>` | Code path (BYO only) |
132+
| `--entrypoint <file>` | Entry file (BYO only) |
133+
| `--json` | JSON output |
132134

133135
### add memory
134136

‎docs/container-builds.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Container Builds
2+
3+
Container builds package your agent as a Docker container image instead of a code ZIP. Use containers when you need
4+
system-level dependencies, custom native libraries, or full control over the runtime environment.
5+
6+
## Prerequisites
7+
8+
A container runtime is required for local development (`agentcore dev`) and packaging (`agentcore package`). Supported
9+
runtimes:
10+
11+
1. [Docker](https://docker.com)
12+
2. [Podman](https://podman.io)
13+
3. [Finch](https://runfinch.com)
14+
15+
The CLI auto-detects the first working runtime in the order listed above. If multiple are installed, the
16+
highest-priority one wins.
17+
18+
> A local runtime is **not** required for `agentcore deploy` — AWS CodeBuild builds the image remotely.
19+
20+
## Getting Started
21+
22+
```bash
23+
# New project with container build
24+
agentcore create --name MyProject --build Container
25+
26+
# Add container agent to existing project
27+
agentcore add agent --name MyAgent --build Container --framework Strands --model-provider Bedrock
28+
```
29+
30+
Both commands generate a `Dockerfile` and `.dockerignore` in the agent's code directory:
31+
32+
```
33+
app/MyAgent/
34+
├── Dockerfile
35+
├── .dockerignore
36+
├── pyproject.toml
37+
└── main.py
38+
```
39+
40+
## Generated Dockerfile
41+
42+
The template uses `ghcr.io/astral-sh/uv:python3.12-bookworm-slim` as the base image with these design choices:
43+
44+
- **Layer caching**: Dependencies (`pyproject.toml`) are installed before copying application code
45+
- **Non-root**: Runs as `bedrock_agentcore` (UID 1000)
46+
- **Observability**: Default CMD wraps the agent with `opentelemetry-instrument`
47+
- **Fast installs**: Uses `uv pip install` for dependency resolution
48+
49+
You can customize the Dockerfile freely — add system packages, change the base image, or use multi-stage builds.
50+
51+
## Configuration
52+
53+
In `agentcore.json`, set `"build": "Container"`:
54+
55+
```json
56+
{
57+
"type": "AgentCoreRuntime",
58+
"name": "MyAgent",
59+
"build": "Container",
60+
"entrypoint": "main.py",
61+
"codeLocation": "app/MyAgent/",
62+
"runtimeVersion": "PYTHON_3_12"
63+
}
64+
```
65+
66+
All other fields work the same as CodeZip agents.
67+
68+
> **Converting an existing CodeZip agent?** Changing the `build` field in `agentcore.json` alone is not enough — you
69+
> must also add a `Dockerfile` and `.dockerignore` to the agent's code directory. The easiest way is to create a
70+
> throwaway container agent with `agentcore add agent --build Container` and copy the generated files.
71+
72+
## Local Development
73+
74+
```bash
75+
agentcore dev
76+
```
77+
78+
For container agents, the dev server:
79+
80+
1. Builds the container image and adds a dev layer with `uvicorn`
81+
2. Runs the container with your source directory volume-mounted at `/app`
82+
3. Enables hot reload via `uvicorn --reload` — code changes apply without rebuilding
83+
84+
AWS credentials are forwarded automatically (environment variables and `~/.aws` mounted read-only).
85+
86+
## Packaging and Deployment
87+
88+
```bash
89+
agentcore package # Build image locally, validate < 1 GB
90+
agentcore deploy -y --progress # Build via CodeBuild, push to ECR
91+
```
92+
93+
Local packaging validates the image size (1 GB limit). If no local runtime is available, packaging is skipped and
94+
deployment handles the build remotely.
95+
96+
## Troubleshooting
97+
98+
| Error | Fix |
99+
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
100+
| No container runtime found | Install Docker, Podman, or Finch |
101+
| Runtime not ready | Docker: start Docker Desktop / `sudo systemctl start docker`. Podman: `podman machine start`. Finch: `finch vm init && finch vm start` |
102+
| Dockerfile not found | Ensure `Dockerfile` exists in the agent's `codeLocation` directory |
103+
| Image exceeds 1 GB | Use multi-stage builds, minimize packages, review `.dockerignore` |
104+
| Build fails | Check `pyproject.toml` is valid; verify network access for dependency installation |

‎docs/local-development.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,13 @@ uv sync
9595
The dev server watches for file changes and automatically reloads. Edit your agent code and the changes take effect
9696
immediately.
9797

98+
### Container Agents
99+
100+
For container agents, the dev server builds a Docker image and runs it with your source directory mounted as a volume.
101+
Changes to your code are picked up by uvicorn's `--reload` inside the container — no image rebuild needed.
102+
103+
See [Container Builds](container-builds.md) for full details on container development.
104+
98105
## Dev vs Deployed Behavior
99106

100107
| Aspect | Local Dev | Deployed |

0 commit comments

Comments
 (0)