docs: "Get started with the AgentCore CLI in TypeScript" tutorial is not runnable as written (broken Dockerfile + other inaccuracies)
- Dominant language
- TypeScript
- Stars
- 283
- Forks
- 95
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 183
Description
### Description
First, apologies if this isn't the right place to report Amazon Bedrock AgentCore *documentation* issues (as opposed to the CLI tool itself) — please point me elsewhere if there's a better venue. I'm filing here because the doc in question is the official getting-started guide for this CLI, and prior documentation issues (e.g. #1100) have been tracked in this repo.
The TypeScript getting-started tutorial can't be followed end-to-end as written — the `Dockerfile` it has you create doesn't build, and a few other parts don't match current CLI behavior. Doc: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli-typescript.html
Problems, roughly in the order you hit them:
**1. Step 2 — `Dockerfile` builder stage: `COPY ..` is missing a space**
```dockerfile
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY .. # <-- single ".." token; should be `COPY . .`
RUN npm run build
```
`COPY ..` is one argument and Docker rejects it (`COPY requires at least two arguments, but only one was provided`). It should be `COPY . .`. (If the doc source actually has `COPY . .` and this is a rendering issue on the docs site, that's still worth fixing — it's what readers copy.)
**2. Step 2 — `Dockerfile` production stage: `useradd -m -u 1000 bedrock_agentcore` collides with the `node` user**
```dockerfile
FROM node:20-slim
...
RUN useradd -m -u 1000 bedrock_agentcore # <-- fails
USER bedrock_agentcore
```
`node:20-slim` (like every official `node` image) already ships a `node` user/group at UID/GID 1000, so this aborts with `useradd: UID 1000 is not unique`. The `RUN` step exits non-zero and the image build fails — surfaced through the CLI as "Container build failed", in both `agentcore dev` (local Docker build) and `agentcore deploy` (CodeBuild). This line looks copied from the Python getting-started Dockerfile (`python:3.x-slim` has no pre-existing UID 1000 user); the TypeScript variant doesn't appear to have been run end-to-end.
Fix: drop the explicit `-u 1000` so the OS assigns a free UID, or just `USER node` and remove `useradd` entirely since the base image already has a non-root user:
```dockerfile
RUN useradd -m bedrock_agentcore
```
**3. Step 4 — `agentcore dev` doesn't forward `AWS_REGION`, but the doc doesn't say so**
The doc says: "Your AWS credentials are forwarded automatically to the container." True for credentials, but `AWS_REGION` is not forwarded (and the active `~/.aws/config` profile isn't mounted either), so any agent that calls the AWS SDK without an explicit region fails locally — e.g. `region setting is missing` / `Could not load credentials ... region`. This affects the tutorial's own Strands/Bedrock example. The tutorial should either have `agentcore dev` forward the region, or tell users to set it — e.g. add `ENV AWS_REGION=us-west-2` to the `Dockerfile`, or `export AWS_REGION=...` before `agentcore dev`.
**4. Step 3 — the `agentcore.json` example is stale**
The doc shows:
```json
{
"name": "MyTsAgent",
"version": 1,
"agents": [
{ "type": "AgentCoreRuntime", "name": "TsAgent", "build": "Container", "entrypoint": "main.py", "codeLocation": "app/TsAgent/", "runtimeVersion": "PYTHON_3_12", "protocol": "HTTP", "networkMode": "PUBLIC" }
]
}
```
The current CLI generates a top-level `"runtimes": [ { "name": ..., "build": ..., "entrypoint": ..., "codeLocation": ..., "runtimeVersion": ..., "networkMode": ..., "protocol": ... } ]` array (no `agents` key, no `type` field), plus `"managedBy"`, `"tags"`, `"memories": []`, `"credentials": []`, etc. The example should match what the CLI actually writes.
**5. (minor) Templating placeholders leak into the rendered page**
Step 3: "Replace {{123456789012}} with your AWS account ID"; Common issues → "Port 8080 in use": "Replace {{PID}} with the process ID" — the `{{...}}` renders literally. (Ignore if that's just an artifact of how I scraped the page.)
### Steps to Reproduce
1. Follow https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli-typescript.html through Step 2 — `agentcore create --no-agent`, `agentcore add agent ... --build Container --language TypeScript ...`, and create the `Dockerfile` exactly as shown.
2. Run `agentcore deploy` (or `agentcore dev`).
3. The container build fails — first on `COPY ..` (`COPY requires at least two arguments`); fix that and it then fails on `useradd: UID 1000 is not unique`.
4. After fixing the Dockerfile, run `agentcore dev` with an AWS profile whose region is only set in `~/.aws/config` (no `AWS_REGION` env var) and an agent that uses the AWS SDK → it fails locally with a "region is missing" error.
### Expected Behavior
Following the TypeScript getting-started tutorial verbatim produces a container that builds, runs locally with `agentcore dev`, and deploys with `agentcore deploy`; and the `agentcore.json` example matches what the CLI generates.
### Actual Behavior
The tutorial's `Dockerfile` doesn't build (`COPY ..`, then `useradd -u 1000`); even after fixing it, `agentcore dev` fails for AWS-SDK agents because `AWS_REGION` isn't forwarded and the doc doesn't mention it; and the `agentcore.json` example shows an older schema (`agents` / `type: AgentCoreRuntime`) that the CLI no longer produces.
### CLI Version
Latest `@aws/agentcore` npm release as of 2026-05-12 (these are docs issues, not version-dependent).
### Operating System
macOS
### Additional Context
Corrected `Dockerfile` I verified end-to-end — `agentcore deploy` + `agentcore invoke` succeed for a TypeScript Container agent (I used Mastra + `@ai-sdk/amazon-bedrock`, but the framework is irrelevant; the tutorial's own Strands example hits the same Dockerfile failures):
```dockerfile
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20-slim
WORKDIR /app
ENV AWS_REGION=us-west-2 # or export before `agentcore dev` / pass at deploy
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./
RUN useradd -m bedrock_agentcore
USER bedrock_agentcore
EXPOSE 8080 8000 9000
CMD ["node", "--require", "@opentelemetry/auto-instrumentations-node/register", "dist/agent.js"]
```
Out of scope for this docs issue, but related: `bedrock-agentcore@0.2.x`'s runtime returns an opaque HTTP 500 when the invocation handler throws or input fails schema validation, which makes the failures above hard to diagnose from the agent inspector (you have to read `docker logs` / `agentcore logs`). I can file that against the SDK separately — and/or an enhancement here for `agentcore add agent --language TypeScript` to scaffold a working Dockerfile/project so users don't hand-copy from the docs at all — if either would be useful.
Contributor guide
Assessment
This issue has not been assessed yet.