Skip to content

Latest commit

 

History

History
156 lines (105 loc) · 4 KB

local-development.md

File metadata and controls

156 lines (105 loc) · 4 KB

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 --agent MyAgent

# Custom port
agentcore dev --port 3000

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

Invoking Local Agents

With the dev server running, open another terminal:

# Interactive chat
agentcore invoke

# Single prompt
agentcore invoke "What can you do?"

# With streaming
agentcore invoke "Tell me a story" --stream

# Direct invoke to running server
agentcore dev --invoke "Hello" --stream

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

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 mcp.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.