Pokédex workshop: prerequisites

Do this the day before.

You need one thing from me first: the project id for the session. I'll send it before the day. It is a Google Cloud project, and your Northwell Google account needs access to it.

I need one thing from you first: reply and tell me what operating system you're on — Windows, macOS, or Linux. That is the detail that caused most of the trouble last time. Nothing in this document assumes one OS, but I do, if nobody tells me otherwise, and half the fixes below only exist because that assumption was wrong for some of the room.

If step 2 or 3 below fails with a permission error, message me before the day, not on it. A permission error needs an admin, not a change on your machine — the network and certificate issues in step 4 are yours to fix, and that section tells you how.

1. Install the tools

Install uv first; agents-cli installs through it.

macOS / Linux:

1curl -LsSf https://astral.sh/uv/install.sh | sh
2uv tool install google-agents-cli

Then install the Google Cloud CLI from cloud.google.com/sdk/docs/install — the platform installer sets up your PATH for you. If you use Homebrew, brew install --cask google-cloud-sdk does the same thing.

Windows (PowerShell):

1powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2uv tool install google-agents-cli

Then install the Google Cloud CLI from cloud.google.com/sdk/docs/install and run its installer; it adds gcloud to PATH.

Restart your terminal after installing so the PATH changes take effect, then check all three:

1uv --version
2agents-cli --version
3gcloud --version

Close to those versions is fine. You do NOT need a specific Python installed. uv brings its own.

2. Authenticate

The agent talks to Gemini through Vertex AI, which uses Application Default Credentials. A plain gcloud auth login is not enough on its own; the --update-adc flag writes those credentials in the same step. Run both:

1gcloud config set project <session project id>
2gcloud auth login --update-adc

The second one opens a browser. Sign in with your Northwell account.

If either command errors, stop and message me.

3. Prove it works

Run the scaffold in a throwaway folder:

agents-cli scaffold create prereq-check --agent adk --prototype

Look for this line:

> ✓ Connected to project: <session project id>

Careful: the scaffold prints ✅ Success! even when auth failed. Success means the project line above, not the checkmark at the end. If you see this instead, step 2 did not take:

> ⚠️  Looks like you are not authenticated with Google Cloud.

Then open prereq-check/.env and check this line before you delete anything:

GOOGLE_CLOUD_PROJECT=<session project id>

If it says your-gcp-project-id, step 2's gcloud config set project did not take. That is the scaffold's fallback when gcloud has no project configured, and nothing warns you — the scaffold still reports success, and the failure only appears on your first question as Permission denied on resource project your-gcp-project-id. Re-run step 2 and scaffold again.

Delete the folder after.

If something fails on the day

Two failures came up in a dry run. Both are fixed on your machine in under a minute, so they are worth knowing rather than debugging live.

Permission denied on resource project your-gcp-project-id — the placeholder above. Run gcloud config set project <session project id>, then edit that same line in your project's .env to the session project id, and restart the playground. Both halves are needed: gcloud fixes the next scaffold, the .env edit fixes the project you already made.

invalid_grant: Bad Request, shown as RefreshError — your stored credentials expired or were revoked, which happens after a password change or simply after long enough. Nothing is wrong with your access. Sign in again:

gcloud auth login --update-adc

4. One network check

The agent calls PokéAPI directly. No key, no signup, but corporate networks sometimes interfere. Run this inside the prereq-check folder from step 3, before you delete it:

uv run python -c "from urllib.request import urlopen, Request; print(urlopen(Request('https://pokeapi.co/api/v2/pokemon/gengar', headers={'User-Agent':'pokedex-workshop/0.1'}), timeout=10).status)"

You want 200. Anything else, let me know before the session.

It has to be this command rather than a browser or a curl. Your browser, and most command-line tools, trust the certificates your operating system trusts. Python does not: it ships its own list. On a corporate network that inspects traffic, everything else can succeed while Python alone fails, so a check that does not go through Python proves nothing about whether the agent will run.

If it fails with CERTIFICATE_VERIFY_FAILED ... unable to get local issuer certificate, that is exactly this: your network is re-signing traffic with a company certificate that Python does not know about. Nothing is broken and it is not a permissions problem. Fix it by giving Python a list that includes your company's certificate.

macOS:

1security find-certificate -a -p /Library/Keychains/System.keychain > ~/corp-roots.pem
2security find-certificate -a -p /System/Library/Keychains/SystemRootCertificates.keychain >> ~/corp-roots.pem
3cat "$(uv run python -c 'import certifi; print(certifi.where())')" ~/corp-roots.pem > ~/workshop-ca.pem
4export SSL_CERT_FILE=~/workshop-ca.pem

Windows (PowerShell):

1$certifi = uv run python -c "import certifi; print(certifi.where())"
2$corp = "$HOME\corp-roots.pem"
3Get-ChildItem Cert:\LocalMachine\Root | ForEach-Object {
4  "-----BEGIN CERTIFICATE-----"
5  [Convert]::ToBase64String($_.RawData, 'InsertLineBreaks')
6  "-----END CERTIFICATE-----"
7} | Set-Content $corp
8Get-Content $certifi, $corp | Set-Content "$HOME\workshop-ca.pem"
9$env:SSL_CERT_FILE = "$HOME\workshop-ca.pem"

Re-run the check in the same terminal; you should now get 200. That export / $env: line only lasts for that terminal window, so either set it again on the day in the terminal you use, or add it to your shell profile to make it permanent. Tell me either way, so I know to expect it.