Foundry IQ

A knowledge source describes searchable content. A knowledge base binds one or more sources and controls retrieval. Foundry Agent Service can call that knowledge base as a native tool, so the agent can ground answers in retrieved content and return source references.

This page describes Foundry IQ and the Agent Application's integration limits. Deployment follows the full-stack deployment guide.

What must be connected before an agent can use a knowledge base?

Search owns the knowledge base and its registered sources.
The native Agent uses the managed Foundry Toolbox integration, not the separate direct Search connector. The Toolbox reaches the knowledge base through its platform-provisioned RemoteTool project connection.
Source ingestion, tool registration and end-user authorization are separate setup tasks. Test all three before admitting users.

Open full-size diagram

What is shipped, and what you must connect

The default platform topology supplies RETRIEVAL_BACKEND=foundry_iq. That selects Search knowledge-object provisioning. It does not enable a tool in the native Agent or Workflow. FOUNDRY_IQ_ENABLED defaults to false.

Choosing a retrieval backend is not enabling its native tool. The native capability flags default to off. Follow Tools & MCP and the native application settings to select the capability with its required bindings, then verify a real source-backed answer and a denied-user case.

The native runtime registers Foundry IQ through the official MAF FoundryToolbox integration. It does not call connectors/foundry_iq.py or manually serialize user Search tokens on a model MCP tool. Selecting RETRIEVAL_BACKEND does not reroute the MCP NL2SQL tools or replace callable MCP tools.

Application settings describes how to change runtime values. Agents & prompts describes application selection independently of the host and its tools.

The NL2SQL tools on Agent App MCP Server store approved SQL metadata and vectors in application Cosmos. This toolset does not require Search. Enabling the server does not enable Foundry IQ or alter this knowledge base's sources.

Managed and remote sources

Indexed sources copy content into Search for retrieval. Remote sources query their service at request time, without copying the source corpus into a local index. Both can return content to the agent and model.

The accelerator defaults to a native Blob source, container documents, standard content extraction and ingestion permission options ["rbacScope"]. Search manages the generated indexing assets. Optional Agent App Ingestion is disabled by default and is not needed for this source. Ingestion explains native source ingestion, private-input boundaries and custom processing.

An existing Search index can be registered as a searchIndex knowledge source. The pipeline that owns that index remains responsible for its content, schema and permission metadata. Registering it does not populate or authorize it. Microsoft documents Blob sources and Search index sources separately.

SharePoint, Work IQ and Fabric IQ describe additional native sources, including previews, and the work needed to integrate them with Agent Application.

Native tools and the accelerator boundary

Microsoft's Foundry Agent Service connection guide connects a knowledge base through its MCP endpoint and a Foundry RemoteTool project connection. Hosted applications consume it through the official managed Toolbox integration.

The coordinated platform implementation provisions a project-scoped RemoteTool connection to the knowledge base's MCP endpoint and publishes its ID as KNOWLEDGE_BASE_CONNECTION_ID for tool registration. Its ProjectManagedIdentity authentication uses the Search audience https://search.azure.com/. After successful Search setup, provisioning creates and promotes a Toolbox version containing the knowledge_base_retrieve tool. It publishes TOOLBOX_ENDPOINT under App Configuration label agent-lz:

<AI_FOUNDRY_PROJECT_ENDPOINT>/toolboxes/<KNOWLEDGE_BASE_NAME>/mcp?api-version=v1

The native runtime consumes that derived endpoint, not the connection ID as a direct model MCP tool. The Hosted identity has Foundry User access at the exact project scope. The project identity retains scoped Search access, separately from the UI's Foundry caller grant and ingestion's Blob access. The direct Search connection remains separate. These service grants do not replace user authorization for a protected source.

The Deployment settings describe knowledge-object inputs. App Configuration uses label agent-lz. Distinguish native application settings from settings used by the separately available direct connector:

Setting	Consumer and meaning
`FOUNDRY_IQ_ENABLED`	Native runtime: enables managed Toolbox retrieval, structural, requires redeployment.
`TOOLBOX_ENDPOINT`	Native runtime: platform-derived project Toolbox endpoint, published under `agent-lz`, not an additional authentication selector.
`KNOWLEDGE_BASE_CONNECTION_ID`	Provisioning: compatible project `RemoteTool` connection used to register the knowledge-base tool in the Toolbox.
`RETRIEVAL_BACKEND`	Provisioning: `foundry_iq` selects knowledge-base setup. The direct connector also reads this selector; native tool composition does not.
`RETRIEVAL_AUTH_MODE`	Platform-derived `native_search` contract in both profiles. Managed Toolbox integration, consent and source permissions establish downstream authorization.
`KNOWLEDGE_BASE_ENDPOINT`	Direct connector: Search service root, such as `https://<service>.search.windows.net`, not a Foundry project or retrieve URL.
`KNOWLEDGE_BASE_NAME`	Provisioning/direct connector: knowledge-base object name, not an index name. Native configuration also loads the name.
`FOUNDRY_IQ_KNOWLEDGE_SOURCE_NAME`	Primary registered source name.
`FOUNDRY_IQ_PATTERN` and `FOUNDRY_IQ_KNOWLEDGE_SOURCE_KIND`	`azureBlob` for the default source, or matching `searchIndex` for an existing index.
`FOUNDRY_IQ_API_VERSION`	The source and connector contract defaults to `2026-05-01-preview`.

Current Microsoft source examples use contracts beyond the accelerator's default API. Adopting a source requires compatibility across registration, retrieve requests and response parsing, not an API-version edit alone.

How to connect a knowledge base

1. Prepare ownership and content before provision

Initialize through the canonical deployment guide. Identify the Search administrator, content owner, Entra consent administrator and application publisher. The Search administrator needs knowledge-object management permission; Search Service Contributor is the keyless management role. Ingestion identities need source/model access independently of the querying user's document permissions.

Keep the native Blob defaults unless your content needs another path. For an existing populated index, set the mapped deployment inputs FOUNDRY_IQ_PATTERN=searchIndex and FOUNDRY_IQ_KNOWLEDGE_SOURCE_KIND=searchIndex; set FOUNDRY_IQ_SEARCH_INDEX_NAME to that index. Confirm schema, semantic configuration, embeddings and ACL metadata before registering it.

2. Provision sources and the managed Toolbox

Run the selected guide's azd provision procedure after source inputs and grants are ready.
Inspect the knowledge base's source references and, for indexed sources, successful indexing and permission metadata.

Source setup is not a runtime refresh operation. Provisioning reconciles platform-owned names and can overwrite manual edits.

Review the generated project RemoteTool binding against Microsoft's native connection procedure and verify its MCP target, authentication and scoped project identity grants. Confirm the post-provision step creates and promotes the knowledge-base Toolbox version after successful Search setup. A project connection or service role must not turn a user-protected corpus into application-wide access. A source-validation failure blocks application deployment, even if some settings have already been published.

3. Enable the capability and publish the application

Follow Configure an agent capability. In root main.parameters.json, merge this entry into parameters.additionalAppConfigurationSettings.value, retaining its host/mode entries and all other required settings:

{ "name": "FOUNDRY_IQ_ENABLED", "value": "true", "label": "agent-lz" }

There is no declared azd env set FOUNDRY_IQ_ENABLED mapping. Run azd provision again to publish the capability declaration and native Toolbox binding. Verify TOOLBOX_ENDPOINT under agent-lz identifies that project's knowledge-base Toolbox, not a direct Search endpoint. Keep reviewed overrides aligned with their provisioning owner rather than relying on a manual key edit that a later provision can overwrite.

Deploy/redeploy the affected native publication after the binding is ready. Capability composition is structural: a provider refresh is not enough to enable it. Confirm the effective endpoint, a real tool invocation and the allow/deny cases below. A successful deployment is not proof of grounding.

User authorization boundaries

Protected retrieval requires source-compatible user authorization, separately from workload authentication. The official MAF FoundryToolbox integration forwards the current trusted Hosted call ID so that Foundry can resolve the user context and manage downstream knowledge-base authorization. Foundry supplies the appropriate Search user credential outside the agent container. The application does not implement a second OBO/token-forwarding protocol or put tokens in model inputs.

The call ID alone is not authorization. Missing context, denied source access or required consent must produce an explicit failure, never an app-only retry against protected data. The mode without OBO uses service credentials for sources that accept them. It does not impose a Blob-only allowlist, and a source requiring user delegation must fail explicitly. See Sign-in & access.

The UI reports managed oauth_consent_request outcomes as an explicit 401 consent_required, with instructions to complete the approved Foundry consent process and retry. It does not open returned consent links or automatically resume the failed request. Failed tool calls are not accepted as successful answers. In service mode, consent requests return 403 user_delegation_required. Other retrieval failures return a safe tool_failed error with service-permission and OBO guidance, without automatically acquiring another credential.

Native permission filtering is enabled for the application index's user, group and RBAC scope fields. Indexing must populate the appropriate metadata. Turning on filtering cannot reconstruct missing ACLs. Conversation uploads also require their conversation/uploader restrictions.

Source contracts differ. Work IQ uses a distinct app-audience assertion and x-ms-query-work-iq-source-authorization, not the Search token. Indexed SharePoint requires compatible permission-ingestion configuration. Fabric sources require compatible preview APIs and user permissions. A source registration or runtime connector alone does not establish that the complete deployment combination is supported.

Tokens do not belong in prompts, chat history, recovery checkpoints or user-supplied tool arguments. Required retrieval must fail closed if credentials or source authorization are unavailable; verify this in the selected native connection or custom integration. Application authentication describes consent and allowed/denied-user acceptance.

Shared-source permission metadata

Ingestion permission metadata records access information alongside indexed content. rbacScope records Azure RBAC scopes; sensitivityLabels records information-protection labels. Retrieval must still enforce the applicable permissions for the caller.

FOUNDRY_IQ_INGESTION_PERMISSION_OPTIONS controls the configured source's ingestion permission metadata. Omission or an actual null value retains the protected default ["rbacScope"]. An explicit JSON empty array, [], is an opt-in for a deliberately shared source when native Blob ingestion is active. An empty array is distinct from an omitted setting.

The explicit mode without OBO does not require [] or restrict source types. Source metadata and the connection's scoped service grants remain independent. Selecting service_identity must not clear existing permission metadata or silently drop sources. If a source requires user delegation, its runtime operation fails without retrying with another identity.

For active native Blob ingestion, the shared-source empty list is accepted with RETRIEVAL_BACKEND=foundry_iq, FOUNDRY_IQ_PATTERN=azureBlob, azureBlob knowledge source kind and a recognized non-ADLS source. Active ADLS Gen2, mismatched source configuration and ambiguous ADLS configuration fail closed. Nonempty Blob permission lists accept only rbacScope and sensitivityLabels.

The infrastructure also publishes [] as unused metadata for inactive native Blob ingestion: ai_search with any pattern, or foundry_iq with the searchIndex pattern. Those empty lists remain accepted because no native Blob knowledge source is rendered. They are not shared-source opt-ins and do not change the independently populated index's authorization.

Malformed JSON, a single value instead of a JSON list, the text null, invalid list entries and unsupported permission names fail with actionable diagnostics. Invalid input fails closed rather than silently removing protection. An actual null and the text null are different inputs.

For active native Blob ingestion, [] is appropriate only when policy permits the source's documents to be shared without that ingestion permission metadata. It does not grant document access by itself or change other sources, application authentication, Entra ID/OBO, retrieval authorization, RBAC or private network restrictions.

It is not a workaround for an authentication or private-link failure. Its use requires audience review and allow/deny tests with real user identities before activation.

Restoring ["rbacScope"] requires source reconfiguration and verification of source/index permission metadata, including already-ingested documents. Allowed and denied users both need validation before access resumes. The Deploy full stack guide covers reconfiguration. See also Private native Blob ingestion.

Generic MCP knowledge sources

The direct connector includes a default-off preview to retrieve grounding from registered mcpServer knowledge sources. This is distinct from callable MCP tools and from deploying Agent App MCP Server. The native runtime does not load these connector settings. Using this planner in your application requires explicit connector/invocation integration; the settings below are not native Agent tool switches. They do not create sources.

Register each source on the selected knowledge base first, with the same name, server and tools as the runtime metadata.

Runtime setting	Default	Required choice
`FOUNDRY_IQ_MCP_ENABLED`	`false`	Set `true` to enable conversational MCP planning.
`FOUNDRY_IQ_MCP_SOURCES_JSON`	`[]`	Supply a non-empty source array when enabled.
`FOUNDRY_IQ_API_VERSION`	`2026-05-01-preview`	This exact API contract is required for this MCP preview.
`FOUNDRY_IQ_MCP_REASONING_EFFORT`	`low`	`low` or `medium`.
`FOUNDRY_IQ_MCP_TRUSTED_HOSTS`	Empty	Exact hostname allowlist, required when enabled.
`FOUNDRY_IQ_MAX_RUNTIME_SECONDS`	`120`	Integer from `30` to `600`.
`FOUNDRY_IQ_MCP_LOG_TOOL_ARGUMENTS`	`false`	Leave off unless debug argument logging is approved.

These settings belong in Application settings, not in a chat request. The exact MCP API requirement differs from the remote Work IQ and Fabric contracts. Do not combine incompatible source requirements in one connector by changing only the API version.

For example, after registering a reviewed read-only source, configure FOUNDRY_IQ_MCP_TRUSTED_HOSTS=mcp.contoso.com and the following source metadata. The names and resource scope are illustrative, not provisioned resources.

[
  {
    "name": "monitor-mcp",
    "description": "Read-only monitoring knowledge.",
    "serverURL": "https://mcp.contoso.com/mcp",
    "failOnError": true,
    "maxOutputDocuments": 5,
    "tools": [
      {
        "name": "query_logs",
        "outputParsing": {
          "kind": "json",
          "jsonParameters": {
            "documentsPath": "$.results[*]",
            "includeContext": true
          }
        },
        "inclusionMode": "reranked",
        "maxOutputTokens": 2048
      }
    ],
    "queryHeaders": [
      {
        "name": "Authorization",
        "valueFrom": {
          "kind": "managedIdentity",
          "scope": "api://monitor-mcp/.default"
        }
      }
    ]
  }
]

Source limits and credentials

Each source needs a unique name, HTTPS server URL and non-empty tool list. Tool names must be unique within the source. Each tool declares output parsing, inclusionMode (reranked or always) and maxOutputTokens from 1 to 8192.

Parsing kinds are auto, none, json and split. json needs a documentsPath and optional boolean includeContext. split supports page or sentence splitting, positive page length and page-count limits, non-negative overlap smaller than page length, and a default language.

Do not mix parsing parameters across kinds or add unknown fields. The API reference is the payload reference.

failOnError=true makes a reported source failure fail the request. Choose false only when partial grounding is acceptable. Per-source maxOutputDocuments accepts 1 to 50. The separate FOUNDRY_IQ_MAX_OUTPUT_DOCUMENTS can bound final grounding records.

Trusted hosts are bare hostnames, supplied as comma/newline-separated values or a JSON array. Matching is exact after lowercasing and removing a trailing dot, not wildcard or subdomain matching. Server URLs reject embedded credentials, queries, fragments, IP literals, single-label names and reserved/local names such as localhost, .internal or .test. This validation does not replace DNS and network egress controls.

Each query header has a unique valid HTTP field name and valueFrom metadata. Reserved and hop-by-hop headers such as Host and Connection are rejected. Do not put literal tokens, API keys or credential values in the source JSON.

`valueFrom.kind`	Configuration and access
`managedIdentity`	Explicit resource `scope`. Grant the workload identity access. The credential chain can use Azure CLI locally.
`obo`	Explicit target-resource `scope`. Uses the original incoming user assertion, backend OBO configuration and consent, not a reused Search token.
`keyVaultSecret`	`secretName` in `KEY_VAULT_URI`. Grant secret-read access and store the complete header value in the vault.
`none`	No scope or secret name. Omits that header rather than creating anonymous access to a protected source.

Only keyVaultSecret accepts secretName, with 1 to 127 letters, digits or hyphens. scope is forbidden for keyVaultSecret and none. Missing credentials or failed delegation fail the request rather than downgrading to none. The retrieve call references registered source names and relays resolved source-specific query headers. It does not send server URLs or tool definitions as registration instructions.

Normal telemetry omits tool arguments. Debug logging performs bounded redaction, which cannot guarantee that arbitrary arguments are safe to export. Use Monitoring & audit for the logging policy.

Ownership and connectivity

Platform Search setup reconciles named sources and knowledge bases from config/search/search.j2. Later provisioning can replace manual additions to those objects. Operator-owned sources and knowledge bases need distinct names. Changes to platform-owned objects belong in reviewed templates. Knowledge-base updates must preserve all intended source references.

Source administration, ingestion and retrieval use separate permissions: the administrator manages knowledge objects. Search's ingestion identity reads the source and calls extraction/embedding services. The retrieval identity authenticates to Search. The end user's delegated identity authorizes protected content. A service role is not a substitute for user authorization.

Private deployments need both runtime-to-Search access and Search-to-source/model connectivity. The platform attempts to set generated Blob indexers to private execution, but skips that update if an indexer does not yet exist. Generated indexer state and shared private-link approvals still need validation before sensitive ingestion. See Network design.

Acceptance and recovery

Acceptance includes successful source indexing where applicable, a known-answer query with the expected document reference, and separate allowed/denied-user tests. A denied result must exclude the restricted document and its citation. A missing-token failure calls for checking the compatible UI/runtime configuration, downstream consent and supported header path, not anonymous retrieval or broader managed-identity grants.

Configuration is cached in the running application. Approved changes require the full-stack deployment guide to start a new hosted version. Recovery restores the previous compatible image and settings while retaining source documents and knowledge objects.