Local Development

The dev command runs your agent locally for testing before deployment.

Starting the Dev Server

# Start dev server (auto-selects agent if only one)
agentcore dev

# Specify agent
agentcore dev --runtime MyAgent

# Custom port
agentcore dev --port 3000

# Non-interactive mode (logs to stdout)
agentcore dev --logs

Invoking Local Agents

Start the dev server in one terminal, then send prompts from another:

# Terminal 1: start the dev server
agentcore dev --logs

# Terminal 2: send prompts
agentcore dev "What can you do?"
agentcore dev "Tell me a story" --stream
agentcore dev "Hello" --runtime MyAgent

Environment Setup

Python Virtual Environment

The dev server automatically:

1. Creates .venv if it doesn't exist
2. Runs uv sync to install dependencies from pyproject.toml
3. Starts uvicorn with your agent

TypeScript Agents

TypeScript agents (Strands-only) use Node 22 and tsx for the dev loop:

1. Runs npm install on first scaffold to populate node_modules/ from package.json
2. Starts the agent with npx tsx watch main.ts — file changes reload automatically
3. No compile step is required; tsx executes .ts sources directly

Set AGENTCORE_SKIP_INSTALL=1 to skip npm install if you want to manage dependencies yourself.

API Keys

For non-Bedrock providers, add keys to agentcore/.env.local:

AGENTCORE_CREDENTIAL_{projectName}OPENAI=sk-...
AGENTCORE_CREDENTIAL_{projectName}ANTHROPIC=sk-ant-...
AGENTCORE_CREDENTIAL_{projectName}GEMINI=...

Debugging

Log Files

Logs are written to agentcore/.cli/logs/:

agentcore/.cli/logs/
├── dev/           # Dev server logs
└── invoke/        # Invocation logs with request/response

Verbose Output

# Dev server with stdout logging
agentcore dev --logs

Common Issues

Port already in use:

agentcore dev --port 8081

Missing dependencies:

cd app/MyAgent
uv sync

Hot Reload

The dev server watches for file changes and automatically reloads. Edit your agent code and the changes take effect immediately.

Container Agents

For container agents, the dev server builds a Docker image and runs it with your source directory mounted as a volume. Changes to your code are picked up by uvicorn's --reload inside the container — no image rebuild needed.

See Container Builds for full details on container development.

Dev vs Deployed Behavior

Aspect	Local Dev	Deployed
API Keys	.env.local	AgentCore Identity service
Memory	Not available	AgentCore Memory service
Gateways	Env vars from deployed state	CDK-injected env vars
Networking	localhost	Public

Memory requires deployment to test fully. For local testing, you can mock these dependencies in your agent code.

Gateway Environment Variables

When you have deployed gateways, agentcore dev automatically injects gateway environment variables into your local agent process. This lets your local agent connect to real deployed gateways during development.

The dev server reads deployed-state.json and agentcore.json to generate:

AGENTCORE_GATEWAY_{NAME}_URL=https://{gateway-id}.gateway.agentcore.{region}.amazonaws.com
AGENTCORE_GATEWAY_{NAME}_AUTH_TYPE=NONE|AWS_IAM|CUSTOM_JWT

The gateway name is uppercased with hyphens replaced by underscores. For example, a gateway named my-gateway produces:

AGENTCORE_GATEWAY_MY_GATEWAY_URL=https://...
AGENTCORE_GATEWAY_MY_GATEWAY_AUTH_TYPE=NONE

Requirements

Gateway env vars require a prior deployment — the dev server reads the gateway URLs from deployed-state.json, which is populated by agentcore deploy. If you haven't deployed yet, no gateway env vars will be set.

Workflow

# 1. Add a gateway and target
agentcore add gateway --name my-gateway
agentcore add gateway-target --name my-tools --type mcp-server \
  --endpoint https://mcp.example.com/mcp --gateway my-gateway

# 2. Deploy to create the gateway
agentcore deploy -y

# 3. Run locally — gateway env vars are injected automatically
agentcore dev

Your agent code reads these env vars to connect to the gateway. The agent templates generated by the CLI already include this wiring.