Step 0

Setup & Installation

On this page

What You’ll Need

Before starting the exercises, set up your development environment. The recommended approach is Dev Container / GitHub Codespaces — everything is pre-configured.

Prerequisites

Requirement	Details
Azure subscription	With permissions to create or access an Microsoft Foundry project
Foundry project	A deployed chat model (e.g. `gpt-4.1-mini`) accessible via the project endpoint
Bing Search connection	Grounding with Bing Search connection configured in the Foundry project (required for Exercises 2, 4, 5, 6)
Azure CLI	Installed and authenticated — `az login`
Dev Container / Codespaces	Recommended runtime (Python 3.11+, all tooling pre-configured)
Git & GitHub account	To clone the repository

[!TIP] Don’t have a Foundry environment yet? See docs/setup-foundry.md — a step-by-step guide that provisions everything (Foundry account + project, gpt-4.1-mini deployment, Bing Grounding connection, optional Azure OpenAI for Demo 6) via az CLI in ~30 minutes. Validated May 6, 2026 against agent-framework-foundry==1.2.2 for ~$0.50.

Step 1: Clone and Open in Dev Container

git clone https://github.com/shinyay/getting-started-with-agent-framework.git
cd getting-started-with-agent-framework

Then open in VS Code and select “Reopen in Container”, or launch via GitHub Codespaces.

[!TIP] The Dev Container includes Python 3.11, Azure CLI, Node.js (for MCP), and all pip dependencies pre-installed.

Step 2: Install Dependencies

Inside the Dev Container terminal:

pip install -r requirements.txt

[!IMPORTANT] This repository locks Agent Framework to pre-release 1.2.2 (latest stable) for reproducibility. Do not upgrade unless the workshop materials are updated accordingly.

Step 3: Authenticate with Azure

az login --use-device-code

Verify the correct subscription is active:

az account show --query "{name:name, id:id}" -o table

Step 4: Configure Environment Variables

Copy the example and fill in your values:

cp .env.example .env

Edit .env with the required variables:

Variable	Required	Description
`FOUNDRY_PROJECT_ENDPOINT`	✅	Foundry project endpoint (e.g. `https://<account>.services.ai.azure.com/api/projects/<project-id>`)
`FOUNDRY_MODEL`	✅	Model deployment name from Foundry → Models + endpoints (e.g. `gpt-4.1-mini`)
`BING_CONNECTION_ID`	✅ (Ex 2+)	Grounding with Bing Search connection ID from the Foundry project

[!NOTE] Fill-only .env pattern: Scripts in this repository load .env explicitly and only fill environment variables that are unset or empty. Existing values (e.g. from Codespaces secrets) are never overwritten.

Optional Variables (for Azure OpenAI entities)

These are only needed if you want to run the entities/ai_genius_workflow/:

Variable	Description
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI endpoint
`AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`	Chat model deployment name
`AZURE_OPENAI_API_KEY`	API key (if using key-based auth)

Step 5: Verify the Setup

Run Exercise 1’s reference solution to confirm everything works:

python src/demo1_run_agent.py

✅ Expected: The agent responds to a built-in prompt. If you see a response, your environment is ready!

Troubleshooting

Symptom	Likely Cause	Fix
`DefaultAzureCredential` or auth errors	Azure CLI session expired	Run `az login --use-device-code`
`DNS resolution failed` / timeout	Foundry endpoint unreachable	Check `FOUNDRY_PROJECT_ENDPOINT` value
`Model deployment not found`	Deployment name mismatch	Confirm `FOUNDRY_MODEL` in Foundry
Web search errors	Bing connection not configured	Set `BING_CONNECTION_ID` in `.env`
`npx: command not found`	Node.js missing	Use the Dev Container (includes Node.js)
Port 8080 in use (Exercise 6)	Another process on port	Set `DEVUI_PORT=<other-port>` in `.env`
`.env` values ignored	Codespaces empty-string vars	Scripts use fill-only pattern (fill unset/empty only)

Ready to Start!

Your environment is configured. Head to Exercise 1 → to run your first agent!

← → to navigate between steps