Quickstart demo shows connection errors due to race condition on startup #587
Description
Description
When running any demo:* script (e.g. npm run demo:all), the Vite dev server starts in ~400ms and opens in the browser, but the Python A2A agents take significantly longer to start (installing dependencies, building packages). This causes repeated ERR_CONNECTION_REFUSED errors in the browser console as the web app tries to fetch /.well-known/agent-card.json from agents that aren't ready yet.
Steps to Reproduce
cd samples/client/lit
export GEMINI_API_KEY="..."
npm install
npm run demo:allOpen http://localhost:5173 as soon as the Vite server is ready.
Observed Behavior
Browser console shows:
:10002/.well-known/agent-card.json:1 Failed to load resource: net::ERR_CONNECTION_REFUSED
app.ts:512 Array(0)
:10002/.well-known/agent-card.json:1 Failed to load resource: net::ERR_CONNECTION_REFUSED
app.ts:512 Array(0)
:10002/.well-known/agent-card.json:1 Failed to load resource: net::ERR_CONNECTION_REFUSED
app.ts:512 Array(0)
The errors repeat because the web app attempts to reach the agent before Uvicorn has started.
A manual page refresh after the agents are running resolves the issue, but this is confusing for first-time users following the quickstart guide.
Expected Behavior
The web app should handle the case where agents aren't ready yet, for example by:
- Showing a "waiting for agent..." message instead of silently failing
- Retrying with backoff until the agent is reachable
- Delaying the shell server start until agents report healthy
Environment
- macOS
- Node.js v18+
- Python 3.13
- First run requires downloading ~132 Python packages including large ones (pyarrow 32.6MiB, grpcio 11.3MiB, etc.)