adding coding agents

Author: evandrofranco

01-tutorials/01-AgentCore-runtime/12-coding-agents/01-claude-code-with-s3-files/README.md

@@ -0,0 +1,136 @@
+# Claude Code on AgentCore Runtime with S3 Files
+
+Deploys Claude Code as an HTTP agent on AWS Bedrock AgentCore Runtime, with an S3 Files file system mounted at `/mnt/s3files` for persistent storage shared across sessions.
+
+## Architecture
+
+```
+  ┌─────────────────────────┐         ┌─────────────────────────┐
+  │  AgentCore Runtime      │         │  AgentCore Runtime      │
+  │  Session A              │         │  Session B              │
+  │  (Claude Code)          │         │  (Claude Code)          │
+  │                         │         │                         │
+  │  /mnt/s3files ──────────┼────┐    │  /mnt/s3files ──────────┼────┐
+  └─────────────────────────┘    │    └─────────────────────────┘    │
+                                 │                                   │
+                                 ▼                                   ▼
+                    ┌──────────────────────────────────────────────────┐
+                    │  S3 Files File System                            │
+                    │                                                  │
+                    │  ┌────────────────────────┐                      │
+                    │  │  S3 Files Access Point │                      │
+                    │  │  (uid/gid 1000)        │                      │
+                    │  └───────────┬────────────┘                      │
+                    └──────────────┼───────────────────────────────────┘
+                                   │
+                                   ▼
+                    ┌──────────────────────────────┐
+                    │  S3 Bucket                   │
+                    │  (agentcore-<account-id>)    │
+                    │                              │
+                    │  agents/                     │
+                    │  ├── skills/                 │
+                    │  ├── results/                │
+                    │  └── ...                     │
+                    └──────────────────────────────┘
+```
+
+Multiple runtime sessions mount the same S3 Files file system, enabling agents to share skills, results, and data across independent invocations.
+
+```
+CloudFormation stack (cfn-vpc.yaml):
+  VPC, subnets, NAT Gateway, Security Group
+  S3 Files IAM role, file system, access point, mount targets
+
+deploy.py creates:
+  IAM execution role
+  AgentCore Runtime (container from ECR, S3 Files mounted at /mnt/s3files)
+```
+
+## Prerequisites
+
+### Python environment
+
+```bash
+uv venv --python 3.13 .venv
+source .venv/bin/activate
+uv pip install boto3 awscli --force-reinstall --no-cache-dir
+```
+
+### S3 Files IAM policies
+
+The CloudFormation stack creates an IAM role (`S3FilesRole`) with the permissions required by S3 Files (S3, KMS, and EventBridge). For the full list of required policies, see the [S3 Files prerequisite policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files-prereq-policies.html) documentation.
+
+## Step-by-step guide
+
+### Step 1 — Infrastructure setup (CloudFormation)
+
+Run the setup script to create the S3 bucket, deploy the CloudFormation stack (VPC, subnets, NAT Gateway, Security Group, S3 Files), build the arm64 Docker image, and push it to ECR.
+
+```bash
+./setup.sh us-west-2
+```
+
+All outputs are saved to `envvars.config` and used automatically by the next steps.
+
+### Step 2 — Deploy the agent
+
+Create the IAM execution role and the AgentCore Runtime:
+
+```bash
+python deploy.py
+```
+
+The script waits until the runtime status is `READY` and saves the runtime config to `runtime_config.json`.
+
+If you need to update an existing runtime (e.g. after rebuilding the Docker image), run:
+
+```bash
+python update.py
+```
+
+### Step 3 — Invoke the agent
+
+Send a prompt to the deployed agent. The first call creates a new session; subsequent calls can reuse the session ID for conversation continuity.
+
+**Session A** — create a shared skill on the persistent filesystem:
+
+```bash
+python invoke.py "can u create a new skill, to review python code? This skill should be created into /mnt/s3files/skills/"
+```
+
+Continue the conversation within the same session:
+
+```bash
+python invoke.py --session <session-a-id> "now add unit tests for that skill"
+```
+
+**Session B** — a completely new session accesses the same filesystem and uses the skill created by Session A:
+
+```bash
+python invoke.py "list the skills available in /mnt/s3files/skills/ and use the python review skill to review this code: def add(a,b): return a+b"
+```
+
+Both sessions share `/mnt/s3files`, so anything written by one session is immediately available to others.
+
+### Step 4 — Execute a command on the running session
+
+Run a shell command directly on the container using the session ID from the previous step:
+
+```bash
+python exec_cmd.py --session 7fd93a80-8838-4721-abea-b1787dd0172c "ls -l /mnt/s3files"
+```
+
+### Step 5 — Cleanup
+
+Delete all AgentCore resources (runtime, IAM role) and the CloudFormation stack. The S3 bucket is kept.
+
+```bash
+python cleanup.py
+```
+
+Or use the shell wrapper:
+
+```bash
+./cleanup.sh
+```