This is the code companion for the Microsoft IQ Deep Dive with Python video series.

This repository includes multiple Jupyter notebooks and Microsoft Agent Framework agents that use Foundry IQ, Web IQ, Work IQ, Fabric IQ, or a combination.

All of the infrastructure for deployment is included in the repository, using the Azure Developer CLI. The infrastructure-as-code (Bicep files) will create gpt-5.4 and text-embedding-3-large deployments, Azure AI Search, storage, monitoring, and an optional Fabric capacity. A sequence of scripts prepares Search data, creates Search knowledge bases, and seeds the Fabric lakehouse.

• Azure account requirements
• Getting started
  • GitHub Codespaces
  • VS Code Dev Containers
  • Local environment
• Deploying to Azure
  • Enable Fabric IQ
  • Enable Work IQ retrieval for Azure AI Search
  • Enable the hosted Foundry IQ Work IQ agent
  • Enable the hosted Work IQ toolbox agent
  • Seed sample mailbox data
• Run the notebooks
• Run and invoke the agents
• Resources

In order to run all of the examples, you will need a tenant with multiple licenses and permissions. However, even if you do not have all of these permissions, you may be able to run some of the examples.

• An Azure subscription with permission to create resources and role assignments
• Quota in one region for gpt-5.4, and text-embedding-3-large
• For Fabric IQ notebooks: A Fabric-capable tenant and a Fabric/Power BI license (or active Fabric trial), with permission to create an F2 capacity
• For Web IQ notebook: Access to the private preview with an assigned WEB_IQ_KEY
• For Work IQ notebooks and agents: A Microsoft 365 Copilot license for each caller, a tenant enabled for Work IQ, and a Global Administrator for the one-time Entra app registration and admin consent

You have a few options for getting started with this repository. The quickest way to get started is GitHub Codespaces, since it will setup everything for you, but you can also set it up locally.

You can run this repository virtually by using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:

1. Open the repository (this may take several minutes):

   

2. Open a terminal window

3. Continue with the steps to run the examples

A related option is VS Code Dev Containers, which will open the project in your local VS Code using the Dev Containers extension:

1. Start Docker Desktop (install it if not already installed)

2. Open the project:

   

3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.

4. Continue with the steps to run the examples

The dev container includes a Redis server, which is used by the agent_history_redis.py example.

1. Make sure the following tools are installed:

   • Python 3.12+
   • uv
   • Azure Developer CLI with the azure.ai.agents and azure.ai.connections extensions available
   • Git

2. Clone the repository:

   git clone https://github.com/microsoft/iqdeepdive/
   cd iqdeepdive

3. Install the dependencies:

   uv sync

1. Login to Azure:

   azd auth login

   For GitHub Codespaces users, if the previous command fails, try:

    azd auth login --use-device-code

2. Create an azd environment:

   azd env new

   It will prompt you for an environment name (like "iqdeepdive"), a subscription from your Azure account, and a location.

3. Every optional service is off by default. Enable the ones you have access to now, since they are read during provisioning:

   # Fabric IQ: F2 capacity, plus the lakehouse, ontology, graph, semantic model, and Data Agent
   azd env set ENABLE_FABRIC_CAPACITY true
   azd env set ENABLE_FABRIC_ITEMS true
   
   # Work IQ knowledge base and toolbox, used by agent-toolbox-foundryiq-workiq
   azd env set ENABLE_WORK_IQ_KB_TOOLBOX true
   
   # Work IQ Entra app and toolbox, used by agent-toolbox-workiq
   azd env set ENABLE_WORK_IQ true

   Each flag has prerequisites described in its own section: Fabric IQ, Work IQ retrieval for Azure AI Search, the hosted Foundry IQ Work IQ agent, and the hosted Work IQ toolbox agent. You can also set any of these later and re-run azd provision.

4. Provision the Azure resources:

   azd provision

5. Once the resources are provisioned, you should now see a local .env file with all the environment variables needed to run the scripts.

6. To delete the resources, run:

   azd down

The Fabric IQ notebooks need a Fabric workspace with a lakehouse, ontology, product review graph, web analytics semantic model, and a published Fabric Data Agent. Fabric is opt-in and controlled by two independent flags, one per layer:

• ENABLE_FABRIC_CAPACITY (default false) creates an F2 Fabric capacity in Bicep. Leave it false to use a workspace you already manage.
• ENABLE_FABRIC_ITEMS (default false) runs the postprovision steps that create the Fabric items: the lakehouse, ontology, product review graph, web analytics lakehouse, semantic model, Power BI report, Fabric Data Agent, and Fabric IQ toolbox. It requires either FABRIC_CAPACITY_ID or FABRIC_WORKSPACE_ID to be set, and fails early with a clear message when neither is present.

To create a capacity and all of the Fabric items:

azd env set ENABLE_FABRIC_CAPACITY true
azd env set ENABLE_FABRIC_ITEMS true
azd provision

To use a workspace you already manage, set FABRIC_WORKSPACE_ID in .env and create only the items:

azd env set ENABLE_FABRIC_ITEMS true
azd provision

To skip Fabric entirely, leave both flags unset. Set FABRIC_ONTOLOGY_ID and FABRIC_GRAPH_ID in .env before running the Fabric IQ notebooks when you manage those items separately.

The Fabric Data Agent is published over three complementary sources. The ontology owns product, category, supplier, store, and inventory facts; the product review graph owns reviewers, reviews, features, and feature-level sentiment; the Direct Lake semantic model owns website traffic and conversion measures. Product SKU is the shared key between the ontology and the graph. Provisioning selects all seven semantic model tables before publishing the Data Agent.

Provisioning writes the generated identifiers and portal links to .env:

The foundryiq-workiq.ipynb notebook and the Work IQ knowledge base use a Work IQ knowledge source in Azure AI Search. This preview is disabled by default and must be approved by Microsoft. An identity with Owner or Contributor on the subscription must register the preview feature and then re-register the Search resource provider:

az feature register \
  --namespace Microsoft.Search \
  --name EnableFoundryIQWithWorkIQ \
  --subscription "<subscription-id>"
az provider register \
  --namespace Microsoft.Search \
  --subscription "<subscription-id>"

A Microsoft Entra administrator must also submit the Work IQ access request form. The subscription role holder and Entra administrator can be different people. Wait for Microsoft to approve the request before running the Work IQ notebooks. See Request access to Work IQ retrieval for the current requirements.

Enable the Work IQ knowledge-base and Toolbox creation hook, then rerun provisioning:

azd env set ENABLE_WORK_IQ_KB_TOOLBOX true
azd provision
azd deploy agent-toolbox-foundryiq-workiq
azd ai agent invoke agent-toolbox-foundryiq-workiq \
  --new-session --new-conversation \
  "Search my recent emails for Professional Claw Hammer and summarize requested actions. Use the knowledge base and its Work IQ source."

Postprovision creates workiq-knowledge-source, combines it with the shared HR and health index sources in multisource-workiq-knowledge-base, and publishes workiq-knowledge-tools. The notebook foundryiq-workiq.ipynb remains an independent walkthrough of the same Search configuration and is not required to deploy the agent.

The dedicated workiq-kb-mcp-connection must target the same knowledge-base MCP URL used by the Toolbox tool. Do not reuse kb-mcp-connection, whose target is contoso-company-kb-minimal. Toolbox uses the matching Foundry IQ connection to authenticate Search with the project managed identity and emit the signed-in user's Search-scoped token as x-ms-query-source-authorization for Work IQ retrieval. Invoke this agent through its deployed endpoint: local runs do not receive the hosted platform's x-agent-foundry-call-id, so Toolbox cannot resolve the signed-in caller for Work IQ retrieval.

Work IQ setup is opt-in because its first run requires a Global Administrator and creates a tenant app registration. Authenticate azd as that administrator, enable Work IQ, and rerun provisioning:

az ad sp create --id fdcc1f02-fc51-4226-8753-f668596af7f7
azd env set ENABLE_WORK_IQ true
azd provision

The postprovision helper creates or reuses the Work IQ service principal, creates a single-tenant Entra application with delegated WorkIQAgent.Ask, grants admin consent, creates the OAuth2 RemoteA2A connection, adds Foundry's returned callback URI to the application, and publishes work-iq-tools. The generated client secret is sent directly to the connection and is not written to .env.

Admin consent allows the application to request WorkIQAgent.Ask; it does not authorize individual users. On a caller's first Work IQ request, the agent returns an oauth_consent_request containing a short-lived sign-in link. That user opens the link once and then retries the request. Each caller must complete this delegated OAuth authorization with their own Microsoft 365 identity.

To test Work IQ with predictable content, sign in to Outlook as the test user and send the following three fixture messages to that same user's email address:

• Urgent: Professional Claw Hammer out of stock at Seattle store
• RE: Weekly inventory report - Seattle flagged
• Customer escalation - hammer unavailable again

Use the subject and body from each fixture. Because Outlook cannot impersonate the named colleague, prepend Forwarded message from <name>, <role> to the body rather than attempting to change the sender. Verify that all three messages appear in the test user's Inbox, then try:

Check my recent emails for messages about the Professional Claw Hammer. Summarize what colleagues
are saying and what actions have been requested.

Automated seeding through Microsoft Graph requires a dedicated Entra application with the admin-consented Mail.Send application permission. That broad permission is not granted by this project, so manual seeding is the recommended setup for a self-deployed test environment.

Install the notebook kernel into the root environment:

uv sync --locked --all-groups
uv pip install --python .venv/bin/python -r notebooks/requirements.txt

Then open notebooks/ in VS Code and select a notebook. Each one is independent, so you can run them in any order, as long as you have the resources necessary.

Knowledge base notebooks, which build a Foundry IQ knowledge base over different kinds of knowledge source:

Endpoint notebooks, which skip the knowledge base and call a service endpoint directly:

The repository includes a .mcp.json file that registers the Fabric IQ ontology MCP server for local tool discovery. The checked-in URL uses placeholder values for the workspace and ontology IDs. After provisioning, replace the placeholder URL with the value written to your local .env file.

On macOS or Linux, use the values from .env to replace the placeholders in .mcp.json in place:

WORKSPACE_ID=$(grep '^FABRIC_WORKSPACE_ID=' .env | sed "s/^FABRIC_WORKSPACE_ID='\(.*\)'/\1/")
ONTOLOGY_ID=$(grep '^FABRIC_ONTOLOGY_ID=' .env | sed "s/^FABRIC_ONTOLOGY_ID='\(.*\)'/\1/")
sed -i '' "s/{FABRIC_WORKSPACE_ID}/${WORKSPACE_ID}/g" .mcp.json
sed -i '' "s/{FABRIC_ONTOLOGY_ID}/${ONTOLOGY_ID}/g" .mcp.json

On Windows, use PowerShell to read .env and rewrite .mcp.json:

$workspaceId = (Get-Content .env | Where-Object { $_ -match "^FABRIC_WORKSPACE_ID='(.+)'" } | ForEach-Object { $matches[1] })
$ontologyId = (Get-Content .env | Where-Object { $_ -match "^FABRIC_ONTOLOGY_ID='(.+)'" } | ForEach-Object { $matches[1] })
$mcpJson = Get-Content .mcp.json | ConvertFrom-Json
$mcpJson.mcpServers."fabric-iq-ontology".url = "https://api.fabric.microsoft.com/v1/mcp/dataPlane/workspaces/$workspaceId/items/$ontologyId/ontologyEndpoint"
$mcpJson | ConvertTo-Json -Depth 4 | Set-Content .mcp.json

When you run a notebook, select the .venv/bin/python virtual environment.

Provisioning creates two knowledge bases over the same HR and health sources: contoso-company-kb-low uses low reasoning effort and the configured Azure OpenAI model for query planning, while contoso-company-kb-minimal uses minimal reasoning effort and is extractive, so it configures no model. The notebooks create their own knowledge bases and are unaffected by these.

Start any of the agents locally, and test them with either the local playground or CLI:

azd ai agent run agent-foundryiq-api
azd ai agent invoke --local "What benefits are available, and when do I need to enroll?"

azd ai agent run agent-foundryiq-mcp
azd ai agent invoke --local "What benefits are available, and when do I need to enroll?"

azd ai agent run agent-toolbox-foundryiq
azd ai agent invoke --local "What benefits are available, and when do I need to enroll?"

azd ai agent run agent-toolbox-workiq
azd ai agent invoke --local \
  "Check my recent Teams chats for messages about the Professional Claw Hammer. Summarize what colleagues are saying and what actions have been requested."

You can also invoke the deployed versions. You may want to re-deploy before invoking, if you've made any changes:

azd deploy agent-foundryiq-api
azd ai agent invoke agent-foundryiq-api "What benefits are available, and when do I need to enroll?"

azd deploy agent-foundryiq-mcp
azd ai agent invoke agent-foundryiq-mcp "What benefits are available, and when do I need to enroll?"

azd deploy agent-toolbox-foundryiq
azd ai agent invoke agent-toolbox-foundryiq "What benefits are available, and when do I need to enroll?"

azd deploy agent-toolbox-foundryiq-workiq
azd ai agent invoke agent-toolbox-foundryiq-workiq \
  --new-session --new-conversation \
  "Search my recent emails for Professional Claw Hammer and summarize requested actions. Use the knowledge base and its Work IQ source."

azd deploy agent-toolbox-workiq
azd ai agent invoke agent-toolbox-workiq \
  --new-session --new-conversation \
  "Check my recent Teams chats for messages about the Professional Claw Hammer. Summarize what colleagues are saying and what actions have been requested."

Direct source deployment is used because the final agent requires no custom OS packages. Foundry's remote build resolves each agent folder's pyproject.toml and uv.lock, avoiding an unnecessary container registry and image-build path.

The IQ workloads:

• What is Foundry IQ?
• What is Fabric IQ?
• Work IQ MCP tool reference

Foundry IQ knowledge bases and agentic retrieval:

• Agentic retrieval overview
• What is a knowledge source?
• Set the retrieval reasoning effort, which explains the difference between the low and minimal knowledge bases created here
• Query a knowledge base via API or MCP
• Create a Work IQ knowledge source
• Create a Fabric Ontology knowledge source

Fabric items used by the Fabric IQ notebooks:

• Fabric data agent concepts
• Direct Lake overview

Building and deploying the agents:

• Microsoft Agent Framework
• Azure Developer CLI
• Mastering Foundry Toolbox
• Model Context Protocol