Connect a Foundry IQ Knowledge Base

Lab overview

File search works for a handful of documents attached to one agent. Foundry IQ is for shared knowledge. In this lab, you find a question the agent can't answer, create an Azure AI Search service on the Free tier, connect it to Foundry IQ, build a knowledge base from a new Software Request policy, and connect that knowledge base to contoso-helpdesk-agent. Then you test both knowledge paths and confirm the agent picks the right one for each question.

Why you'd do this

The file search index from lab 5 belongs to one agent. That's fine for a pilot, but the moment a second agent needs the same policies, or the documents start numbering in the hundreds, you want the knowledge to live somewhere shared and managed on its own. Foundry IQ is that layer: a knowledge base built on Azure AI Search, which is the service Microsoft's own products use for enterprise retrieval. Knowledge sources go into it once, any agent in the project can connect to it, and updating a policy means re-indexing one place rather than touching every agent that uses it.

Creating the search service yourself, rather than letting Foundry spin one up, is deliberate. You pick the tier and the region, which is where cost and data residency are decided. The Free tier is enough for a lab and a small knowledge base; in production you'd choose Basic or Standard for replicas, larger indexes, and semantic ranking. The API-key connection you'll see is the simplest way to wire it up; a managed identity is the safer choice once this leaves the lab.

Two settings in the knowledge base deserve a look. The embedding model turns document chunks into vectors so meaning can be searched rather than keywords; text-embedding-3-small is the cheap, capable default. Retrieval reasoning effort controls how hard the knowledge base works to find and rank chunks before handing them to the agent; Minimal is fast and fine for a single clear policy document, and you'd raise it when the corpus is large or questions are ambiguous.

The test at the end is the point: the agent now has two knowledge paths, and it answers the Visio question from the knowledge base and the password question from file search without being told which to use. Saving creates version 2 of the agent, so version 1 is still there if you need to roll back. For certification prep, this is grounding with your own data in AI-901 and agent tools and knowledge sources in AI-103.

Lab details

• Search Service: contoso-search-01 (Free tier, East US)
• Knowledge Source: contoso-software-ks from the Software Request policy
• Embedding Model: text-embedding-3-small
• Knowledge Base: contoso-it-kb, retrieval reasoning effort Minimal
• Agent: contoso-helpdesk-agent, version 2

Learning objectives

1. Create an Azure AI Search service and connect it to Foundry IQ.
2. Build a knowledge base from an uploaded knowledge source.
3. Connect a Foundry IQ knowledge base to an agent and save a new version.
4. Compare file search and a knowledge base as two ways to ground an agent.

Exam relevance

• AI-901 — Microsoft Azure AI Fundamentals — AI agents and their components, grounding with your own data.
• AI-103 — Developing AI Apps and Agents on Azure — create a prompt agent in Foundry Agent Service, agent instructions, tools, and versions.

How this lab fits into the project

This is lab 7 of 12 in the Contoso Knowledge Assistant project. Contoso's IT help desk fields the same policy questions all day, so over this series you'll build an AI agent that answers them from the company's own documents, then ground it, secure it, evaluate it, monitor it, and publish it to Teams. This lab gives the agent its second knowledge path, a shared Foundry IQ knowledge base built on Azure AI Search, alongside the file search it already has.

Step-by-step instructions

1. Show the gap:
   • In the Foundry portal, click Build, then click contoso-helpdesk-agent on the Agents page.
   • In the chat box, type How do I request Microsoft Visio? and click send.
   • Note that the agent says the documents don't cover it.
2. Create a free Azure AI Search service:
   • Click the Microsoft Azure browser tab.
   • In the search bar, type AI Search and select AI Search (Foundry IQ).
   • Click + Create.
   • Select rg-contoso-assistant from the Resource group dropdown.
   • Type contoso-search-01 as the Service name.
   • Open the Location dropdown and select East US.
   • Click Change Pricing Tier, click Free, and click Select.
   • Click Review + create, then Create, and wait for the deployment to complete.
3. Connect the search service to Foundry IQ:
   • Click the Foundry portal browser tab.
   • Click Knowledge in the left pane.
   • Open the Foundry IQ resource dropdown and select contoso-search-01.
   • Note that Auth Type is set to API Key, then click Connect.
4. Create the knowledge base:
   • Click Create knowledge base, then Upload files.
   • Select Contoso-Software-Request-Policy and click Open.
   • Double-click the default name and type contoso-software-ks as the knowledge source name.
   • Ensure text-embedding-3-small is selected as the embedding model, then click Create.
   • Double-click the default knowledge base name and type contoso-it-kb.
   • Leave the retrieval reasoning effort set to Minimal.
   • Click Save knowledge base, then Save.
5. Connect the knowledge base to the agent:
   • Click Agents in the left pane, then click contoso-helpdesk-agent.
   • Under the Knowledge section, click Add, then Connect to Foundry IQ.
   • Ensure the Connection field shows contoso-search-01.
   • Open the Knowledge base dropdown, select contoso-it-kb, and click Connect.
   • Click Save and note that the agent is now on version 2.
6. Test both knowledge paths:
   • Click the new chat icon, type How do I request Microsoft Visio?, and click send.
   • Note the grounded answer: a help desk ticket under Software > Request, manager approval, and about 3 business days.
   • Click the new chat icon, type What is Contoso's password expiration policy?, and click send.
   • Note that the agent still answers 120 days from the file search index.
   • Click Microsoft Foundry in the upper left to return to the home page.