docs: "Get started with the AgentCore CLI in TypeScript" tutorial is not runnable as written (broken Dockerfile + other inaccuracies)

[minorun365]

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

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

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:

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:

{
  "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):

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.