Skip to content

Commit adb684a

Browse files
author
Andrés Aguilar
committed
feat: add full TypeScript agent support
- TypeScript agents use Container build (CodeZip only supports Python runtimes) - Dev server runs TS locally with tsx watch (no Docker needed for dev) - Strands TS SDK + Express server template - MCP standalone TS template - Node 22 slim Dockerfile for container deployment - TS+CodeZip explicitly blocked with clear error message - Updated docs for TypeScript language support
1 parent 1a45c28 commit adb684a

40 files changed

Lines changed: 1019 additions & 97 deletions

‎.prettierignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
CHANGELOG.md
22
src/assets/**/*.md
3+
src/assets/**/*.ts

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ AgentCore with minimal configuration.
1414

1515
- **Node.js** 20.x or later
1616
- **uv** for Python agents ([install](https://docs.astral.sh/uv/getting-started/installation/))
17+
- **Docker**, **Podman**, or **Finch** for TypeScript agents (Container deployment only)
1718

1819
## Installation
1920

@@ -120,11 +121,14 @@ my-project/
120121
```
121122
├── app/ # Application code
122123
│ └── <AgentName>/ # Agent directory
123-
│ ├── main.py # Agent entry point
124+
│ ├── main.py # Python agent entry point
124125
│ ├── pyproject.toml # Python dependencies
125126
│ └── model/ # Model configuration
126127
```
127128

129+
TypeScript agents use a similar structure with `main.ts`, `package.json`, `tsconfig.json`, and a `Dockerfile` for
130+
deployment.
131+
128132
## Configuration
129133

130134
Projects use JSON schema files in the `agentcore/` directory:

‎docs/commands.md‎

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -65,30 +65,30 @@ agentcore create \
6565
--memory none
6666
```
6767

68-
| Flag | Description |
69-
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
70-
| `--name <name>` | Project name (alphanumeric, starts with letter, max 23 chars) |
71-
| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) |
72-
| `--no-agent` | Skip agent creation |
73-
| `--type <type>` | `create` (default) or `import` |
74-
| `--language <lang>` | `Python` (default) |
75-
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` |
76-
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
77-
| `--build <type>` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) |
78-
| `--api-key <key>` | API key for non-Bedrock providers |
79-
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` (see [Memory Shorthand Mapping](memory.md#--memory-shorthand-mapping)) |
80-
| `--protocol <protocol>` | `HTTP` (default), `MCP`, `A2A` |
81-
| `--network-mode <mode>` | `PUBLIC` (default) or `VPC` |
82-
| `--subnets <ids>` | Comma-separated subnet IDs (required for VPC mode) |
83-
| `--security-groups <ids>` | Comma-separated security group IDs (required for VPC mode) |
84-
| `--agent-id <id>` | Bedrock Agent ID (import only) |
85-
| `--agent-alias-id <id>` | Bedrock Agent Alias ID (import only) |
86-
| `--region <region>` | AWS region for Bedrock Agent (import only) |
87-
| `--output-dir <dir>` | Output directory |
88-
| `--skip-git` | Skip git initialization |
89-
| `--skip-python-setup` | Skip venv setup |
90-
| `--dry-run` | Preview without creating |
91-
| `--json` | JSON output |
68+
| Flag | Description |
69+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
70+
| `--name <name>` | Project name (alphanumeric, starts with letter, max 23 chars) |
71+
| `--defaults` | Use defaults (Python, Strands, Bedrock, no memory) |
72+
| `--no-agent` | Skip agent creation |
73+
| `--type <type>` | `create` (default) or `import` |
74+
| `--language <lang>` | `Python` (default) or `TypeScript` |
75+
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` |
76+
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
77+
| `--build <type>` | `CodeZip` (default for Python) or `Container` (default for TypeScript; see [Container Builds](container-builds.md)) |
78+
| `--api-key <key>` | API key for non-Bedrock providers |
79+
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` (see [Memory Shorthand Mapping](memory.md#--memory-shorthand-mapping)) |
80+
| `--protocol <protocol>` | `HTTP` (default), `MCP`, `A2A` |
81+
| `--network-mode <mode>` | `PUBLIC` (default) or `VPC` |
82+
| `--subnets <ids>` | Comma-separated subnet IDs (required for VPC mode) |
83+
| `--security-groups <ids>` | Comma-separated security group IDs (required for VPC mode) |
84+
| `--agent-id <id>` | Bedrock Agent ID (import only) |
85+
| `--agent-alias-id <id>` | Bedrock Agent Alias ID (import only) |
86+
| `--region <region>` | AWS region for Bedrock Agent (import only) |
87+
| `--output-dir <dir>` | Output directory |
88+
| `--skip-git` | Skip git initialization |
89+
| `--skip-python-setup` | Skip venv setup |
90+
| `--dry-run` | Preview without creating |
91+
| `--json` | JSON output |
9292

9393
### deploy
9494

@@ -197,8 +197,8 @@ agentcore add agent \
197197
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
198198
| `--name <name>` | Agent name (alphanumeric + underscores, starts with letter, max 48 chars) |
199199
| `--type <type>` | `create` (default), `byo`, or `import` |
200-
| `--build <type>` | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md)) |
201-
| `--language <lang>` | `Python` (create); `Python`, `TypeScript`, `Other` (BYO) |
200+
| `--build <type>` | `CodeZip` (default for Python) or `Container` (default for TypeScript; see [Container Builds](container-builds.md)) |
201+
| `--language <lang>` | `Python` (default) or `TypeScript` (create); `Python`, `TypeScript`, `Other` (BYO) |
202202
| `--framework <fw>` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` |
203203
| `--model-provider <p>` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` |
204204
| `--api-key <key>` | API key for non-Bedrock providers |

‎docs/container-builds.md‎

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,13 @@
33
Container builds package your agent as a Docker container image instead of a code ZIP. Use containers when you need
44
system-level dependencies, custom native libraries, or full control over the runtime environment.
55

6+
TypeScript agents always use Container build because AgentCore Runtime's CodeZip mode only supports Python runtimes. The
7+
CLI sets this automatically — no manual configuration needed.
8+
69
## Prerequisites
710

8-
A container runtime is required for local development (`agentcore dev`) and packaging (`agentcore package`). Supported
9-
runtimes:
11+
A container runtime is required for packaging (`agentcore package`) and for Python container agents during local
12+
development. Supported runtimes:
1013

1114
1. [Docker](https://docker.com)
1215
2. [Podman](https://podman.io)
@@ -16,13 +19,18 @@ The CLI auto-detects the first working runtime in the order listed above. If mul
1619
highest-priority one wins.
1720

1821
> A local runtime is **not** required for `agentcore deploy` — AWS CodeBuild builds the image remotely.
22+
>
23+
> TypeScript agents do **not** need a local container runtime for `agentcore dev` — they run directly with `tsx watch`.
1924
2025
## Getting Started
2126

2227
```bash
23-
# New project with container build
28+
# Python project with container build (opt-in)
2429
agentcore create --name MyProject --build Container
2530

31+
# TypeScript project (Container is the default and only option)
32+
agentcore create --name MyProject --language TypeScript --framework Strands --model-provider Bedrock
33+
2634
# Add container agent to existing project
2735
agentcore add agent --name MyAgent --build Container --framework Strands --model-provider Bedrock
2836
```
@@ -33,10 +41,21 @@ Both commands generate a `Dockerfile` and `.dockerignore` in the agent's code di
3341
app/MyAgent/
3442
├── Dockerfile
3543
├── .dockerignore
36-
├── pyproject.toml
44+
├── pyproject.toml # Python
3745
└── main.py
3846
```
3947

48+
TypeScript agents generate a Node.js-based Dockerfile:
49+
50+
```
51+
app/MyAgent/
52+
├── Dockerfile # Node 22 slim base
53+
├── .dockerignore
54+
├── package.json
55+
├── tsconfig.json
56+
└── main.ts
57+
```
58+
4059
## Generated Dockerfile
4160

4261
The template uses `ghcr.io/astral-sh/uv:python3.12-bookworm-slim` as the base image with these design choices:
@@ -75,13 +94,20 @@ All other fields work the same as CodeZip agents.
7594
agentcore dev
7695
```
7796

78-
For container agents, the dev server:
97+
For **Python** container agents, the dev server:
7998

8099
1. Builds the container image and adds a dev layer with `uvicorn`
81100
2. Runs the container with your source directory volume-mounted at `/app`
82101
3. Enables hot reload via `uvicorn --reload` — code changes apply without rebuilding
83102

84-
AWS credentials are forwarded automatically (environment variables and `~/.aws` mounted read-only).
103+
For **TypeScript** container agents, the dev server runs locally without Docker:
104+
105+
1. Runs `npm install` if needed
106+
2. Starts `tsx watch` with hot-reload
107+
3. No container build or runtime required
108+
109+
AWS credentials are forwarded automatically (environment variables and `~/.aws` mounted read-only for Python
110+
containers).
85111

86112
## Packaging and Deployment
87113

‎docs/frameworks.md‎

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,34 @@ that runs on AgentCore:
121121
| `--framework <fw>` | `Strands` or `LangChain_LangGraph` |
122122
| `--memory <opt>` | `none`, `shortTerm`, `longAndShortTerm` |
123123

124+
## Supported Languages
125+
126+
| Language | Build Type | Dev Server | Frameworks |
127+
| -------------- | ---------- | ----------------- | ----------------------------------------------- |
128+
| **Python** | CodeZip | uvicorn (local) | Strands, LangChain/LangGraph, GoogleADK, OpenAI |
129+
| **TypeScript** | Container | tsx watch (local) | Strands |
130+
131+
### TypeScript Agents
132+
133+
TypeScript agents use the [Strands Agents SDK](https://github.com/strands-agents/sdk-typescript) with Express and deploy
134+
as Container images. AgentCore Runtime's CodeZip mode only supports Python runtimes, so TypeScript agents automatically
135+
default to Container build.
136+
137+
> **Local development runs without Docker.** The `agentcore dev` command runs TypeScript agents directly with
138+
> `tsx watch` for fast iteration and hot-reload — no container build needed. Docker/Podman/Finch is only required for
139+
> `agentcore deploy` and `agentcore package`.
140+
141+
```bash
142+
# Create a TypeScript agent
143+
agentcore create --name MyProject --language TypeScript --framework Strands --model-provider Bedrock
144+
145+
# Local dev — runs with tsx, no Docker needed
146+
agentcore dev
147+
148+
# Deploy — builds container image via CodeBuild
149+
agentcore deploy
150+
```
151+
124152
## Bring Your Own (BYO) Agent
125153

126154
For existing agent code or frameworks not listed above, use the BYO option:
@@ -138,16 +166,13 @@ agentcore add agent \
138166

139167
1. **Entrypoint**: Your code must expose an HTTP endpoint that accepts agent invocation requests
140168
2. **Code location**: Directory containing your agent code
141-
3. **Language**: Python
169+
3. **Language**: Python or TypeScript
142170

143171
### BYO Options
144172

145-
| Flag | Description |
146-
| ------------------------ | ------------------------------------------ |
147-
| `--type byo` | Use BYO mode (required) |
148-
| `--code-location <path>` | Directory containing your agent code |
149-
| `--entrypoint <file>` | Entry file (e.g., `main.py` or `index.ts`) |
150-
| `--language <lang>` | `Python` |
173+
| Flag | Description |\n| ------------------------ | ------------------------------------------ | | `--type byo` | Use
174+
BYO mode (required) | | `--code-location <path>` | Directory containing your agent code | | `--entrypoint <file>` |
175+
Entry file (e.g., `main.py` or `main.ts`) | | `--language <lang>` | `Python` or `TypeScript` |
151176

152177
## Framework Comparison
153178

‎docs/local-development.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,16 @@ The dev server automatically:
4242
2. Runs `uv sync` to install dependencies from `pyproject.toml`
4343
3. Starts uvicorn with your agent
4444

45+
### TypeScript / Node.js
46+
47+
The dev server automatically:
48+
49+
1. Runs `npm install` if `node_modules` is missing
50+
2. Starts `tsx watch` with your agent entry point (hot-reload enabled)
51+
52+
> TypeScript agents use Container build for deployment, but `agentcore dev` runs them locally without Docker for fast
53+
> iteration.
54+
4555
### API Keys
4656

4757
For non-Bedrock providers, add keys to `agentcore/.env.local`:
@@ -93,10 +103,13 @@ immediately.
93103

94104
### Container Agents
95105

96-
For container agents, the dev server builds a Docker image and runs it with your source directory mounted as a volume.
97-
Changes to your code are picked up by uvicorn's `--reload` inside the container — no image rebuild needed.
106+
For Python container agents, the dev server builds a Docker image and runs it with your source directory mounted as a
107+
volume. Changes to your code are picked up by uvicorn's `--reload` inside the container — no image rebuild needed.
108+
109+
TypeScript agents always run locally in dev mode (via `tsx watch`), even though they use Container build for deployment.
110+
No Docker is needed for `agentcore dev` with TypeScript.
98111

99-
See [Container Builds](container-builds.md) for full details on container development.
112+
See [Container Builds](container-builds.md) for full details on container development and deployment.
100113

101114
## Dev vs Deployed Behavior
102115

0 commit comments

Comments
 (0)