Dev Mode

Run your AI agent locally with automatic AWS credential management, hot reload, and an interactive chat interface.

serverless dev

Dev mode runs your agent on your local machine while using the deployed IAM role for AWS permissions. This lets you iterate on agent code without redeploying, while still accessing all deployed AWS resources (gateway tools, memory, Bedrock models, etc.).

Quick Start

1. Deploy your agent first (creates the IAM role and cloud resources):

serverless deploy

2. Start dev mode:

serverless dev

3. Chat with your agent -- once the agent is ready, you'll see:

Dev mode running on http://localhost:8080

Session ID: a1b2c3d4-...
Type your message and press Enter to chat with the agent.
Press Ctrl+C to stop.

You: What can you help me with?

Agent:
I'm an AI assistant that can help you with...

You:

Edit your agent code, save the file, and dev mode automatically rebuilds and restarts.

How It Works

When you run serverless dev, the framework:

1. Fetches deployed resources from CloudFormation -- IAM role ARN, gateway URL, memory ID
2. Configures IAM trust policy -- automatically adds your local identity to the role's trust policy so you can assume it
3. Obtains temporary credentials -- calls STS AssumeRole to get 60-minute credentials
4. Detects the execution mode -- Docker or Code, based on your project configuration
5. Starts the agent locally -- Docker container or Python process, with credentials and environment variables injected
6. Watches for file changes -- rebuilds/restarts automatically when source files change
7. Starts interactive chat -- readline CLI with streaming response support

serverless dev
    │
    ├── Read CloudFormation stack outputs (Role ARN, Gateway URL, Memory ID)
    ├── Update IAM trust policy for local AssumeRole
    ├── Get STS temporary credentials (60 min)
    │
    ├── [Docker Mode] Build image → Run container on port 8080
    │   OR
    ├── [Code Mode] Spawn Python process on PORT
    │
    ├── Start file watcher
    └── Start interactive chat CLI
            │
            ├── User types message
            ├── HTTP POST http://localhost:8080/invocations
            ├── Agent responds (SSE stream or JSON)
            └── Display response

Your agent runs locally and calls AWS services directly using the injected temporary credentials -- there is no tunnel or cloud proxy.

Command Options

# Auto-detects the first runtime agent
serverless dev

# Specify which agent to run (required when multiple agents are defined)
serverless dev --agent myAgent

# Use a custom port (default: 8080)
serverless dev --port 9000

# Force agents dev mode (see note below)
serverless dev --agents

The --agents flag

When your serverless.yml defines both Lambda functions and agents, serverless dev defaults to Lambda functions dev mode. Use --agents to explicitly select agents dev mode:

# This runs Lambda dev mode (default when functions exist)
serverless dev

# This runs agents dev mode
serverless dev --agents

If your configuration only has agents (no functions), agents dev mode is selected automatically.

Execution Modes

Dev mode supports two execution modes, detected automatically based on your project configuration.

Mode Detection Priority

Docker Mode

Builds a Docker image locally and runs it in a container. This is the default mode for most projects.

ai:
  agents:
    myAgent: {} # Dockerfile auto-detected

• Builds image as <service>-<agent>:local
• Maps container port 8080 to the host port
• Watches the Dockerfile directory for changes
• Rebuilds the container on file changes
• Closest match to production behavior

Code Mode (Python Only)

Runs the Python process directly without Docker. Faster startup and iteration, ideal for rapid development.

ai:
  agents:
    myAgent:
      handler: agent.py
      runtime: python3.13

• Spawns the Python process directly from the project directory
• Only watches .py files for changes
• Restarts the Python process on changes
• Virtual environment recommended for credential isolation

Important: Your handler must read the PORT environment variable:

if __name__ == "__main__":
  port = int(os.getenv('PORT', 8080))
  app.run(port=port, host='0.0.0.0')

Resource Auto-Discovery

Dev mode automatically discovers deployed cloud resources from your CloudFormation stack and injects them as environment variables. This means your local agent connects to the same gateway tools, memory, and other resources as the deployed version.

This happens automatically -- no manual configuration needed. When you run serverless dev, the framework reads the CloudFormation stack outputs and injects the values.

Credentials

Dev mode manages AWS credentials automatically through the deployed IAM role.

How It Works

1. Trust policy setup -- Dev mode adds a ServerlessAgentCoreLocalDevPolicy statement to the agent's IAM role trust policy, allowing your local AWS identity to assume the role. This handles SSO sessions, assumed roles, and regular IAM users.

2. STS AssumeRole -- Obtains temporary credentials (AccessKeyId, SecretAccessKey, SessionToken) with 60-minute expiration.

3. Auto-refresh -- When credentials have less than 10 minutes remaining and a file change triggers a rebuild, credentials are automatically refreshed.

4. Retry logic -- Credential acquisition retries up to 10 times with exponential backoff, handling IAM propagation delays.

Credential Isolation (Code Mode)

For Python code mode, a virtual environment is strongly recommended:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
serverless dev

This prevents boto3 from reading your system ~/.aws/config or SSO cache, ensuring the agent uses only the injected temporary credentials. Dev mode detects the virtual environment automatically via the VIRTUAL_ENV environment variable.

Environment Variables

Dev mode injects the following environment variables into your agent process/container:

Always Injected

Mode-Specific

Auto-Discovered (If Deployed)

User-Defined

Any variables defined in environment in your serverless.yml are also injected:

ai:
  agents:
    myAgent:
      environment:
        MODEL_ID: us.anthropic.claude-sonnet-4-20250514-v1:0
        MY_API_KEY: ${ssm:/my/api/key}

Interactive Chat

Dev mode provides a built-in CLI for chatting with your local agent.

• Prompt: Type messages at the You: prompt
• Streaming: Responses stream in real-time via Server-Sent Events (SSE)
• Sessions: Each dev mode start creates a new session ID (UUID). Sessions reset when files change and the agent rebuilds.
• Exit: Press Ctrl+C for graceful shutdown (stops container/process, cleans up)

Invocation Protocol

The chat CLI sends HTTP POST requests to your local agent:

POST http://localhost:<port>/invocations
Content-Type: application/json
Accept: text/event-stream
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-uuid>

{ "prompt": "Your message here" }

Your agent can respond with SSE streams or plain JSON.

File Watching

Dev mode monitors your source files and automatically rebuilds/restarts on changes.

Watch Behavior

• Docker mode: Watches the entire Dockerfile directory
• Code mode: Watches only .py files in the project
• Debouncing: 300ms stability threshold prevents rebuilds during file writes
• Rebuild process: Stops agent, refreshes credentials if expiring, restarts agent, resets session

Excluded Paths

The following are always excluded from file watching:

• node_modules/, .git/, .serverless/
• venv/, .venv/
• __pycache__/, *.pyc
• .pytest_cache/, .mypy_cache/, coverage/
• Test files: *_test.py, *.test.py, *.test.js, *.spec.js

Code Mode Requirements

Python Version

Dev mode converts the runtime configuration to a Python command:

If the installed Python version doesn't match the configured runtime, dev mode logs a warning.

On Windows, python.exe is used regardless of the runtime configuration.

Virtual Environment

A virtual environment is strongly recommended for code mode:

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

pip install -r requirements.txt

Dev mode detects the virtual environment via the VIRTUAL_ENV environment variable and:

• Prepends the venv bin/ directory to PATH
• Passes VIRTUAL_ENV and VIRTUAL_ENV_PROMPT to the Python process
• Provides credential isolation from system-level AWS config

File Structure

my-agent/
├── agent.py              # Entry point (handler)
├── requirements.txt      # Dependencies
├── serverless.yml        # Configuration
└── venv/                 # Virtual environment (recommended)

Troubleshooting

"Failed to gather deployed agent resources"

You must deploy the agent before using dev mode. The IAM role and cloud resources must exist:

serverless deploy

"Connection refused" when chatting

The agent is still starting up. Wait a few seconds for the container/process to initialize and begin listening on the port.

Python version mismatch warning

Dev mode detected a different Python version than configured. Install the correct version or update the runtime in serverless.yml:

# Check installed version
python3.13 --version

# Or update serverless.yml
ai:
  agents:
    myAgent:
      runtime: python3.12  # Match your installed version

Credentials fail after trust policy update

IAM trust policy changes take a few seconds to propagate. Dev mode waits 10 seconds automatically, but in rare cases you may need to retry. Dev mode retries up to 10 times with exponential backoff.

boto3 using wrong credentials (Code Mode)

If your agent uses system-level AWS credentials instead of the injected ones, activate a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
serverless dev

This isolates boto3 from ~/.aws/config and SSO session caches.

Agent crashes on file change

Dev mode does not auto-restart after crashes. Fix the issue in your code, and dev mode will rebuild automatically when you save the file.

Next Steps

• Runtime Configuration - Deployment and runtime settings
• Gateway Configuration - Custom tools via Lambda, OpenAPI, MCP
• Memory Configuration - Conversation persistence
• Browser Configuration - Web automation capabilities
• Code Interpreter - Sandboxed code execution