DEV Community

Girish Mukim
Girish Mukim

Posted on

Fixing AgentCore CLI Hangs on Windows: Step‑by‑Step with Python, AWS CLI, Strands agents and WSL

#ai #bedrock #agentcore #agents

Introduction

While experimenting with Amazon Bedrock AgentCore on Windows, I ran into a frustrating issue:

agentcore configure would hang indefinitely, even with a minimal sample agent.

No errors. No logs. Just a frozen terminal.

This blog documents:

  • The exact symptoms
  • Why this happens on Windows
  • Why Python 3.13 breaks AgentCore
  • Why installing Python 3.11 is not enough
  • And the only reliable fix

If you’re using Strands + AgentCore on Windows, this will save you hours.

You can try running AgentCore directly on Windows and follow the troubleshooting steps I went through, but in my experience, it never worked reliably. If it doesn’t work for you either, don’t worry — WSL on Windows is the way to go for a stable setup.

Environment

  • OS: Windows 10 / 11

  • Python versions installed:

    • ❌ Python 3.13
    • ✅ Python 3.11.9

  • Tools:

    • bedrock-agentcore-starter-toolkit
    • strands
    • strands-agents-tools

  • Shell: Command Prompt / PowerShell

The Symptom

Running the following command:

agentcore configure --entrypoint agentcore.py --region us-east-1
Enter fullscreen mode Exit fullscreen mode

Results in:

  • No output
  • No error
  • CLI hangs forever

Never ending wait...

Terminal showing raw `agentcore configure` endraw hanging with no output

First Assumption: My Agent Code Is Wrong ❌

I simplified the agent to the absolute minimum:

from strands import Agent
from strands.models import MockModel

agent = Agent(
    model=MockModel(),
    system_prompt="test"
)
Enter fullscreen mode Exit fullscreen mode

Still hangs.

➡️ This proves the issue is not agent logic.

Second Assumption: AWS Credentials or Bedrock ❌

I validated AWS access:

aws sts get-caller-identity --region us-east-1
Enter fullscreen mode Exit fullscreen mode

✔ Works instantly.

➡️ Not an AWS or Bedrock permission issue.

Third Assumption:: Python Version (3.11) ❌

If you don't want to try Python version 3.11, go ahead to skip this section and move to Network & Connectivity Validation

Checking Python version:

python --version
Enter fullscreen mode Exit fullscreen mode 
Python 3.13.x
Enter fullscreen mode Exit fullscreen mode

Checking where AgentCore-related packages are installed:

pip show strands-agents | findstr Location
pip show strands-agents-tools | findstr Location
pip show bedrock-agentcore-starter-toolkit | findstr Location
Enter fullscreen mode Exit fullscreen mode

Output:

Location: C:\Users\AppData\Roaming\Python\Python313\site-packages
Enter fullscreen mode Exit fullscreen mode

➡️ All AgentCore binaries are bound to Python 3.13

C:\Users\LearnAI>pip show strands-agents | findstr Python
Location: C:\Users\AppData\Roaming\Python\Python313\site-packages

C:\Users\LearnAI>pip show strands-agents-tools | findstr Python
Location: C:\Users\AppData\Roaming\Python\Python313\site-packages

C:\Users\LearnAI>pip show bedrock-agentcore-starter-toolkit | findstr Python
Location: C:\Users\AppData\Roaming\Python\Python313\site-packages

C:\Users\LearnAI>pip show bedrock-agentcore | findstr Python
Location: C:\Users\AppData\Roaming\Python\Python313\site-packages

C:\Users\LearnAI>
Enter fullscreen mode Exit fullscreen mode

Installing Python 3.11 Is Necessary — But Not Sufficient

I installed Python 3.11.9:

🔗 https://www.python.org/downloads/release/python-3119/

But after installation:

python --version
Enter fullscreen mode Exit fullscreen mode

Still showed:

Python 3.13.x
Enter fullscreen mode Exit fullscreen mode

Why?

Because Windows PATH still prioritizes Python 3.13.

Attempt 1: Fix PATH Order (Partial Fix)

Steps:

  1. Open Environment Variables
  2. Edit System PATH
  3. Move Python 3.11 paths above Python 3.13

Example:

C:\Python311\
C:\Python311\Scripts\
C:\Users\...\Python313\
Enter fullscreen mode Exit fullscreen mode

Restart terminal.

Verify:

python --version
Enter fullscreen mode Exit fullscreen mode 
Python 3.11.9
Enter fullscreen mode Exit fullscreen mode

Windows PATH editor

Still Not Working? Here’s Why

Even after fixing PATH, pip-installed binaries remain tied to Python 3.13.

This is the key gotcha.

Example:

agentcore
Enter fullscreen mode Exit fullscreen mode

This binary was installed using:

Python 3.13 pip
Enter fullscreen mode Exit fullscreen mode

So it still launches under 3.13, regardless of PATH.

Let's remove Python 3.13

✅ Completely remove Python 3.13 tooling

1. Uninstall AgentCore and related packages 

pip uninstall bedrock-agentcore-starter-toolkit strands-agents strands-agents-tools -y
Enter fullscreen mode Exit fullscreen mode

Make sure this pip is from Python 3.13.

C:\Users\LearnAI>where pip
C:\Python313\Scripts\pip.exe
C:\Users\AppData\Roaming\Python\Python313\Scripts\pip.exe

C:\Users\LearnAI>pip uninstall bedrock-agentcore-starter-toolkit strands strands-agents-tools -y
Found existing installation: bedrock-agentcore-starter-toolkit 0.1.10
Uninstalling bedrock-agentcore-starter-toolkit-0.1.10:
  Successfully uninstalled bedrock-agentcore-starter-toolkit-0.1.10
WARNING: Skipping strands as it is not installed.
Found existing installation: strands-agents-tools 0.2.19
Uninstalling strands-agents-tools-0.2.19:
  Successfully uninstalled strands-agents-tools-0.2.19

C:\Users\LearnAI>pip uninstall strands-agents -y
Found existing installation: strands-agents 1.22.0
Uninstalling strands-agents-1.22.0:
  Successfully uninstalled strands-agents-1.22.0

C:\Users\LearnAI>
Enter fullscreen mode Exit fullscreen mode

2. (Optional but recommended) Uninstall Python 3.13

From:

  • Windows “Add or Remove Programs”

This avoids future confusion.

3. Activate Python 3.11 explicitly 

py -3.11 -m venv agentcore-env
agentcore-env\Scripts\activate
Enter fullscreen mode Exit fullscreen mode

Verify:

python --version
Enter fullscreen mode Exit fullscreen mode 
Python 3.11.9
Enter fullscreen mode Exit fullscreen mode

In my case, I removed path referencing Python313 from system environment variables and started a new command line terminal.

still observed that pip is pointing to Python313.

C:\Users\LearnAI>where pip
C:\Users\AppData\Roaming\Python\Python313\Scripts\pip.exe
Enter fullscreen mode Exit fullscreen mode 
C:\Users\LearnAI>python -m pip install --upgrade pip
Requirement already satisfied: pip in c:\users\appdata\local\programs\python\python311\lib\site-packages (24.0)
Collecting pip
  Using cached pip-25.3-py3-none-any.whl.metadata (4.7 kB)
Using cached pip-25.3-py3-none-any.whl (1.8 MB)
Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 24.0
    Uninstalling pip-24.0:
      Successfully uninstalled pip-24.0
  WARNING: The scripts pip.exe, pip3.11.exe and pip3.exe are installed in 'C:\Users\AppData\Local\Programs\Python\Python311\Scripts' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed pip-25.3

C:\Users\LearnAI>
Enter fullscreen mode Exit fullscreen mode

Added C:\Users\AppData\Local\Programs\Python\Python311\Scripts to PATH.
Also manually removed pip.exe from Python313 folder.

C:\Users\LearnAI>where pip
C:\Users\AppData\Local\Programs\Python\Python311\Scripts\pip.exe

C:\Users\LearnAI>
Enter fullscreen mode Exit fullscreen mode

4. Reinstall everything under Python 3.11 

pip install --upgrade pip
pip install boto3 bedrock-agentcore-starter-toolkit strands-agents strands-agents-tools
Enter fullscreen mode Exit fullscreen mode

Verify:

pip show bedrock-agentcore-starter-toolkit | findstr Location
Enter fullscreen mode Exit fullscreen mode

Expected:

Python311\site-packages
Enter fullscreen mode Exit fullscreen mode 
C:\Users\LearnAI>
C:\Users\LearnAI>pip show bedrock-agentcore-starter-toolkit | findstr Location
Location: C:\Users\AppData\Local\Programs\Python\Python311\Lib\site-packages

C:\Users\LearnAI>
Enter fullscreen mode Exit fullscreen mode

Oops Still the same issue -

Despite this cleanup, the agentcore configure hang still persists, confirming this is not a Python-version issue.

Here’s how you can write the Python 3.11 point in the same style as your other assumptions:

python --version
# Python 3.11.x
Enter fullscreen mode Exit fullscreen mode

✔ Python 3.11 is correctly set up and recognized.

➡️ Python version was not the root cause of the AgentCore issues.

Network & Connectivity Validation

To rule out firewall or endpoint connectivity issues, the following test was performed:

curl https://bedrock.us-east-1.amazonaws.com

Result:
<UnknownOperationException/>

Why this result is important

  • DNS resolution succeeded.
  • TLS handshake succeeded.
  • Outbound HTTPS (port 443) connectivity is confirmed.
  • The error is expected when calling the Bedrock control-plane endpoint without request signing.

The local machine can successfully reach AWS Bedrock endpoints. Firewall or port blocking is unlikely to be the root cause.

Since AgentCore continued to hang or behave unpredictably on Windows despite fixing Python and AWS CLI issues, I decided to rule out platform-related problems. To do this, I switched to WSL (Windows Subsystem for Linux), which provides a Linux environment on Windows, and tested AgentCore there. This approach helps isolate any Windows-specific limitations and ensures a cleaner, more consistent runtime for Python 3.11 and AWS CLI.

High-level approach

You will:

  1. Open a Linux distro inside WSL (Ubuntu recommended)
  2. Install Python 3.11 inside WSL
  3. Install AgentCore + Strands inside WSL
  4. Run agentcore configure from WSL
  5. Compare behavior with Windows

Step-by-step: Running AgentCore in WSL

You can refer Microsoft’s official WSL installation documentation — step‑by‑step on installing WSL and a Linux distro (like Ubuntu) on Windows using the integrated installer:
👉 Install WSL

This doc explains how to enable WSL, install a Linux distribution (Ubuntu by default), and get up and running with WSL.

1️⃣ Confirm your WSL distro

From Windows command line:

C:\Users\LearnAI>wsl
gmukim@LearnAI:/mnt/c/Users/LearnAI$
Enter fullscreen mode Exit fullscreen mode

From PowerShell:

wsl -l -v
Enter fullscreen mode Exit fullscreen mode

You should see something like:

NAME      STATE   VERSION
Ubuntu    Running 2
Enter fullscreen mode Exit fullscreen mode

If you don’t have Ubuntu, install it:

wsl --install -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

WSL distro list showing Ubuntu (WSL2)

2️⃣ Open Ubuntu (WSL)

Run:

wsl
Enter fullscreen mode Exit fullscreen mode

You are now inside Linux, not Windows. Start WSL from your working directory.

3️⃣ Install Python 3.11 in WSL (clean)

Inside Ubuntu:

sudo apt update
sudo apt install -y python3.11 python3.11-venv python3.11-dev
Enter fullscreen mode Exit fullscreen mode

Verify:

python3.11 --version
Enter fullscreen mode Exit fullscreen mode

python3.11 version

4️⃣ Create a virtual environment (important) 

python3.11 -m venv agentcore-env
source agentcore-env/bin/activate
Enter fullscreen mode Exit fullscreen mode

You should see:

(agentcore-env)
Enter fullscreen mode Exit fullscreen mode 
gmukim@LearnAI:/mnt/c/GirishIBM/SkillUP/AWS/Certifications/AI Professional/LearnAI$ python3.11 -m venv agentcore-env

gmukim@LearnAI:/mnt/c/Users/LearnAI$
gmukim@LearnAI:/mnt/c/Users/LearnAI$ source agentcore-env/bin/activate
(agentcore-env) gmukim@LearnAI:/mnt/c/Users/LearnAI$
Enter fullscreen mode Exit fullscreen mode

5️⃣ Install AgentCore + dependencies 

pip install --upgrade pip
pip install bedrock-agentcore-starter-toolkit strands-agents strands-agents-tools
Enter fullscreen mode Exit fullscreen mode

Verify installs:

pip show bedrock-agentcore
pip show strands-agents
pip show strands-agents-tools
Enter fullscreen mode Exit fullscreen mode 
(agentcore-env) gmukim@LearnAI:/mnt/c/GirishIBM/SkillUP/AWS/Certifications/AI Professional/LearnAI$ pip show bedrock-agentcore
Name: bedrock-agentcore
Version: 1.2.0
Summary: An SDK for using Bedrock AgentCore
Home-page: https://github.com/aws/bedrock-agentcore-sdk-python
Author:
Author-email: AWS <opensource@amazon.com>
License: Apache-2.0
Location: /mnt/c/GirishIBM/SkillUP/AWS/Certifications/AI Professional/LearnAI/agentcore-env/lib/python3.11/site-packages
Requires: boto3, botocore, pydantic, starlette, typing-extensions, urllib3, uvicorn, websockets
Required-by: bedrock-agentcore-starter-toolkit

(agentcore-env) gmukim@LearnAI:/mnt/c/Users/LearnAI$ pip show strands-agents
Name: strands-agents
Version: 1.22.0
Summary: A model-driven approach to building AI agents in just a few lines of code
Home-page: https://github.com/strands-agents/sdk-python
Author:
Author-email: AWS <opensource@amazon.com>
License: Apache-2.0
Location: /mnt/c/Users/LearnAI/agentcore-env/lib/python3.11/site-packages
Requires: boto3, botocore, docstring-parser, jsonschema, mcp, opentelemetry-api, opentelemetry-instrumentation-threading, opentelemetry-sdk, pydantic, typing-extensions, watchdog
Required-by: strands-agents-tools
(agentcore-env) gmukim@LearnAI:/mnt/c/Users/LearnAI$

(agentcore-env) gmukim@LearnAI:/mnt/c/Users/LearnAI$ pip show strands-agents-tools
Name: strands-agents-tools
Version: 0.2.19
Summary: A collection of specialized tools for Strands Agents
Home-page: https://github.com/strands-agents/tools
Author:
Author-email: AWS <opensource@amazon.com>
License: Apache-2.0
Location: /mnt/c/Users/LearnAI/agentcore-env/lib/python3.11/site-packages
Requires: aiohttp, aws-requests-auth, botocore, dill, markdownify, pillow, prompt-toolkit, pyjwt, requests, rich, slack-bolt, strands-agents, sympy, tenacity, typing-extensions, watchdog
Required-by:
(agentcore-env) gmukim@LearnAI:/mnt/c/Users/LearnAI$
Enter fullscreen mode Exit fullscreen mode

7️⃣ Configure AWS credentials inside WSL

This is important — Windows AWS creds do not automatically carry over.

Inside WSL:

aws configure
Enter fullscreen mode Exit fullscreen mode

If require, install AWS CLI.

8️⃣ Run AgentCore configure and Launch (the real test)

Now the moment of truth:

agentcore configure --entrypoint agentcore.py --region us-east-1 --verbose
Enter fullscreen mode Exit fullscreen mode

agentcore configure

agentcore launch
Enter fullscreen mode Exit fullscreen mode

agentcore launch

agentcore status
agentcore invoke '{"prompt": "What is the current time?"}'
Enter fullscreen mode Exit fullscreen mode

✔ Completes successfully
✔ No hang
✔ AgentCore works as expected

Final Response

Destroying AgentCore Resources [ Critical ]

After testing your agent, run:

agentcore destroy
Enter fullscreen mode Exit fullscreen mode

This deletes the deployed agent and any remote build artifacts.

agentcore destroy

Do you want me to also add the one-line reminder message for learners?

Final Thoughts

This issue is subtle, silent, and extremely frustrating — especially because AgentCore fails by hanging instead of erroring.

Hopefully, this guide helps you avoid the same trap.

This journey showed me how environment issues can block AgentCore. I found that using WSL with Python 3.11 and a clean AWS CLI install provided a stable setup.

That’s it for this deep dive! Hopefully, this helps you avoid the pitfalls I ran into.

— Girish, signing off. See you in the next one!

Top comments (0)