Doctor

Do NOT use for:

• Creating a new project or getting started → use agents-get-started
• Deploy failures that aren’t environment-related (CDK errors, IAM) → use agents-deploy
• Agent runtime errors → use agents-debug

Input

No arguments required.

Process

Run each check and report the result. For anything missing, give the exact fix command — don’t just say “install X.”

Check 1: AgentCore CLI

If the command errors instead of returning a version:

Run which agentcore to see what’s installed:

• Path in /usr/local/lib/python*/site-packages/ or similar Python location → the old Starter Toolkit is shadowing the new CLI. Uninstall it (see below).
• Path in a Node.js-based location but still errors → the Node.js version may be wrong. Continue to Check 2.
• No path returned → the CLI isn’t installed.

If not found:

Requires Node.js 20+. If npm isn’t available, install Node.js first: https://nodejs.org (opens in a new tab)

If old Starter Toolkit is installed (Python-based agentcore command):

Check 2: Node.js version

Requires Node.js 20.x or later. If older:

• macOS: brew install node or download from https://nodejs.org (opens in a new tab)
• Linux: use nvm install 20 (https://github.com/nvm-sh/nvm (opens in a new tab))

Check 3: uv (Python package manager)

uv manages Python virtual environments for your agent code. It’s required for Python agents.

If not found:

After installing, restart your terminal or run source ~/.bashrc (or ~/.zshrc).

Check 4: AWS credentials

If AWS CLI not found:

If credentials not configured:

If using SSO:

Check the region: The region in aws configure must match the region where you’ve enabled Bedrock model access and where you’ll deploy.

Check 5: Bedrock model access

If no Claude models appear, or if you see access errors:

1. Go to AWS Console → Amazon Bedrock → Model access
2. Click “Manage model access”
3. Enable “Anthropic Claude” models
4. Click “Save changes” — access is usually granted within a minute

Required model for default projects: The default model is a cross-region inference profile (e.g., global.anthropic.claude-sonnet-4-5-20250929-v1:0 — the CLI scaffolds global. by default). The global. prefix routes to any commercial region; geographic prefixes (us., eu., apac.) keep inference within that geography. All prefixes require model access enabled in every destination region the profile covers. Check agentcore.json after agentcore create for the exact model ID used.

Check 6: IAM permissions

For deploy to work, you need:

• iam:CreateRole — to create execution roles
• bedrock:InvokeModel — to call Bedrock models
• ecr:CreateRepository, ecr:PutImage — for container builds
• codebuild:StartBuild — for remote builds

If permissions are missing, ask your AWS admin to attach BedrockAgentCoreFullAccess and AmazonBedrockFullAccess managed policies to your IAM user or role.

Check 7: Docker (optional — only needed for Container builds)

Docker is only required if you’re using --build Container. CodeZip builds (the default) don’t need Docker locally — they use AWS CodeBuild.

If Docker not running:

• macOS: Start Docker Desktop
• Linux: sudo systemctl start docker

Alternatives to Docker: AgentCore also supports Podman and Finch.

Summary output format

Report results as a clear checklist:

Output

• Checklist of all prerequisites with pass/fail status
• Exact fix command for each failing check
• Clear indication of what’s blocking vs. what’s optional
• Pointer to agents-get-started skill when environment is healthy