Grounding with Foundry IQ

Before you start: this is a billed Azure service

• Cost and account. An Azure subscription, a Foundry project, and (for grounding) an Azure AI Search resource. Grounding creates resources that bill while they exist — a search index / vector store — plus ingestion and query costs. Cleanup is mandatory.
• Authored against the docs, not executed live. Code is written against the official docs and syntax-checked, not run during authoring. Grounding needs a recent SDK (preview 2.0.0+) and the class/parameter names move — pin your version and verify.
• Two languages, hybrid. Python-primary with .NET noted; you'll use both the portal and the SDK.

About this series

This is Part 3 of the twelve-part Microsoft Foundry series. Lab 2 built a code-defined agent that could reason and call a tool — but it didn't actually know anything about Acme. This lab fixes that: you'll ground the agent in your own documents and data so its answers are accurate and cite their sources, using Foundry IQ — Foundry's unified knowledge layer.

What you'll build

You'll give the Acme Orders assistant a knowledge base of Acme policy documents (returns, shipping, warranty) and make it answer from them:

1. File Search: upload the Acme docs into a vector store backed by Azure AI Search, and attach it to the agent.
2. Azure AI Search index: connect an existing search index for data you already maintain.
3. Foundry IQ: see how the unified knowledge layer ties these (plus SharePoint, Fabric, Azure SQL, MCP) behind one retrieval endpoint with agentic retrieval and permission enforcement.
4. Citations: read the inline citations so every answer traces back to a source.

Why this matters (the 5-minute business case)

Read this before handing the lab to your team.

Grounding is the single highest-leverage move for trustworthy enterprise AI. A raw model answers from training data — confidently, and sometimes wrongly, about your business, which it has never seen. Grounding flips that: the agent retrieves the relevant passages from your content and answers from them, with citations. It's the difference between a plausible guess and a sourced answer a customer or auditor can trust.

Three reasons this is a leadership-level concern:

1. It reduces hallucination where it matters most. The real questions — "what's the return window?", "is this under warranty?" — are exactly the ones a generic model gets wrong. Grounding ties the answer to your actual policy, so it's right and current.
2. It adds provenance. Grounded answers carry citations to the source. That's what makes output reviewable, defensible, and safe for customers and regulators. "Here's the answer and where it came from" is a different product.
3. Foundry IQ unifies your knowledge behind one endpoint. Instead of wiring a separate retrieval system per source, Foundry IQ puts File Search, Azure AI Search, SharePoint, Fabric, Azure SQL, and MCP behind one SLA-backed, permission-aware retrieval layer with agentic retrieval. You ground once, against everything.

The honest caveats:

• Grounding is only as good as retrieval. If the right passage isn't retrieved, the model can't ground on it. Chunking, the index, and clean documents matter more than the model. When a grounded answer is wrong, suspect retrieval first.
• It bills, and the index persists. Search indexes and vector stores are live resources. Track them and delete what you're not using.
• Permissions are a feature, not an afterthought. Foundry IQ can enforce user permissions on retrieval — use it, so the agent never surfaces a document the user couldn't see.

A framing for a non-technical stakeholder: "Grounding makes the agent answer from our own documents and show its sources, instead of guessing. Foundry IQ lets it draw on all our knowledge — files, search, SharePoint, databases — through one secure, permission-aware layer."

Concepts you'll use (2-minute primer)

• File Search — upload documents into a vector store (backed by your Azure AI Search resource); the agent searches it and cites results. Fastest path; your data stays in your resource.
• Azure AI Search tool — connect an existing search index you already maintain; the agent retrieves and cites from it.
• Foundry IQ — the unified knowledge layer: a knowledge base that fronts File Search, Azure AI Search, SharePoint, Fabric, Azure SQL, and MCP behind one retrieval endpoint, with agentic retrieval (it plans and runs the retrieval) and permission enforcement.
• Citations — grounded answers carry inline references to the source documents, so every claim is traceable.

One sentence: index your knowledge (File Search, a search index, or many sources via Foundry IQ), attach it to the agent, and get cited, grounded answers.

Prerequisites

Path A — File Search (fastest)

Upload the Acme docs, build a vector store, and attach File Search to the agent:

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import FileSearchTool

project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# Upload documents and build a vector store (backed by your Azure AI Search).
files = [
    project.agents.files.upload_and_poll(file_path=p, purpose="assistants")
    for p in ["returns_policy.md", "shipping_policy.md", "warranty_policy.md"]
]
vector_store = project.agents.vector_stores.create_and_poll(
    file_ids=[f.id for f in files], name="acme-knowledge-base"
)

# Attach File Search to the agent.
file_search = FileSearchTool(vector_store_ids=[vector_store.id])

agent = project.agents.create_version(
    agent_name="acme-orders-assistant",
    definition={
        "model": "gpt-5-mini",  # your deployment name
        "instructions": (
            "You are the Acme Orders assistant. Answer questions about Acme "
            "policies using file search to ground answers in the company's "
            "documents. If the documents don't cover it, say so — don't guess."
        ),
        "tools": file_search.definitions,
        "tool_resources": file_search.resources,
    },
)

Ask "What's Acme's return window for opened electronics?" and the agent searches the vector store, retrieves the policy passage, and answers from it.

.NET note: the same flow uses Azure.AI.Agents/Azure.AI.Projects with a FileSearchToolDefinition and a vector store created from uploaded files. Class names mirror Python; check the NuGet docs for your version.

Path B — Connect an existing Azure AI Search index

If you already maintain a search index, connect it directly with the Azure AI Search tool instead of re-uploading:

from azure.ai.agents.models import AzureAISearchTool

search = AzureAISearchTool(
    index_connection_id="<your-search-connection-id>",
    index_name="acme-policies",
)

agent = project.agents.create_version(
    agent_name="acme-orders-assistant",
    definition={
        "model": "gpt-5-mini",
        "instructions": "Ground answers in the connected Acme search index; cite sources.",
        "tools": search.definitions,
        "tool_resources": search.resources,
    },
)

This reuses the index (and its chunking/embedding choices) you already run — the right path when search is part of your existing stack.

Foundry IQ — ground against everything, once

File Search and a single index are the building blocks. Foundry IQ is the layer that unifies them. In the portal, create a knowledge base and attach your sources — File Search vector stores, Azure AI Search indexes, SharePoint, Fabric, Azure SQL, even MCP knowledge sources — then connect the agent to the knowledge base.

When the agent queries it, Foundry IQ does agentic retrieval: it plans the retrieval across sources, enforces user permissions, and returns grounded answers with citations. The win is that you ground once, against all your knowledge, behind one SLA-backed, permission-aware endpoint — instead of wiring and securing a retrieval path per source.

Foundry IQ's connect-an-agent flow has full Python + REST samples (preview 2026-05-01 API / SDK 2.0.0+). Use the portal to assemble the knowledge base, then attach it to the agent in code or the portal.

Read the citations

The point of grounding is sourced answers. Grounded responses come back with inline citations that map claims to the documents they came from — read them off the run's output / message annotations and surface them to the user. When the agent answers "Can I return opened headphones after 20 days?", you get the answer and the returns-policy document it came from — a sourced response, not a guess.

The exact annotation/citation field names differ across SDK versions; print the message object to see the shape your version returns, and render the source titles/URIs you find there.

Cost & cleanup

# Delete the vector store and uploaded files when done
project.agents.vector_stores.delete(vector_store.id)
for f in files:
    project.agents.files.delete(f.id)

• Delete the vector store and uploaded files (above).
• Delete any Azure AI Search index / Foundry IQ knowledge base created only for this lab.
• Confirm in Cost Management that nothing is still accruing.

If a lab created it and you're done, delete it today.

Verified against

• Microsoft Foundry File Search, Azure AI Search tool, and Foundry IQ docs, and the `azure-ai-projects` preview SDK (2.0.0+), June 2026.
• Tool class names, the vector-store API, and citation/annotation fields vary by SDK version; code is syntax-checked against the docs but not executed during authoring. Pin your version.

What's next

Your agent now answers from your documents, with citations. Next:

• Lab 4 — Tools: built-in, custom, OpenAPI & MCP: beyond reading documents, connect the agent to live systems and capabilities — including the 1,400+ MCP-enabled tools.
• Grounding (this lab) plus tools (Lab 4) are the two ways an agent reaches the world: what it knows, and what it can do.