Agentic AI Workshop - Setup instructions

Please complete these Setup instructions, and run the Test notebooks (linked at the bottom) to confirm everything is ready for the workshop.

If you're looking at this in VS Code, please right click on the file name README.md in the File Explorer on the left and select 'Open Preview' to see it with formatting!

Each step starts with the short version. If you'd like more detail, expand the Step by step section underneath it.

Part 1: Initial setup

1.1 Install VS Code

Download and install Visual Studio Code from code.visualstudio.com. If you already have it, you're done with this step.

Step by step

Windows

1. Go to code.visualstudio.com and click Download for Windows.
2. Run the downloaded installer (VSCodeUserSetup-...exe).
3. Accept the defaults and click through the installer. Leave Add to PATH checked.
4. When it finishes, VS Code will launch.

Mac

1. Go to code.visualstudio.com and click Download for macOS.
2. Open the downloaded .zip file (it may unzip automatically).
3. Drag Visual Studio Code.app from your Downloads folder into your Applications folder.
4. Open it from Applications (the first time, macOS may ask you to confirm - click Open).

1.2 Open a Terminal in VS Code

Open VS Code, then open a terminal with the menu Terminal > New Terminal (or press Ctrl+` - that's the backtick key, works on both PC and Mac).

A panel appears at the bottom of the window with a blinking cursor - this is a command line running inside VS Code, and it's where you'll type the commands in the next steps. On Windows it's usually PowerShell; on Mac it's zsh. Either is fine - all the commands below work in both.

1.3 Check that git is installed

In the terminal, run:

git --version

If you see a version number (e.g. git version 2.45.0), you're set - skip to 1.4. If not, install it:

• Windows: winget install --id Git.Git -e --source winget
• Mac: run git --version again and macOS will offer to install its developer tools - click Install.

Step by step

Windows

1. In the VS Code terminal, type git --version and press Enter.
2. If you see an error like git is not recognized, install git by running:

   winget install --id Git.Git -e --source winget
   

   (winget is Microsoft's package manager and comes built in to Windows 10 and 11.)
3. When it finishes, close VS Code completely and reopen it - this refreshes the terminal so it can find git.
4. Open a new terminal (step 1.2) and run git --version again to confirm you see a version number.

Mac

1. In the VS Code terminal, type git --version and press Enter.
2. If git isn't installed, macOS pops up a dialog offering to install the Command Line Developer Tools. Click Install, accept the license, and wait for it to finish (a few minutes).
3. Run git --version again to confirm you see a version number.

1.4 Clone this repository

In the terminal, run:

git clone https://github.com/ed-donner/workshop

Step by step

1. "Cloning" downloads a copy of this project to your computer.
2. The terminal starts in your home folder by default, which is a fine place for it. If you prefer to keep projects somewhere specific (like a projects folder), move there first with cd, e.g. cd projects.
3. Run:

   git clone https://github.com/ed-donner/workshop
   

4. This creates a folder called workshop containing the project. Note where it is - you'll open it in the next step. To see the full location, run cd workshop and then pwd.

1.5 Open the workshop project in VS Code

Open the workshop folder you just cloned: File > Open Folder..., select the workshop folder, and click Open (on Mac the button says Open; the menu item may say Open...).

You'll know it worked when the Explorer sidebar on the left shows WORKSHOP in capital letters at the top.

Step by step

1. In VS Code, click File in the menu bar, then Open Folder... (on Mac this may appear as Open...).
2. Navigate to where you cloned the project in step 1.4 - your home folder unless you chose somewhere else. Home is C:\Users\<your name> on Windows, or /Users/<your name> on Mac (in the Mac dialog, press Cmd+Shift+H to jump straight to your home folder).
3. Click the workshop folder once to select it (don't double-click into a folder inside it), then click Select Folder (Windows) or Open (Mac).
4. If VS Code asks "Do you trust the authors of the files in this folder?", click Yes, I trust the authors.
5. Check the Explorer sidebar on the left (the top icon that looks like two stacked files - or press Ctrl+Shift+E / Cmd+Shift+E). The very top of the panel should read WORKSHOP in capital letters.
6. If you see a different name in capitals (like your username or PROJECTS), you opened the wrong folder - go back to File > Open Folder... and make sure you select the workshop folder itself.

1.6 Install the Python and Jupyter extensions

Open the Extensions view (Ctrl+Shift+X / Cmd+Shift+X) and install Python and Jupyter, both by Microsoft. If they're already installed, you're done.

Step by step

1. In VS Code, click the Extensions icon in the left sidebar (four squares, with one detached) - or press Ctrl+Shift+X on Windows, Cmd+Shift+X on Mac.
2. In the search box at the top, type Python.
3. Find Python with Microsoft as the publisher (usually the first result) and click Install. If you see a gear icon instead of an Install button, it's already installed.
4. Now search for Jupyter, find the one published by Microsoft, and click Install.
5. Each may pull in a few companion extensions automatically (like Pylance) - that's expected.

Part 2: Python environment with uv

We use uv, a fast Python package manager. It handles everything - including installing Python itself - so this is the only tool you need.

For all of Part 2, work in a VS Code terminal (Terminal > New Terminal) with the workshop project open, so the terminal starts in the right folder.

2.1 Install uv

In the terminal, run:

uv --version

If you see a version number, skip to 2.2. If not, install uv with the default (standalone) installer from the uv installation page:

• Windows:

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

• Mac:

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

Then close and reopen VS Code, open a new terminal, and confirm uv --version works.

2.2 Update uv

uv self update

This makes sure you're on the latest version. If you just installed uv, it will say it's already up to date - that's fine. If you get an error saying self-update is not available, your uv came from a package manager like Homebrew or winget - update it the same way you installed it (e.g. brew upgrade uv).

2.3 Install the project dependencies

uv sync

Step by step

1. Make sure the terminal is in the workshop folder. If you opened the workshop project in VS Code (step 1.5), any new terminal starts there automatically - the prompt shows the folder name.
2. Run uv sync.
3. uv reads the project configuration, downloads the right version of Python if needed, creates a private environment for this project, and installs all the packages. The first run can take a minute or two.
4. When it finishes without errors, you're done. If it complains it can't find pyproject.toml, the terminal is in the wrong folder - run cd workshop (or reopen the project as in step 1.5) and try again.

2.4 Check that the environment was created

Look at the Explorer sidebar: a new folder called .venv should have appeared at the top level of the project, right under WORKSHOP.

Step by step

1. Open the Explorer sidebar (Ctrl+Shift+E / Cmd+Shift+E).
2. Under WORKSHOP, you should see a folder named .venv (it may look slightly dimmed - that's normal).
3. This folder contains the project's own private copy of Python and all its packages, created by uv sync.
4. Don't see it? Run ls in the terminal to double-check, and make sure step 2.3 completed without errors in the workshop folder.

Part 3: API key

The project reads your API key from a file called .env. This file stays on your machine and holds your secret key.

3.1 Create a .env file

In the Explorer sidebar, right-click in the empty area below the files, choose New File..., and name it exactly:

.env

Step by step

1. Open the Explorer sidebar (Ctrl+Shift+E / Cmd+Shift+E).
2. Right-click in the empty space below the list of files - not on a folder - so the new file lands at the top level of the project.
3. Choose New File... from the menu.
4. Type .env and press Enter. The name starts with a dot and has nothing after "env" - not .env.txt, not env.
5. The file opens in the editor, empty. Check the Explorer: .env should sit at the top level, directly under WORKSHOP alongside the other files - not inside a folder. If it landed in the wrong place, drag it to the top level.

3.2 Add your API key

Type one line into the file, depending on which workshop you're attending:

• Claude workshop:

  ANTHROPIC_API_KEY=sk-ant-...
  

• ADK workshop:

  GOOGLE_API_KEY=AIz...
  

Replace the sk-ant-... or AIz... part with your actual key.

Step by step

1. Click into the empty .env file in the editor.
2. Type the variable name for your workshop (ANTHROPIC_API_KEY or GOOGLE_API_KEY), then =, then paste your full key.
3. Everything goes on one line: no spaces around the =, no quotes around the key.
4. Anthropic keys start with sk-ant-; Google keys start with AIz. If yours doesn't, double-check you copied the whole key.

3.3 Save the file

Press Ctrl+S (Windows) or Cmd+S (Mac). The dot on the file's tab turns into an x when it's saved.

And now - time to run some tests...

If you're part of the group that will be using Google ADK (and your team uses ADK today):

• Please double click on adk.ipynb in the File Explorer on the left and follow the instructions

If you're part of the group that will be using Claude:

• Please double click on claude.ipynb in the File Explorer on the left and follow the instructions