Task 1 — Create a Foundry IQ knowledge agent and connect from code

Part of the Integrate agents with enterprise knowledge and Microsoft 365 lab. New here? Start with Getting started.

Set up (start here): This task needs a Foundry project (with a deployed model) and the starter code. If you haven’t already, complete Getting started to create your project, clone the code, and set PROJECT_ENDPOINT and MODEL_DEPLOYMENT_NAME in Python/.env. Then, from the Labfiles/B-integrate-agents-with-enterprise-knowledge-and-m365 folder, verify you’re ready:

python setup/check_env.py --task 1

Continuing from a previous task? If your project, virtual environment, and .env are already set, you can skip the setup and go straight to Create an agent below.

You’ll build the Tailwind Traders staff knowledge assistant: an agent grounded on the company’s internal documents (store operations, product catalog, returns and rentals, suppliers) using Foundry IQ, then connect to it from a Python app that controls each knowledge lookup with an approval step.

What is Foundry IQ?

Foundry IQ connects an agent to a knowledge base — a searchable index built from your own documents backed by Azure AI Search. When the agent needs facts, it performs agentic retrieval against that knowledge base and cites what it finds. You can require approval before each lookup so your application reviews and controls every knowledge-base access.

Learn more →

Create an agent

If you created the tailwind-knowledge-agent during Getting started, open it now (Build → Agents → tailwind-knowledge-agent) and skip to Configure your data and Foundry IQ. Otherwise:

On the home page, select the Build tab, then on the Agents tab select Create agent.
Create your agent with the name tailwind-knowledge-agent.

When creating an agent, it deploys the default model (like gpt-5). Once your agent is created, you’ll see the agent playground with that default model automatically selected for you.

Configure your data and Foundry IQ

Now you’ll configure your agent to use Foundry IQ to search the Tailwind Traders knowledge base.

First, give your agent the following instructions:

 You are the Tailwind Traders staff knowledge assistant, specializing in our outdoor-gear
 products, store operations, returns and rentals, and suppliers. You must ALWAYS search the
 knowledge base to answer questions about our products, policies, or procedures. Provide
 detailed, accurate information and always cite your sources.
 If you don't find relevant information in the knowledge base, say so clearly.

Select Save to save your current agent configuration.
Then, in the Knowledge section, expand the Add dropdown, and select Connect to Foundry IQ.
In the Foundry IQ setup window, select Connect to an AI Search resource and then Create new resource which should open up a dialog to create the resource.
Create a search resource with the default settings:
- Resource name: A globally unique name
- Subscription: Your Azure subscription
- Resource group: Use the same resource group as your project
- Region: The same location as your project
- Pricing tier: Free if available, otherwise choose Basic

Now you’ll upload the Tailwind Traders knowledge documents to connect to with Foundry IQ.

Download the sample knowledge documents. These are the Markdown files in the starter code under Labfiles/B-integrate-agents-with-enterprise-knowledge-and-m365/Python/data/:
- tailwind-store-operations.md
- tailwind-tents-catalog.md
- tailwind-backpacks-guide.md
- tailwind-camping-accessories.md
- tailwind-returns-and-rentals-policy.md
- tailwind-supplier-guide.md
Tip: You already have these locally from Getting started. If you’d rather download them directly, browse to the data folder in the repository and save each file.
Open a new tab and navigate to the Azure portal at https://portal.azure.com. In the top search bar, search for Storage accounts and select Storage accounts from the services section.
Create a storage account with the following settings:
- Subscription: Your Azure subscription
- Resource group: Use the same resource group as your project
- Storage account name: A unique storage account name
- Region: The same location as your project
- Primary service: Azure Blob Storage or Azure Data Lake Storage
- Performance: Standard
- Redundancy: Locally-redundant storage (LRS)
Once created, go to the storage account you created and select Upload from the top bar.
In the Upload blob blade, create a new container named tailwindproducts.
Browse for the six Tailwind Traders Markdown files from the data folder, select all of them, and select Upload.
Once your files are uploaded, navigate to the search service you created.
On the left pane, under Security + networking > Keys, select Both for API Access control and confirm the selection. Once complete, leave the Azure Portal tab open and navigate back to the Foundry portal tab and refresh the page.
Verify you are on the Knowledge page, select Create a knowledge base, choosing Azure Blob Storage as your knowledge source, then select Connect.
Configure your knowledge source with the following settings:
- Name: ks-tailwindproducts
- Description: Tailwind Traders staff knowledge base
- Storage account name: Select your storage account
- Container name: tailwindproducts
- Authentication type: API Key
- Content extraction mode: minimal
- Embedding model: Select the available deployed model, likely text-embedding-3-small
- Chat completions model: Select the available deployed model, likely gpt-5
Select Create.
On the knowledge base creation page, select the gpt-5 model from the Chat completions model dropdown, leaving the rest of the field defaults as is.
Select Save knowledge base, and then refresh your browser to verify the knowledge source status is active. If it isn’t yet, wait a minute and refresh your page until it is.
Select the back button to return to the Knowledge page, then select the Manage link next to the Connection drop-down.
Scroll down to the Connected resources, where you should see your search service. Select that row, find the Authentication section.
Select Key authentication and then select Edit authentication.
Leaving the dialog open, return to the Azure portal tab which should still be on your search service Keys page. Copy one of those keys into the dialog in Foundry and select Save.

Your Foundry IQ settings should now be complete.

Test the agent in the playground

Before connecting from code, test your agent in the portal playground.

Navigate back to your agent on the Build > Agents page, and select the agent you created.
In the agent page, you should see a playground tab selected. Find the knowledge section and add Foundry IQ, selecting the connection and knowledge base you created.
Try the following test queries to verify the agent can retrieve information from the knowledge base:
- What types of tents does Tailwind Traders offer?
- Tell me about which backpacks are available in XL.
- What is the return window for a tent?
Review the responses and notice:
- The agent provides specific information from the knowledge base
- Citations or references to the source documents may be included
- The agent stays focused on Tailwind Traders information
In the agent details page, locate and copy the following information to a notepad (you’ll need these later):
- Agent name: This is the name you created (tailwind-knowledge-agent)
- Project endpoint: Found in the project settings or home page

Configure the agent to require approval for tool calls

When you create an agent in the portal, its Foundry IQ (knowledge) tool runs without asking for approval by default. To ensure your app can review and control each knowledge base lookup, you’ll change the agent to require approval before it uses tools with the Foundry Toolkit for VS Code extension.

Note: The Foundry portal doesn’t currently expose a setting to change this approval behavior, so you’ll configure it from the Foundry Toolkit extension instead.

In Visual Studio Code, select Extensions from the left pane (or press Ctrl+Shift+X), then search the marketplace for the Foundry Toolkit for VS Code extension from Microsoft and select Install (if it isn’t already installed).

Note: The extension is currently listed as Foundry Toolkit, but some VS Code labels, commands, or older screenshots may still refer to AI Toolkit. In this lab, treat those names as referring to the same extension experience.
Select the Foundry Toolkit icon in the sidebar, and sign in to your Azure account if you’re prompted.

Note: If you’re unable to sign in with the Foundry Toolkit extension, you may need to select the Azure extension. Sign in there, then navigate back to the Foundry Toolkit to access your resources.
Under Microsoft Foundry Resources, choose Set Default Project and select the project you created earlier.
Expand the project section. Under Prompt Agents, select your tailwind-knowledge-agent agent to open the Agent Builder window.
In the Tools section, add the Azure AI Search tool, and then select the connection and knowledge base you created earlier.

Note: The agent may list more than one tool. The Foundry portal adds a Web search tool to new agents by default, so be sure to select the three dots on the Azure AI Search tool for your knowledge base rather than another tool.
In the Require approval before using tools dropdown, select Ask for approval for all tools, and save your changes if you’re prompted.

Your agent will now request approval each time it uses Foundry IQ to search the knowledge base, which the client app you complete next will handle.

Connect to your agent from code

Now you’ll complete a Python console client that talks to your agent and handles the approval flow. The starter file is provided in the Python folder.

Open the Python folder and activate the virtual environment from Getting started (.\labenv\Scripts\Activate.ps1), then continue below.

In Python/.env, make sure AGENT_NAME is set to tailwind-knowledge-agent (the default in .env.example). Save the file.
Open knowledge_agent.py and review the starter code, including:
- Import statements and configuration loading
- The send_message_to_agent() function structure
- The display_conversation_history() function
- The main program loop

Find the first TODO comment and add the following code to connect to the project, get the OpenAI client, retrieve the agent, and create a new conversation:

Tip: Be careful to maintain the correct indentation level.

 # Connect to the project and agent
 credential = DefaultAzureCredential(
     exclude_environment_credential=True,
     exclude_managed_identity_credential=True
 )
 project_client = AIProjectClient(
     credential=credential,
     endpoint=project_endpoint
 )

 # Get the OpenAI client
 openai_client = project_client.get_openai_client()

 # Get the agent
 agent = project_client.agents.get(agent_name=agent_name)
 print(f"Connected to agent: {agent.name} (id: {agent.id})\n")

 # Create a new conversation
 conversation = openai_client.conversations.create(items=[])
 print(f"Created conversation (id: {conversation.id})\n")

Find the second TODO comment inside the send_message_to_agent() function and add the following code to send messages and handle responses, including the Foundry IQ approval request:

 # Add user message to the conversation
 openai_client.conversations.items.create(
     conversation_id=conversation.id,
     items=[{"type": "message", "role": "user", "content": user_message}],
 )

 # Store in conversation history (client-side)
 conversation_history.append({
     "role": "user",
     "content": user_message
 })

 # Create a response using the agent
 response = openai_client.responses.create(
     conversation=conversation.id,
     extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
     input=""
 )

 # Check if the response output contains an MCP approval request
 approval_request = None
 if hasattr(response, 'output') and response.output:
     for item in response.output:
         if hasattr(item, 'type') and item.type == 'mcp_approval_request':
             approval_request = item
             break

 # Handle approval request if present
 if approval_request:
     print(f"[Approval required for: {approval_request.name}]\n")
     print(f"Server: {approval_request.server_label}")

     # Parse and display the arguments (optional, for transparency)
     import json
     try:
         args = json.loads(approval_request.arguments)
         print(f"Arguments: {json.dumps(args, indent=2)}\n")
     except Exception:
         print(f"Arguments: {approval_request.arguments}\n")

     # Prompt user for approval
     approval_input = input("Approve this action? (yes/no): ").strip().lower()

     if approval_input in ['yes', 'y']:
         print("Approving action...\n")

         # Create approval response item
         approval_response = {
             "type": "mcp_approval_response",
             "approval_request_id": approval_request.id,
             "approve": True
         }
     else:
         print("Action denied.\n")

         # Create denial response item
         approval_response = {
             "type": "mcp_approval_response",
             "approval_request_id": approval_request.id,
             "approve": False
         }

     # Add the approval response to the conversation
     openai_client.conversations.items.create(
         conversation_id=conversation.id,
         items=[approval_response]
     )

     # Get the actual response after approval/denial
     response = openai_client.responses.create(
         conversation=conversation.id,
         extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
         input=""
     )

After you’ve added the code, save the file.
Review how the code uses the conversations API to manage interactions with your agent, where:
- A conversation is created and tracked by its ID
- User messages are added to the conversation using conversations.items.create()
- Responses are generated using responses.create() with an agent reference
- Approval handling: When the agent needs to access Foundry IQ, it returns an mcp_approval_request in the response output
- The code prompts you to approve or deny the action before proceeding
- After approval/denial, an mcp_approval_response is added to the conversation and a new response is generated

Test the integration

Now you’ll run your application and test the agent’s ability to retrieve information from the knowledge base.

In the terminal (in the Python folder), sign into Azure:
```
 az login
```
Note: In most scenarios, just using az login will be sufficient. However, if you have subscriptions in multiple tenants, you may need to specify the tenant by using the –tenant parameter.
When prompted, complete the sign-in process, selecting the subscription containing your Foundry resource if prompted.
Run your application:
```
 python knowledge_agent.py
```
When the application starts, test the agent with the following queries:

Query 1 - Product categories:
```
 What types of outdoor products does Tailwind Traders offer?
```
When prompted for approval, type yes to allow the agent to search the knowledge base. Observe how the agent retrieves information from multiple documents.

Query 2 - Store policy:
```
 What is the return window for tents and how do gear rentals work?
```
Approve the request and notice how the agent provides specific details from the returns and rentals policy.

Query 3 - Product comparison:
```
 What's the difference between your daypacks and expedition backpacks?
```
Approve the request and see how the agent synthesizes information from the backpacks guide.

Query 4 - Supplier and restock:
```
 When should we reorder tents, and who is our tent supplier?
```
Approve the request and observe the agent answering from the supplier guide.

Query 5 - Follow-up question:
```
 What are our store's core hours?
```
Notice how the agent maintains conversation context and answers from the store operations doc.
Type history to view the complete conversation history.
Type quit when you’re done testing.

✅ Checkpoint: You’ve created and grounded an enterprise-knowledge agent with Foundry IQ, required approval before each knowledge lookup, and connected to it from code — handling the approval flow yourself. That’s the Core of this lab. Everything below is optional.

Optional: run the same agent as a web chat app

The same grounded agent can be served through the shared Tailwind Traders web chat window. From the Python folder, run:

python knowledge_chat_app.py

A browser opens at http://localhost:7860 with the Tailwind Traders Staff Knowledge Assistant. This variant auto-approves the Foundry IQ knowledge tool so the chat stays smooth. Ask it the same questions as above. Close the tab and press Ctrl+C to stop it.

Fast-forward: If you’d rather ground an agent in code instead of the portal, run python setup/bootstrap_agent.py from the Python folder. It creates tailwind-knowledge-agent, grounds it on the six knowledge docs with File Search, and writes AGENT_NAME to .env. The client code you run against it is identical.

When you’re finished, enter deactivate to exit the virtual environment.

Next (optional): Task 2 — Publish to Microsoft Teams · Task 3 — Publish to Microsoft 365 Copilot · Task 4 — Work IQ