Amber Example App

Start The App

Prerequisites:

• Python 3.11+
• the Amber runtime package
• app dependencies from requirements.txt

This app loads environment variables from .env, so put any local settings there if needed.

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

Install the app and Amber runtime dependencies:

pip install -r requirements.txt
pip install amber-runtime

Start the API in one terminal:

uv run uvicorn main:app --port 8003

Start the worker in another terminal:

source .venv/bin/activate
uv run python -m amber.worker main:agent_runtime

Open http://localhost:8003 after both processes are running.

Start The Local Dashboard

The local app UI and the Amber dashboard are separate:

• app UI: http://localhost:8003
• Amber dashboard: http://127.0.0.1:8765/admin

Make sure .env includes DB_URL, then start the dashboard in another terminal:

source .venv/bin/activate
amber dashboard dev

The local dashboard runs without Cognito or AWS.

Error Demo

Use account-research-error-demo to show durable debugging with forked workflows.

Story:

• the workflow runs several research subagents
• it sends the AE brief email as an irreversible side effect
• for enterprise accounts it enters a rare deep-scan branch
• that deep scan fails with a generic ConnectionError

In the launcher UI, enable Fail deep scan on rate limit to force the failure path.

Demo Flow

1. Naive run: the email sends, then the deep scan fails.
2. Fork 1: uncomment the DEMO FORK 1 line in user_agents/account_research_error_demo.py to log the real throttle cause.
3. Fork 2: uncomment the DEMO FORK 2 line in user_agents/account_research_error_demo.py to add backoff so the forked run succeeds.

Notes:

• restart the worker after changing a lever
• earlier research steps and the email send should not replay on forks