Merge pull request #2 from damc-dev/claude/review-agentcore-cli-migration-TkwBW

Update README for @aws/agentcore npm CLI migration

Replace all references to the old pip-based CLI (agentcore launch,
.bedrock_agentcore.yaml, yq, uv run agentcore) with the new npm CLI
(agentcore deploy, agentcore.json, agentcore dev). Add CDK bootstrap
prerequisite and updated IAM permissions. Update project structure,
local dev workflow, and adding-new-agent instructions.

https://claude.ai/code/session_01G2hszc4Xx3t7JsaJr9G4qf

Author: damc-dev

README.md

@@ -8,7 +8,6 @@ Every commit to `main` automatically:
 - 🚀 **Deploys a new version** of each agent to AWS Bedrock
 - 🏗️ **Builds and pushes** Docker images to Amazon ECR
 - 📦 **Tracks deployment history** via timestamped artifacts
-- ⚡ **Runs in parallel** for multi-agent deployments
 
 **No manual intervention required.** Push your code, and your agents are live in minutes.
 
@@ -23,9 +22,7 @@ git push origin main
       ↓
 GitHub Actions detects the push
       ↓
-Workflow extracts all agents from .bedrock_agentcore.yaml
-      ↓
-Parallel deployment begins for each agent
+AWS credentials configured via OIDC
       ↓
 Docker image built → pushed to ECR → deployed to Bedrock
       ↓
@@ -38,29 +35,34 @@ The deployment triggers on:
 
 ### Deployment Architecture
 
-The GitHub Actions workflow ([.github/workflows/deploy-agent.yml](.github/workflows/deploy-agent.yml)) uses a matrix strategy to deploy multiple agents efficiently:
+The GitHub Actions workflow ([.github/workflows/deploy-agent.yml](.github/workflows/deploy-agent.yml)) uses the `@aws/agentcore` npm CLI backed by AWS CDK:
 
-**Setup Job:**
-1. Extracts all agent names from `.bedrock_agentcore.yaml` using `yq`
-2. Installs Python and `uv` package manager
-3. Installs dependencies once (`uv sync`)
-4. Caches the environment for reuse
+1. Checks out code
+2. Installs Node.js and `@aws/agentcore` CLI
+3. Installs `uv` (required by the agentcore CLI for Python agents)
+4. Configures AWS credentials via OIDC
+5. Runs `agentcore deploy -y` which builds the Docker image, pushes to ECR, and deploys to Bedrock AgentCore
 
-**Deploy Jobs (parallel):**
-1. Restores the cached environment
-2. Configures AWS credentials
-3. Runs `agentcore launch --agent {agent-name}` for each agent
-4. Saves agent-specific `.bedrock_agentcore.yaml` as an artifact
+### Setup Requirements
 
-This approach eliminates redundant dependency installation, significantly speeding up multi-agent deployments.
+#### Prerequisites
 
-### Setup Requirements
+- Node.js 20+
+- [uv](https://github.com/astral-sh/uv) package manager
+- AWS account with CDK bootstrapped in your target region
 
-#### AWS Configuration
+#### CDK Bootstrap (one-time per account/region)
 
-You need to configure AWS authentication for GitHub Actions. Two options:
+The `@aws/agentcore` CLI uses AWS CDK internally. Before the first deploy, bootstrap your account:
 
-**Option 1: OIDC (Recommended)**
+```bash
+npm install -g @aws/agentcore
+npx cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1
+```
+
+#### AWS Configuration
+
+Configure AWS authentication for GitHub Actions using OIDC:
 
 1. Create an IAM OIDC identity provider for GitHub Actions:
    ```
@@ -94,32 +96,25 @@ You need to configure AWS authentication for GitHub Actions. Two options:
    - Amazon ECR (push images)
    - AWS CodeBuild (trigger builds)
    - Amazon Bedrock AgentCore (deploy agent)
+   - AWS CloudFormation (CDK stack management)
+   - `sts:AssumeRole` for CDK bootstrap roles (`cdk-hnb659fds-*`)
 
 4. Add the role ARN as a GitHub secret: `AWS_ROLE_ARN`
 
-**Option 2: Access Keys**
-
-1. Create an IAM user with programmatic access
-2. Attach necessary permissions (same as above)
-3. Add GitHub secrets:
-   - `AWS_ACCESS_KEY_ID`
-   - `AWS_SECRET_ACCESS_KEY`
-
 ### Manual Deployment
 
-To deploy a specific agent:
-
 ```bash
-uv sync
-uv run agentcore launch --agent <agent-name>
+npm install -g @aws/agentcore
+agentcore deploy -y
 ```
 
 ## Development
 
 ### Prerequisites
 
-- Python 3.12+
+- Python 3.13+
 - [uv](https://github.com/astral-sh/uv) package manager
+- Node.js 20+ and `@aws/agentcore` CLI
 - AWS credentials configured
 
 ### Local Setup
@@ -128,20 +123,21 @@ uv run agentcore launch --agent <agent-name>
 # Install uv
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# Install dependencies
+# Install Python dependencies
 uv sync
+
+# Install agentcore CLI
+npm install -g @aws/agentcore
 ```
 
-### Local Agent Run
+### Local Agent Development
 
 ```bash
-# Run the agent locally (if applicable)
-uv run python agent.py
+# Run the agent locally with a live reload server
+agentcore dev
 ```
 
-### Local Invocation
-You can invoke the agent locally for testing:
-
+Then in another terminal:
 ```bash
 curl -X POST http://localhost:8080/invocations \
   -H "Content-Type: application/json" \
@@ -150,55 +146,48 @@ curl -X POST http://localhost:8080/invocations \
 
 ### Adding a New Agent
 
-Adding a new agent is simple and automatically deployed:
-
-```bash
-# Configure a new agent interactively
-uv run agentcore configure --agent <new-agent-name>
-
-# Commit and push
-git add .bedrock_agentcore.yaml
-git commit -m "Add new agent"
-git push origin main
-```
-
-**What happens next:**
-1. Configure command updates `.bedrock_agentcore.yaml` with your new agent
-2. Push to `main` triggers the deployment workflow
-3. Workflow automatically detects the new agent
-4. New agent is built and deployed alongside existing agents in parallel
-5. Your new agent is live! 🎉
-
-**Example:**
-```bash
-# Add a new agent called "summarizer_agent"
-uv run agentcore configure --entrypoint summarizer_agent.py
-
-# Commit and push to deploy
-git add .bedrock_agentcore.yaml
-git commit -m "Add summarizer agent"
-git push origin main
+1. Add a new entry to `agentcore/agentcore.json`:
+   ```json
+   {
+     "type": "AgentCoreRuntime",
+     "name": "my-new-agent",
+     "build": "Container",
+     "entrypoint": "my_agent.py",
+     "codeLocation": ".",
+     "runtimeVersion": "PYTHON_3_13"
+   }
+   ```
 
-# ✅ Agent automatically deployed to AWS Bedrock
-```
+2. Commit and push:
+   ```bash
+   git add agentcore/agentcore.json my_agent.py
+   git commit -m "Add my-new-agent"
+   git push origin main
+   ```
 
+The workflow automatically deploys the new agent alongside existing ones.
 
 ## Project Structure
 
-- `agent.py` - Agent entrypoint
-- `.bedrock_agentcore.yaml` - Agent configuration
-- `Dockerfile` - Container definition
-- `.github/workflows/deploy-agent.yml` - Deployment workflow
+```
+agent.py                          # Agent entrypoint
+agentcore/
+  agentcore.json                  # Agent configuration
+  aws-targets.json                # Deployment target (account/region)
+  cdk/                            # CDK app (managed by agentcore CLI)
+Dockerfile                        # Container definition
+.github/workflows/deploy-agent.yml  # Deployment workflow
+```
 
 ## Deployment Versioning & History
 
 Every deployment is tracked and versioned automatically:
 
 ### Artifacts
-Each successful deployment creates timestamped artifacts:
-- **Naming**: `bedrock-agentcore-config-{agent-name}-{commit-sha}`
+Each successful deployment creates artifacts:
+- **Naming**: `agentcore-config-{commit-sha}`
+- **Contents**: `agentcore/agentcore.json` and `agentcore/aws-targets.json`
 - **Retention**: 90 days
-- **Purpose**: Full audit trail of deployments and configuration changes
 
 ### Version Tracking
 - Each `git push` to `main` creates a new agent version in AWS Bedrock

agentcore/.gitignore

@@ -0,0 +1,15 @@
+# Secrets (local environment files are never committed)
+.env.local
+
+# CDK Build Artifacts
+cdk/cdk.out/
+cdk/node_modules/
+
+# CLI Internals
+.cli/*
+
+# Ephemeral Staging
+.cache/*
+
+# Exception: Commit the State
+!.cli/deployed-state.json

agentcore/.llm-context/README.md

@@ -0,0 +1,15 @@
+# LLM Context Files
+
+**DO NOT EDIT THESE FILES** - They are read-only reference for AI coding assistants.
+
+## Files
+
+| File             | JSON Config        | Purpose                              |
+| ---------------- | ------------------ | ------------------------------------ |
+| `agentcore.ts`   | `agentcore.json`   | Project and agent environment config |
+| `aws-targets.ts` | `aws-targets.json` | Deployment targets                   |
+
+## Usage
+
+When editing schema JSON files, reference the corresponding `.ts` file here for type definitions and validation
+constraints (marked with `@regex`, `@min`, `@max`).

agentcore/.llm-context/agentcore.ts

@@ -0,0 +1,84 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * READ-ONLY LLM CONTEXT - Do not edit this file.
+ *
+ * JSON File: agentcore/agentcore.json
+ * Purpose: Top-level project configuration with flat resource model
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ROOT SCHEMA: AgentCoreProjectSpec
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface AgentCoreProjectSpec {
+  name: string; // @regex ^[A-Za-z][A-Za-z0-9]{0,22}$ @max 23 - project name
+  version: number; // Schema version (integer)
+  agents: AgentEnvSpec[]; // Unique by name
+  memories: Memory[]; // Unique by name
+  credentials: Credential[]; // Unique by name
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ENUMS
+// ─────────────────────────────────────────────────────────────────────────────
+
+type BuildType = 'CodeZip' | 'Container';
+type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
+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
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface AgentEnvSpec {
+  type: 'AgentCoreRuntime';
+  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
+  build: BuildType;
+  entrypoint: string; // @regex ^[a-zA-Z0-9_][a-zA-Z0-9_/.-]*\.(py|ts|js)(:[a-zA-Z_][a-zA-Z0-9_]*)?$ e.g. "main.py:handler" or "index.ts"
+  codeLocation: string; // Directory path
+  runtimeVersion: RuntimeVersion;
+  envVars?: EnvVar[];
+  networkMode?: NetworkMode; // default 'PUBLIC'
+  instrumentation?: Instrumentation; // OTel settings
+  modelProvider?: ModelProvider; // Model provider used by this agent
+}
+
+interface Instrumentation {
+  enableOtel: boolean; // default true - wrap entrypoint with opentelemetry-instrument
+}
+
+interface EnvVar {
+  name: string; // @regex ^[A-Za-z_][A-Za-z0-9_]*$ @max 255
+  value: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MEMORY
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Memory {
+  type: 'AgentCoreMemory';
+  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
+  eventExpiryDuration: number; // @min 7 @max 365 (days)
+  strategies: MemoryStrategy[]; // @min 1, unique by type
+}
+
+interface MemoryStrategy {
+  type: MemoryStrategyType;
+  name?: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
+  description?: string;
+  namespaces?: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CREDENTIAL
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Credential {
+  type: 'ApiKeyCredentialProvider';
+  name: string; // @regex ^[A-Za-z0-9_.-]+$ @min 3 @max 255
+}

agentcore/.llm-context/aws-targets.ts

@@ -0,0 +1,37 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * READ-ONLY LLM CONTEXT - Do not edit this file.
+ *
+ * JSON File: agentcore/aws-targets.json
+ * Purpose: AWS deployment targets for AgentCore resources
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ROOT SCHEMA: AwsDeploymentTargets (array)
+// ─────────────────────────────────────────────────────────────────────────────
+
+// The JSON file contains an array of deployment targets.
+// Target names must be unique within the array.
+type AwsDeploymentTargets = AwsDeploymentTarget[];
+
+interface AwsDeploymentTarget {
+  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_-]*$ @max 64 - unique identifier
+  description?: string; // @max 256
+  account: string; // @regex ^[0-9]{12}$ - AWS account ID (exactly 12 digits)
+  region: AgentCoreRegion;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SUPPORTED REGIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+type AgentCoreRegion =
+  | 'ap-northeast-1'
+  | 'ap-south-1'
+  | 'ap-southeast-1'
+  | 'ap-southeast-2'
+  | 'eu-central-1'
+  | 'eu-west-1'
+  | 'us-east-1'
+  | 'us-east-2'
+  | 'us-west-2';

agentcore/agentcore.json

@@ -1,6 +1,6 @@
 {
-  "name": "autodeployed-agent",
-  "version": "1",
+  "name": "autodeployedagent",
+  "version": 1,
   "agents": [
     {
       "type": "AgentCoreRuntime",
@@ -10,7 +10,9 @@
       "codeLocation": ".",
       "runtimeVersion": "PYTHON_3_13",
       "networkMode": "PUBLIC",
-      "instrumentation": { "enabled": true }
+      "instrumentation": { "enableOtel": true }
     }
-  ]
+  ],
+  "memories": [],
+  "credentials": []
 }