From ed194a9b73f8412736be88efb672255f21814533 Mon Sep 17 00:00:00 2001 From: Tejas Kashinath Date: Thu, 19 Feb 2026 12:04:29 -0500 Subject: [PATCH 1/2] docs: update AGENTS.md and llm-context for container support Document container build type, dev server architecture, packaging pipeline, and template rendering across all AGENTS.md files. Add missing modelProvider field to llm-compacted agentcore.ts. --- AGENTS.md | 13 ++++++++++--- src/assets/AGENTS.md | 28 ++++++++++++++++++++++++--- src/assets/agents/AGENTS.md | 15 ++++++++++++-- src/cli/AGENTS.md | 10 ++++++++++ src/cli/templates/AGENTS.md | 13 +++++++++++++ src/lib/AGENTS.md | 13 ++++++++++--- src/schema/llm-compacted/agentcore.ts | 2 ++ 7 files changed, 83 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b1993ac6..70388a25 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,18 +27,25 @@ Note: CDK L3 constructs are in a separate package `@aws/agentcore-cdk`. - `remove` - Remove resources (agent, memory, identity, target, all) - `deploy` - Deploy infrastructure to AWS - `status` - Check deployment status -- `dev` - Local development server +- `dev` - Local development server (CodeZip: uvicorn with hot-reload; Container: Docker build + run with volume mount) - `invoke` - Invoke agents (local or deployed) -- `package` - Package agent artifacts without deploying +- `package` - Package agent artifacts without deploying (zip for CodeZip, container image build for Container) - `validate` - Validate configuration files - `update` - Check for CLI updates - `help` - Display help information ### Agent Types -- **Template agents**: Created from framework templates (Strands, LangChain_LangGraph, GoogleADK, OpenAIAgents) +- **Template agents**: Created from framework templates (Strands, LangChain_LangGraph, CrewAI, GoogleADK, OpenAIAgents, + AutoGen) - **BYO agents**: Bring your own code with `agentcore add agent --type byo` +### Build Types + +- **CodeZip**: Python source is packaged into a zip artifact and deployed to AgentCore Runtime (default) +- **Container**: Agent is built as a Docker container image, deployed via ECR and CodeBuild. Requires a `Dockerfile` in + the agent's code directory. Supported container runtimes: Docker, Podman, Finch. + ### Coming Soon - MCP gateway and tool support (`add gateway`, `add mcp-tool`) - currently hidden diff --git a/src/assets/AGENTS.md b/src/assets/AGENTS.md index 0ae9479e..04441afd 100644 --- a/src/assets/AGENTS.md +++ b/src/assets/AGENTS.md @@ -3,14 +3,36 @@ This directory stores: - Template assets for agents written in different Languages, SDKs and having different configurations +- Container templates (`container/python/`) with `Dockerfile` and `.dockerignore` for Container build agents -The rendering logic is rooted in the `AgentEnvSpec` and must ALWAYS respect the configuration in the Spec +### Directory Layout + +``` +assets/ +├── python/ # Framework templates (one per SDK) +│ ├── strands/ +│ ├── langchain_langgraph/ +│ ├── crewai/ +│ ├── googleadk/ +│ ├── openaiagents/ +│ └── autogen/ +├── container/ # Container build templates +│ └── python/ +│ ├── Dockerfile +│ └── dockerignore.template +└── agents/ # AGENTS.md vended to user projects +``` + +The rendering logic is rooted in the `AgentEnvSpec` and must ALWAYS respect the configuration in the Spec. + +For Container builds, `BaseRenderer.render()` automatically copies the `container//` templates (Dockerfile, +.dockerignore) into the agent directory when `buildType === 'Container'`. ## Guidance for template changes - Always make sure the templates are as close to working code as possible - AVOID as much as possible using any conditionals within the templates -# How to use the assets in this directory +## How to use the assets in this directory -- These assets are rendered by the CLI's template renderer in `packages/agentcore-cli/src/templates`. +- These assets are rendered by the CLI's template renderer in `src/cli/templates/`. diff --git a/src/assets/agents/AGENTS.md b/src/assets/agents/AGENTS.md index 35f1b7d2..3be3654f 100644 --- a/src/assets/agents/AGENTS.md +++ b/src/assets/agents/AGENTS.md @@ -60,21 +60,32 @@ file maps to a JSON config file and includes validation constraints as comments. ### Common Enum Values -- **BuildType**: `'CodeZip'` +- **BuildType**: `'CodeZip'` | `'Container'` - **NetworkMode**: `'PUBLIC'` - **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` - **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` +### Build Types + +- **CodeZip**: Python source is packaged as a zip artifact and deployed directly to AgentCore Runtime. +- **Container**: Agent code is built as a Docker container image. Requires a `Dockerfile` in the agent's `codeLocation` + directory. At deploy time, the source is uploaded to S3, built in CodeBuild (ARM64), pushed to a per-agent ECR + repository, and the container URI is provided to the AgentCore Runtime. For local development (`agentcore dev`), the + container is built and run locally with volume-mounted hot-reload. + ### Supported Frameworks (for template agents) - **Strands** - Works with Bedrock, Anthropic, OpenAI, Gemini - **LangChain_LangGraph** - Works with Bedrock, Anthropic, OpenAI, Gemini +- **CrewAI** - Works with Bedrock, Anthropic, OpenAI, Gemini - **GoogleADK** - Gemini only - **OpenAIAgents** - OpenAI only +- **AutoGen** - Works with Bedrock, Anthropic, OpenAI, Gemini ### Specific Context -Directory pathing to local projects is required for runtimes. Only Python offers a zip based direct code deploy option. +Directory pathing to local projects is required for runtimes. Both CodeZip (Python zip) and Container (Docker image) +deployment options are available. ## Deployment diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index f606eea7..d340b1a0 100644 --- a/src/cli/AGENTS.md +++ b/src/cli/AGENTS.md @@ -65,6 +65,16 @@ appropriate to test the relevant surface area. If start up issues are encountered, read the console error to troubleshoot bugs and update the harness. +## Dev Server Architecture + +The `dev` command uses a strategy pattern with a `DevServer` base class and two implementations: + +- **CodeZipDevServer**: Runs uvicorn locally with Python venv hot-reload +- **ContainerDevServer**: Builds and runs a Docker container with volume mount for hot-reload. Detects + Docker/Podman/Finch via the `detectContainerRuntime()` utility. + +The server selection is based on `agent.build` (`CodeZip` or `Container`). + ## Commands Directory Structure Commands live in `commands/`. Each command has its own directory with an `index.ts` barrel file and a file called diff --git a/src/cli/templates/AGENTS.md b/src/cli/templates/AGENTS.md index 74644eee..8466162c 100644 --- a/src/cli/templates/AGENTS.md +++ b/src/cli/templates/AGENTS.md @@ -6,6 +6,19 @@ Template **assets** live in the `assets/` directory at the repository root. The rendering logic is rooted in the `AgentEnvSpec` and must ALWAYS respect the configuration in the Spec. +### Rendering Pipeline + +1. `createRenderer()` selects a renderer based on framework/language +2. `BaseRenderer.render()` copies and renders the framework base template +3. If `hasMemory`, capability templates are layered on top +4. If `buildType === 'Container'`, the container templates (`Dockerfile`, `.dockerignore`) from + `assets/container//` are copied into the agent directory + +### LLM Context Files + +`schema-assets.ts` imports llm-compacted TypeScript files that are embedded at build time via the esbuild text-loader +plugin. `CDKRenderer.writeLlmContext()` writes these to `agentcore/.llm-context/` during project initialization. + ## Guidance for template changes - Always make sure the templates are as close to working code as possible diff --git a/src/lib/AGENTS.md b/src/lib/AGENTS.md index 4f825e41..9a792543 100644 --- a/src/lib/AGENTS.md +++ b/src/lib/AGENTS.md @@ -5,9 +5,16 @@ module serves the important goal of making sure that the CDK implementations don ## Functions -**Packaging**: Installing dependencies and then producing a `.zip` file artifact that is ready to be deployed on -AgentCore runtime. This is surfaced as a modular function in the CLI and used as a bundling CDK asset in the CDK. A core -problem this functionality solves is attempting to produce an artifact that can run on ARM64 arch hardware. +**Packaging**: Producing deployment artifacts for AgentCore runtimes. Two packagers are available: + +- **PythonPackager / NodePackager** (CodeZip): Installs dependencies and produces a `.zip` artifact targeting ARM64 + architecture. +- **ContainerPackager** (Container): Validates the Dockerfile exists, detects a local container runtime + (Docker/Podman/Finch), builds the image locally, and validates the 1GB size limit. If no local runtime is available, + the local build is skipped (deploy uses CodeBuild). + +Container constants (`CONTAINER_RUNTIMES`, `DOCKERFILE_NAME`, `CONTAINER_INTERNAL_PORT`) and the `ContainerRuntime` type +are in `lib/constants.ts`. **ConfigIO**: This module defines utilities to read and write configs which satisfy schemas to the local file system. Both the CLI and the CDK require this functionality. diff --git a/src/schema/llm-compacted/agentcore.ts b/src/schema/llm-compacted/agentcore.ts index 15eddd66..382fda92 100644 --- a/src/schema/llm-compacted/agentcore.ts +++ b/src/schema/llm-compacted/agentcore.ts @@ -28,6 +28,7 @@ type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22'; type RuntimeVersion = PythonRuntime | NodeRuntime; type NetworkMode = 'PUBLIC' | 'PRIVATE'; type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE'; +type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic'; // ───────────────────────────────────────────────────────────────────────────── // AGENT @@ -43,6 +44,7 @@ interface AgentEnvSpec { envVars?: EnvVar[]; networkMode?: NetworkMode; // default 'PUBLIC' instrumentation?: Instrumentation; // OTel settings + modelProvider?: ModelProvider; // Model provider used by this agent } interface Instrumentation { From b29f2a5c1791e23182c2b3783c1a48c4df52af3c Mon Sep 17 00:00:00 2001 From: Tejas Kashinath Date: Thu, 19 Feb 2026 12:13:03 -0500 Subject: [PATCH 2/2] test: update asset snapshot tests for AGENTS.md changes --- .../assets.snapshot.test.ts.snap | 43 ++++++++++++++++--- 1 file changed, 38 insertions(+), 5 deletions(-) diff --git a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap index 3bc9d532..ad79babe 100644 --- a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap +++ b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap @@ -2752,17 +2752,39 @@ exports[`Assets Directory Snapshots > Root-level assets > AGENTS.md should match This directory stores: - Template assets for agents written in different Languages, SDKs and having different configurations +- Container templates (\`container/python/\`) with \`Dockerfile\` and \`.dockerignore\` for Container build agents -The rendering logic is rooted in the \`AgentEnvSpec\` and must ALWAYS respect the configuration in the Spec +### Directory Layout + +\`\`\` +assets/ +├── python/ # Framework templates (one per SDK) +│ ├── strands/ +│ ├── langchain_langgraph/ +│ ├── crewai/ +│ ├── googleadk/ +│ ├── openaiagents/ +│ └── autogen/ +├── container/ # Container build templates +│ └── python/ +│ ├── Dockerfile +│ └── dockerignore.template +└── agents/ # AGENTS.md vended to user projects +\`\`\` + +The rendering logic is rooted in the \`AgentEnvSpec\` and must ALWAYS respect the configuration in the Spec. + +For Container builds, \`BaseRenderer.render()\` automatically copies the \`container//\` templates (Dockerfile, +.dockerignore) into the agent directory when \`buildType === 'Container'\`. ## Guidance for template changes - Always make sure the templates are as close to working code as possible - AVOID as much as possible using any conditionals within the templates -# How to use the assets in this directory +## How to use the assets in this directory -- These assets are rendered by the CLI's template renderer in \`packages/agentcore-cli/src/templates\`. +- These assets are rendered by the CLI's template renderer in \`src/cli/templates/\`. " `; @@ -2912,21 +2934,32 @@ file maps to a JSON config file and includes validation constraints as comments. ### Common Enum Values -- **BuildType**: \`'CodeZip'\` +- **BuildType**: \`'CodeZip'\` | \`'Container'\` - **NetworkMode**: \`'PUBLIC'\` - **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\` - **MemoryStrategyType**: \`'SEMANTIC'\` | \`'SUMMARIZATION'\` | \`'USER_PREFERENCE'\` +### Build Types + +- **CodeZip**: Python source is packaged as a zip artifact and deployed directly to AgentCore Runtime. +- **Container**: Agent code is built as a Docker container image. Requires a \`Dockerfile\` in the agent's \`codeLocation\` + directory. At deploy time, the source is uploaded to S3, built in CodeBuild (ARM64), pushed to a per-agent ECR + repository, and the container URI is provided to the AgentCore Runtime. For local development (\`agentcore dev\`), the + container is built and run locally with volume-mounted hot-reload. + ### Supported Frameworks (for template agents) - **Strands** - Works with Bedrock, Anthropic, OpenAI, Gemini - **LangChain_LangGraph** - Works with Bedrock, Anthropic, OpenAI, Gemini +- **CrewAI** - Works with Bedrock, Anthropic, OpenAI, Gemini - **GoogleADK** - Gemini only - **OpenAIAgents** - OpenAI only +- **AutoGen** - Works with Bedrock, Anthropic, OpenAI, Gemini ### Specific Context -Directory pathing to local projects is required for runtimes. Only Python offers a zip based direct code deploy option. +Directory pathing to local projects is required for runtimes. Both CodeZip (Python zip) and Container (Docker image) +deployment options are available. ## Deployment