Add container deployment support for AgentCore Runtime (#334)

* Add container agent support

- Add Container as a build type for agents (create, add, dev, deploy, invoke, package)
- Add Dockerfile and dockerignore templates for Python container agents
- Add container dev server with Docker build, run, volume mount, and hot-reload
- Add container packaging with Docker runtime detection and validation
- Add Docker prerequisite check and runtime detection utility
- Wire userId (default: "default-user") through invoke flow for container auth
- Log userId in invoke request logs
- Upgrade vended @aws/agentcore-cdk to ^0.1.0-alpha.2
- Fix eslint require-await errors in codezip-dev-server and container packaging
- Simplify BaseRenderer to use copyAndRenderDir for container templates

* Fix CI: add missing buildType in test, revert CDK dep to alpha.1

- Add buildType: 'CodeZip' to schema-mapper test baseConfig (merge artifact)
- Revert @aws/agentcore-cdk to ^0.1.0-alpha.1 (alpha.2 not yet published;
  semver ^0.1.0-alpha.1 already covers alpha.2 once available)

* fix: sequential port checks to avoid bind race condition

* test: add unit tests for container agent support

* Address PR review feedback for container support

- Add port comments to Dockerfile EXPOSE directive
- Fix container runtime null check (info.runtime !== null)
- Use path.join() in getDockerfilePath for cross-platform support
- Use CONTAINER_RUNTIMES constant instead of hardcoded array
- Change dynamic import to static import in container-dev-server
- Check ports sequentially to avoid bind race conditions

* fix: defer load_model() to first invocation for Container build compatibility

In Container builds, the Python module loads at container startup before
any request context exists. API-key-based providers use @requires_api_key
which needs a workload access token only available within request context,
causing ValueError at import time.

Defer load_model() using lazy initialization in all affected templates:
- Strands: get_or_create_agent() singleton
- LangChain/LangGraph: get_or_create_model() singleton
- Google ADK / OpenAI Agents: ensure_credentials_loaded() guard

---------

Author: tejaskash

.gitignore

@@ -58,3 +58,5 @@ workdir-tmp/
 
 # Bun
 bun.lock
+
+.agentreview

src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -356,6 +356,8 @@ exports[`Assets Directory Snapshots > File listing > should match the expected f
   "cdk/package.json",
   "cdk/test/cdk.test.ts",
   "cdk/tsconfig.json",
+  "container/python/Dockerfile",
+  "container/python/dockerignore.template",
   "mcp/python-lambda/README.md",
   "mcp/python-lambda/handler.py",
   "mcp/python-lambda/pyproject.toml",
@@ -1580,12 +1582,18 @@ def add_numbers(a: int, b: int) -> int:
     return a + b
 
 
-# Set environment variables for model authentication
-load_model()
-
 # Get MCP Toolset
 mcp_toolset = [get_streamable_http_mcp_client()]
 
+_credentials_loaded = False
+
+def ensure_credentials_loaded():
+    global _credentials_loaded
+    if not _credentials_loaded:
+        load_model()
+        _credentials_loaded = True
+
+
 # Agent Definition
 agent = Agent(
     model=MODEL_ID,
@@ -1598,6 +1606,7 @@ agent = Agent(
 
 # Session and Runner
 async def setup_session_and_runner(user_id, session_id):
+    ensure_credentials_loaded()
     session_service = InMemorySessionService()
     session = await session_service.create_session(
         app_name=APP_NAME, user_id=user_id, session_id=session_id
@@ -1843,8 +1852,13 @@ from mcp_client.client import get_streamable_http_mcp_client
 app = BedrockAgentCoreApp()
 log = app.logger
 
-# Instantiate model
-llm = load_model()
+_llm = None
+
+def get_or_create_model():
+    global _llm
+    if _llm is None:
+        _llm = load_model()
+    return _llm
 
 
 # Define a simple function tool
@@ -1869,7 +1883,7 @@ async def invoke(payload, context):
     mcp_tools = await mcp_client.get_tools()
 
     # Define the agent using create_react_agent
-    graph = create_react_agent(llm, tools=mcp_tools + tools)
+    graph = create_react_agent(get_or_create_model(), tools=mcp_tools + tools)
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
@@ -2184,12 +2198,17 @@ from mcp_client.client import get_streamable_http_mcp_client
 app = BedrockAgentCoreApp()
 log = app.logger
 
-# Set environment variables for model authentication
-load_model()
-
 # Get MCP Server
 mcp_server = get_streamable_http_mcp_client()
 
+_credentials_loaded = False
+
+def ensure_credentials_loaded():
+    global _credentials_loaded
+    if not _credentials_loaded:
+        load_model()
+        _credentials_loaded = True
+
 
 # Define a simple function tool
 @function_tool
@@ -2200,6 +2219,7 @@ def add_numbers(a: int, b: int) -> int:
 
 # Define the agent execution
 async def main(query):
+    ensure_credentials_loaded()
     try:
         async with mcp_server as server:
             active_servers = [server] if server else []
@@ -2461,14 +2481,19 @@ def agent_factory():
     return get_or_create_agent
 get_or_create_agent = agent_factory()
 {{else}}
-# Create agent
-agent = Agent(
-    model=load_model(),
-    system_prompt="""
-        You are a helpful assistant. Use tools when appropriate.
-    """,
-    tools=tools+[mcp_client]
-)
+_agent = None
+
+def get_or_create_agent():
+    global _agent
+    if _agent is None:
+        _agent = Agent(
+            model=load_model(),
+            system_prompt="""
+                You are a helpful assistant. Use tools when appropriate.
+            """,
+            tools=tools+[mcp_client]
+        )
+    return _agent
 {{/if}}
 
 
@@ -2480,8 +2505,10 @@ async def invoke(payload, context):
     session_id = getattr(context, 'session_id', 'default-session')
     user_id = getattr(context, 'user_id', 'default-user')
     agent = get_or_create_agent(session_id, user_id)
-
+{{else}}
+    agent = get_or_create_agent()
 {{/if}}
+
     # Execute and format response
     stream = agent.stream_async(payload.get("prompt"))
 

src/assets/container/python/Dockerfile

@@ -0,0 +1,24 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+WORKDIR /app
+
+ENV UV_SYSTEM_PYTHON=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_NO_PROGRESS=1 \
+    PYTHONUNBUFFERED=1 \
+    DOCKER_CONTAINER=1
+
+COPY pyproject.toml uv.lock* ./
+RUN uv pip install -r pyproject.toml
+
+RUN useradd -m -u 1000 bedrock_agentcore
+USER bedrock_agentcore
+
+COPY . .
+
+# 8080: AgentCore runtime endpoint
+# 8000: Local dev server (uvicorn)
+# 9000: OpenTelemetry collector
+EXPOSE 8080 8000 9000
+
+CMD ["opentelemetry-instrument", "python", "-m", "{{entrypoint}}"]

src/assets/container/python/dockerignore.template

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# IDE
+.vscode/
+.idea/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# AgentCore build artifacts
+.agentcore/artifacts/
+*.zip

src/assets/python/googleadk/base/main.py

@@ -22,12 +22,18 @@ def add_numbers(a: int, b: int) -> int:
     return a + b
 
 
-# Set environment variables for model authentication
-load_model()
-
 # Get MCP Toolset
 mcp_toolset = [get_streamable_http_mcp_client()]
 
+_credentials_loaded = False
+
+def ensure_credentials_loaded():
+    global _credentials_loaded
+    if not _credentials_loaded:
+        load_model()
+        _credentials_loaded = True
+
+
 # Agent Definition
 agent = Agent(
     model=MODEL_ID,
@@ -40,6 +46,7 @@ def add_numbers(a: int, b: int) -> int:
 
 # Session and Runner
 async def setup_session_and_runner(user_id, session_id):
+    ensure_credentials_loaded()
     session_service = InMemorySessionService()
     session = await session_service.create_session(
         app_name=APP_NAME, user_id=user_id, session_id=session_id

src/assets/python/langchain_langgraph/base/main.py

@@ -9,8 +9,13 @@
 app = BedrockAgentCoreApp()
 log = app.logger
 
-# Instantiate model
-llm = load_model()
+_llm = None
+
+def get_or_create_model():
+    global _llm
+    if _llm is None:
+        _llm = load_model()
+    return _llm
 
 
 # Define a simple function tool
@@ -35,7 +40,7 @@ async def invoke(payload, context):
     mcp_tools = await mcp_client.get_tools()
 
     # Define the agent using create_react_agent
-    graph = create_react_agent(llm, tools=mcp_tools + tools)
+    graph = create_react_agent(get_or_create_model(), tools=mcp_tools + tools)
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")

src/assets/python/openaiagents/base/main.py

@@ -7,12 +7,17 @@
 app = BedrockAgentCoreApp()
 log = app.logger
 
-# Set environment variables for model authentication
-load_model()
-
 # Get MCP Server
 mcp_server = get_streamable_http_mcp_client()
 
+_credentials_loaded = False
+
+def ensure_credentials_loaded():
+    global _credentials_loaded
+    if not _credentials_loaded:
+        load_model()
+        _credentials_loaded = True
+
 
 # Define a simple function tool
 @function_tool
@@ -23,6 +28,7 @@ def add_numbers(a: int, b: int) -> int:
 
 # Define the agent execution
 async def main(query):
+    ensure_credentials_loaded()
     try:
         async with mcp_server as server:
             active_servers = [server] if server else []

src/assets/python/strands/base/main.py

@@ -42,14 +42,19 @@ def get_or_create_agent(session_id, user_id):
     return get_or_create_agent
 get_or_create_agent = agent_factory()
 {{else}}
-# Create agent
-agent = Agent(
-    model=load_model(),
-    system_prompt="""
-        You are a helpful assistant. Use tools when appropriate.
-    """,
-    tools=tools+[mcp_client]
-)
+_agent = None
+
+def get_or_create_agent():
+    global _agent
+    if _agent is None:
+        _agent = Agent(
+            model=load_model(),
+            system_prompt="""
+                You are a helpful assistant. Use tools when appropriate.
+            """,
+            tools=tools+[mcp_client]
+        )
+    return _agent
 {{/if}}
 
 
@@ -61,8 +66,10 @@ async def invoke(payload, context):
     session_id = getattr(context, 'session_id', 'default-session')
     user_id = getattr(context, 'user_id', 'default-user')
     agent = get_or_create_agent(session_id, user_id)
-
+{{else}}
+    agent = get_or_create_agent()
 {{/if}}
+
     # Execute and format response
     stream = agent.stream_async(payload.get("prompt"))
 

src/cli/aws/agentcore.ts

@@ -10,11 +10,16 @@ export interface SSELogger {
   logSSEEvent(rawLine: string): void;
 }
 
+/** Default user ID sent with invocations. Container agents require this to obtain workload access tokens. */
+export const DEFAULT_RUNTIME_USER_ID = 'default-user';
+
 export interface InvokeAgentRuntimeOptions {
   region: string;
   runtimeArn: string;
   payload: string;
   sessionId?: string;
+  /** User ID for the runtime invocation. Defaults to 'default-user'. Required for Container agents using identity providers. */
+  userId?: string;
   /** Optional logger for SSE event debugging */
   logger?: SSELogger;
 }
@@ -112,6 +117,7 @@ export async function invokeAgentRuntimeStreaming(options: InvokeAgentRuntimeOpt
     contentType: 'application/json',
     accept: 'application/json',
     runtimeSessionId: options.sessionId,
+    runtimeUserId: options.userId ?? DEFAULT_RUNTIME_USER_ID,
   });
 
   const response = await client.send(command);
@@ -207,6 +213,7 @@ export async function invokeAgentRuntime(options: InvokeAgentRuntimeOptions): Pr
     contentType: 'application/json',
     accept: 'application/json',
     runtimeSessionId: options.sessionId,
+    runtimeUserId: options.userId ?? DEFAULT_RUNTIME_USER_ID,
   });
 
   const response = await client.send(command);

src/cli/aws/index.ts

@@ -14,6 +14,7 @@ export {
   type GetAgentRuntimeStatusOptions,
 } from './agentcore-control';
 export {
+  DEFAULT_RUNTIME_USER_ID,
   invokeAgentRuntime,
   invokeAgentRuntimeStreaming,
   stopRuntimeSession,