Why Service Desks Should Build a Foundry IQ Knowledge Base

Your password-reset bot has its own retrieval. So does the incident triage agent, and so does the change-request helper someone built on the side. Each has its own chunking, index and nightly sync, all pointed at the same runbooks. Then someone fixes a runbook and one bot keeps quoting the old version for a week. A shared Foundry IQ knowledge base fixes that: build retrieval once and let every service desk agent use it.

Why a shared Foundry IQ knowledge base beats per-bot retrieval

Foundry IQ is Microsoft's managed knowledge layer for agents, built on Azure AI Search agentic retrieval. A knowledge base is a set of knowledge sources plus retrieval settings, and Microsoft Learn says multiple agents can share the same one.

For a service desk, three properties matter:

• One copy of the truth. Indexers can run on a schedule and refresh incrementally, so a corrected runbook reaches every agent at once.
• Answers a technician can check. Retrieval returns extractive content with citations, so an agent can cite the article it used instead of asking to be trusted.
• Permission-aware retrieval. Queries can run under the caller's Microsoft Entra identity, so a Tier 1 analyst's agent doesn't read out the security incident playbook.

Ad hoc retrieval rarely gets the third: a bot with its own index usually searches as one service identity.

Pass the caller's identity to the knowledge base

Microsoft Foundry agents reach a knowledge base through an MCP tool named knowledge_base_retrieve. To get permission trimming, forward the signed-in user's token in the x-ms-query-source-authorization header. The connection guide does this with a structured input, so the token arrives on each call.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, PromptAgentDefinition, StructuredInputDefinition
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint="<your-project-endpoint>",
    credential=DefaultAzureCredential(),
)

mcp_endpoint = (
    "https://<your-search-service>.search.windows.net"
    "/knowledgebases/<knowledge-base-name>/mcp?api-version=2026-08-01-preview"
)

kb_tool = MCPTool(
    server_label="knowledge-base",
    server_url=mcp_endpoint,
    require_approval="never",
    allowed_tools=["knowledge_base_retrieve"],
    project_connection_id="<project-connection-name>",
    headers={"x-ms-query-source-authorization": "{{search_auth_token}}"},
)

agent = project_client.agents.create_version(
    agent_name="servicedesk-triage",
    definition=PromptAgentDefinition(
        model="<your-model-deployment>",
        instructions=(
            "Answer only from the knowledge base. Cite the sources you used. "
            "If the knowledge base has no answer, say you don't know."
        ),
        tools=[kb_tool],
        structured_inputs={
            "search_auth_token": StructuredInputDefinition(
                description="Per-user Azure AI Search bearer token",
                required=True,
                schema={"type": "string"},
            )
        },
    ),
)

This creates the agent with the header wired to a placeholder. It assumes you already created the project connection from the connection guide.

openai_client = project_client.get_openai_client()
conversation = openai_client.conversations.create()

response = openai_client.responses.create(
    conversation=conversation.id,
    input="How do I reset a locked VPN account?",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"search_auth_token": "<signed-in-user-search-token>"},
    },
)
print(response.output_text)

The token is for the https://search.azure.com/.default scope. In production, get it through an on-behalf-of flow for the signed-in user, not from the app's own credential. Indexed content also needs permission metadata in the index to filter on.

Now the sharp edge. Per Microsoft Learn, without the token, permission-enabled sources return results unfiltered. A forgotten header is a leak, not an error.

The objection: much of this is still in preview

Fair hit. Which Foundry IQ features are generally available and which are preview depends on the Search REST API version.

The migration page spells it out. The 2026-04-01 version is the production path, with searchIndex, azureBlob, indexedOneLake and web knowledge sources and minimal, extractive retrieval. SharePoint sources, LLM query planning, answer synthesis and multi-turn messages are preview on 2026-08-01-preview. And ingestionPermissionOptions, which ingests permission metadata such as sensitivity labels for blob and OneLake sources, isn't supported in 2026-04-01. The agent connection guide shows the preview endpoint too.

Preview features carry no SLA and aren't recommended for production, so the objection is right about today. But the knowledge base, its sources and the share-it-across-agents pattern are the parts worth getting right early. The preview items are switches you flip later.

In practice, start with content every agent user may read: runbooks, how-to articles, public vendor docs. Keep access-restricted material, like HR cases and security playbooks, out of the shared knowledge base until the permission features you need are generally available, or accept the preview terms knowingly.

First step: one runbook source on the free tier

Pick one source, such as a Blob container of your most-used runbooks. Microsoft suggests starting in the Foundry portal, where you can use the free tier of Azure AI Search and a free allocation of tokens for agentic retrieval.

With the New Foundry toggle on, open your project, go to Build, then the Knowledge tab. Connect a search service, add the source, create the knowledge base, then connect an agent on the Agents tab and test it in the playground. Feed it ten real tickets and check that the citations point at the right runbook.

Objects created in the portals may use preview schemas that need migration later.

If your service desk agents answer from one governed, cited, permission-aware source, you can defend them to the customer's security team; with five private indexes you will be defending five.