Step 1 · Set up

Step 1 of 8Set up

Objective

Get the project running on your machine, with your own keys, and prove it works before spending any quota.

Why this step exists

Most “it doesn’t work” problems in a workshop are environment problems, not code problems. We front-load them and give you a single command that proves the whole setup is sound.

Get the code

git clone https://github.com/dileepadev/deploying-agentic-ai-apps-workshop.git
cd deploying-agentic-ai-apps-workshop/app

The deployed application is its own uv project, so app/ is where the rest of this step happens.

Install uv

uv manages the Python version, the virtual environment, and the packages — one tool instead of four.

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Already have pipx or brew

brew install uv        # or:  pipx install uv

Then:

uv sync

That reads pyproject.toml and uv.lock, installs the exact versions this project was tested with, and creates .venv for you. You never need to activate it — uv run handles that.

Configure your secrets

cp .env.example .env

Open .env (in app/, next to pyproject.toml) and fill in three values:

Variable	Where to get it
LLM_API_KEY	https://aistudio.google.com/apikey → Create API key
SUPABASE_URL	Supabase → Connect (top of the dashboard) → Project URL
SUPABASE_SECRET_KEY	Supabase → Settings → API Keys → Secret keys → starts with sb_secret_

One more is optional, and you can add it later without changing anything else:

Variable	Where to get it	What it buys
TAVILY_API_KEY	https://app.tavily.com → free, no card	Web search, so the agent can answer questions about this week rather than only what Wikipedia has written up

Leave it blank and everything in this workshop still works — the agent researches with Wikipedia alone, and says so when asked about something recent.

Prefer a different model provider?

Gemini is the default because it’s the shortest path to a working key, but Cerebras, OpenRouter and Groq are all free without a card, and switching is three environment variables — no code change.

Follow the workshop on Gemini first — every screenshot and error message below assumes it — then see Model providers when you want to change, or when a rate limit forces the issue.

If your project only offers `anon` and `service_role`

Supabase renamed and reworked its keys: anon became the publishable key (sb_publishable_…) and service_role became the secret key (sb_secret_…). Projects created before the change may still show only the old pair, under the Legacy API Keys tab.

Those keep working until Supabase retires them at the end of 2026. Paste the service_role key into SUPABASE_SECRET_KEY and carry on — everything in this workshop behaves the same.

The secret key bypasses every database security rule

It belongs on your server and nowhere else. Never in frontend code, a screenshot, a commit, or a chat message.

.env is already in .gitignore — check that it stays there. Once a key is pushed to GitHub it is in the history forever and must be rotated.

Prove it works

Run the tests. They need no API key and no network:

uv run --extra dev pytest

.................                                   [100%]
17 passed

Then start the server:

uv run fastapi dev main.py

Expected result

Open http://localhost:8000/health. You want:

{"ok": true, "database": true, "provider": "google",
 "model": "gemini-flash-latest", "web_search": false}

Also open http://localhost:8000/docs — FastAPI generates that from your code, and you’ll use it to test the deployed version later. It follows your system’s light/dark setting: Swagger UI has had a dark theme since 5.31, and app/main.py adds the few lines that switch it on.

Install the client

The frontend is a separate Vite + React app in client/, with its own dependencies. It needs Node.js 20+ (node --version). From the repo root, in a second terminal:

cd client
npm install
npm run dev

Open http://localhost:5173. You’ll get the demo UI with Backend URL already pointing at http://localhost:8000 — leave it there for now. You won’t have anything to ask it until step 7; this is just to confirm both halves install.

Two terminals from here on

The backend runs from app/, the frontend from client/. Neither reloads the other, so keep both running while you build.

What usually goes wrong

database: false

Your SUPABASE_URL or key is wrong, or the project is paused. Free projects pause after about a week idle — open the Supabase dashboard and resume it.

You haven’t created the tables yet either — that’s step 2. database: false at this point is expected if you’ve skipped ahead.

RuntimeError: Missing environment variable: LLM_API_KEY

Working as intended — config fails loudly at startup rather than mysteriously at request time. Check .env exists in app/ and that there are no quotes around the values.

If you’re following an older copy of this workshop, the variable used to be called GEMINI_API_KEY. That name still works.

uv: command not found after installing

The installer added it to a shell profile that your current terminal hasn’t read. Open a new terminal, or source ~/.bashrc / source ~/.zshrc.

Python version errors

You don’t need to fix your system Python. uv python install 3.12 then uv sync again — uv will use its own.

What’s next

You have an environment. Now it needs somewhere to put things.

← Build overviewStep 2 · The database →