Foundry Iq

Foundry IQ Agent Framework Integration Skill

> Default knowledge retrieval pattern for EVERY threadlight process. > SPEC § 7 (Knowledge Sources) must declare at least one Knowledge Base per process, > with Backing service: foundry-iq (the default — alternatives are mcp-search > or inline-context only when foundry-iq is genuinely overkill, e.g., a process > with literally zero domain documents). > > See threadlight-design/SKILL.md → "Knowledge sources (default = foundry-iq)" > for the rule. This skill is the implementation of that default.

Input contract / Output artifacts

| Reads | From | |-------|------| | SPEC.md § 7 Knowledge Sources (Backing service, sources list, expected query patterns) | threadlight-design | | Documents from blob storage / SharePoint / GitHub (sources declared in § 7) | Customer / threadlight-demo-data-factory for demo seed corpus |

| Produces | At | |----------|-----| | Azure AI Search index | One per Knowledge Base in SPEC § 7 | | Knowledge Agent (in Foundry project) | One per Knowledge Base; reasoning effort per § 7 spec | | infra/modules/foundry-iq-index.bicep | Composed by azd-patterns Bicep library; included by threadlight-deploy Phase 6 when SPEC § 7 declares foundry-iq | | infra/scripts/bootstrap_foundry_iq.py | Postprovision hook that creates the index + uploads documents + creates the Knowledge Agent | | src/agent/skills//SKILL.md | Skill that wraps the Knowledge Agent retrieval call as a tool | | agent.yaml env vars | FOUNDRY_IQ_INDEX, FOUNDRY_IQ_AGENT_NAME, AI_SEARCH_ENDPOINT |

---

Folder Contents

| File | Type | Description | |------|------|-------------| | SKILL.md | Documentation | Main skill documentation with architecture, API reference, and agentic retrieval deep dive | | PRD.md | Documentation | Product Requirements Document for the skill | | .env.sample | Configuration | Sample environment variables for Azure OpenAI and AI Search | | requirements.txt | Dependencies | Python package dependencies (azure-search-documents, azure-ai-projects, fastapi) | | scripts/ | | | | scripts/__init__.py | Module | Package initializer with exports | | scripts/search_index_manager.py | Index Manager | Creates and manages Azure AI Search indexes with vector search and HNSW configuration | | scripts/document_indexer.py | Indexer | Document chunking with sentence boundary detection and batch upload to search index | | scripts/knowledge_agent_manager.py | Agent Manager | Creates Knowledge Agents with configurable reasoning effort; KnowledgeAgentRetriever for multi-turn retrieval | | scripts/azure_openai_client.py | LLM Client | Azure OpenAI client for chat completions; PolicyBot combining retrieval + generation |

---

Overview

Foundry IQ is Microsoft's enterprise-grade RAG solution that treats retrieval as a reasoning task. It uses Azure AI Search Knowledge Bases with agentic retrieval to enable multi-hop reasoning, query planning, and citation-backed responses.

> ### Knowledge Bases migration callout (May 2026) > > Two control-plane surfaces exist side by side; they are NOT > interchangeable and you must pin to one consciously: > > | Surface | api-version | Endpoint shape | Wire shape | > |---------|-------------|----------------|------------| > | Legacy "Knowledge Agents" | 2025-01-01-preview | PUT /agents/ | configuration: { reasoningEffort, outputMode } (nested) | > | New "Knowledge Bases" | 2025-11-01-preview | PUT /knowledgebases/ | top-level retrievalReasoningEffort + outputConfiguration: { modality } (flat) | > > The scripts in this skill are pinned to the legacy /agents/ surface > for compatibility with tenants that haven't yet been migrated. To opt > into Knowledge Bases: > 1. Bump AI_SEARCH_API_VERSION to 2025-11-01-preview. > 2. Replace the /agents/ path with /knowledgebases/ in > KnowledgeAgentManager._make_request callers and > KnowledgeAgentRetriever.retrieve. > 3. The wire shape change in step 1 is already implemented in > knowledge_agent_manager.create_agent (see the wire-format note > inline in the function), but the legacy endpoint will reject the > flat shape — the two MUST move together. > > Output mode values are also camelCase on the wire — extractiveData, > NOT extractive_data. The previous snake_case form was a docs typo > that the legacy endpoint silently ignored.

---

Knowledge Base GA + Serverless (Build 2026)

> GA as of //build 2026. Knowledge Base graduated from preview to > general availability on the 2026-05-01-preview API version > (paired with the /knowledgebases/ flat surface from the > migration callout above). Two consumption shapes ship: > > 1. Standard KB — bring your own AI Search service. You manage > the index, vector profile, and capacity. Use when you already > operate AI Search or need control over the search SKU. > 2. Serverless KB — Foundry-managed index and capacity. No AI > Search SKU to size, no index schema to author. Use for pilots, > POCs, and any consumer that hasn't already standardized on a > Search service. Billing is per-query + storage. > > The wire shape is identical across both — the same > knowledge_agent_manager.create_agent call works; only the > serverless: true flag on the request body switches modes. > > KB-MCP integration. Knowledge Bases now expose an MCP > server surface that any hosted agent (or third-party MCP > client) can attach to via tools=[{"type": "mcp", > "server_label": "kb", "server_url": "/mcp"}]. This > replaces the older "wire your agent to call corpus_query > manually" pattern — the agent now discovers KB capabilities > through MCP tool listing and the agentic-retrieval loop runs > inside the KB service. See foundry-hosted-agents for the > agent-side wiring. > > Four knowledge source types ship at GA — Web IQ (public-web > grounding), Files (blob upload), Search (existing AI Search > index), and External MCP (third-party KB connectors). See > Key Components § 4 below for source-by-source guidance.

---

Architecture

+---------------------------------------------------------------------+
|                    Foundry IQ Architecture                           |
+---------------------------------------------------------------------+
|                                                                      |
|  +----------------+    +------------------+    +-----------------+   |
|  |   Documents    |--->|  Azure AI Search |--->| Knowledge       |   |
|  |   (Blob)       |    |     Index        |    | Agent           |   |
|  +----------------+    +------------------+    +-----------------+   |
|                                                        |             |
|                                                        v             |
|  +----------------+    +------------------+    +-----------------+   |
|  |   FastAPI      ||  Agent Framework || Agentic         |   |
|  |   Endpoint     |    |  (ChatAgent)     |    | Retrieval       |   |
|  +----------------+    +------------------+    +-----------------+   |
|                              |                                       |
|                              v                                       |
|                     +------------------+                             |
|                     |  Azure OpenAI    |                             |
|                     |  (Configurable)  |                             |
|                     +------------------+                             |
|                                                                      |
+---------------------------------------------------------------------+

---

Key Components

1. Azure AI Search Knowledge Agent

The Knowledge Agent provides:

• Query Planning: LLM-powered decomposition of complex queries
• Multi-hop Reasoning: Following chains of information across documents
• Answer Synthesis: Comprehensive context with citations
• Retrieval Modes: semantic (fast) vs agentic (intelligent)

2. Retrieval Modes

| Mode | Speed | Use Case | |------|-------|----------| | semantic | ~100-300ms | Simple Q&A, speed-critical apps | | agentic | ~1-3s | Complex questions, multi-hop reasoning |

3. Reasoning Effort Levels

• minimal: Basic retrieval
• low: Light query planning
• medium: Full query planning and multi-hop reasoning

4. Knowledge Sources (4 source types, Build 2026)

Knowledge Bases ingest from four distinct source types — pick the one that matches where your domain knowledge already lives:

• Web IQ — public-web grounding via Bing. No upload step; the

KB queries the live web at retrieval time and returns Bing-style citations. Use for evergreen factual lookups (regulations, product docs, news). Subject to per-tenant Bing quota.

• Files — drop documents into the KB and let Foundry chunk +

embed + index them for you. Backed by managed AI Search (or Serverless KB). Use when you own the source documents and want zero index-management ceremony.

• Search — attach an existing Azure AI Search index as-is.

Foundry queries your index through the agentic-retrieval loop without re-ingesting. Use when you've already invested in a Search index and don't want to re-chunk.

• External MCP — connect any MCP-speaking third-party

knowledge backend (vendor KB, internal wiki MCP server, partner RAG service) by URL. Foundry treats it as just another retrieval source in the agentic loop.

Mix-and-match: a single KB can compose all four. The agentic-retrieval planner fans the query across sources and merges citations.

---

Project Structure

The recommended project structure for a Foundry IQ implementation:

project-root/
|
+-- .env                           # All configuration (never hardcode!)
|
+-- src/
|   +-- foundry-iq/
|       +-- app/
|       |   +-- __init__.py
|       |   +-- main.py            # FastAPI application & endpoints
|       |   +-- models.py          # Pydantic request/response models
|       |   +-- services.py        # Service layer (all business logic)
|       |
|       +-- requirements.txt       # Python dependencies
|       +-- Dockerfile             # Container configuration
|       +-- docker-compose.yml     # Docker orchestration
|
+-- notebooks/
|   +-- foundry_iq_demo.ipynb      # Interactive demonstration
|
+-- .github/
|   +-- skills/
|       +-- foundry-iq/
|           +-- SKILL.md           # This documentation
|           +-- scripts/           # Reusable building blocks
|               +-- __init__.py
|               +-- search_index_manager.py
|               +-- document_indexer.py
|               +-- knowledge_agent_manager.py
|               +-- azure_openai_client.py
|
+-- research.md                    # Training materials & micro-hack design

---

Environment Variables

All configuration should be externalized to .env. Keyless auth (DefaultAzureCredential) is the default — only set API keys if you cannot use managed identity or az login.

> ### ⚠️ Threadlight pilots: keyless is MANDATORY (not optional) > > For threadlight processes deployed via threadlight-deploy, the keyed > fallback path must not ship in production: > > - Provision Azure AI Search with disableLocalAuth: true > - Provision AOAI with disableLocalAuth: true > - Assign UAMI roles per the matrix below — NOT keys, NOT shared admin keys > - Strip AZURE_OPENAI_API_KEY and AI_SEARCH_KEY from the deployed .env (they're for local dev only) > > Required RBAC for foundry-iq runtime (assign to the agent's UAMI): > > | Resource | Role | Role ID | > |----------|------|---------| > | Azure AI Search service | Search Index Data Reader | 1407120a-92aa-4202-b7e9-c0e197c71c8f | > | Azure AI Search service | Search Index Data Contributor (only for indexer/builder UAMI) | 8ebe5a00-799e-43f5-93ac-243d3dce84a7 | > | Azure OpenAI account | Cognitive Services OpenAI User | 5e0bd9bd-7b93-4f28-af87-19fc36ad61bd | > | Foundry project (if using Knowledge Agent) | Azure AI User | 53ca6127-db72-4b80-b1b0-d745d6d5456d | > > Plus: Search Service Contributor (7ca78c08-252a-4471-8644-bb5ff32d4ba0) > on the Search service for the deploy-time identity that creates indexes, > indexers, and knowledge agents (separate from the runtime UAMI; least > privilege at runtime). > > #### Hosted-agent runtime identity (the gotcha that breaks corpus_query) > > If the consumer is a Foundry hosted agent (foundry-hosted-agents / > threadlight-deploy Phase 5), the agent does NOT make outbound calls > under the Foundry project managed identity or the AI Services > account managed identity — even if you've granted those Search > Index Data Reader. Granting only those will leave you with a confidently > wrong "RBAC is set, why am I getting 403?" debug session. > > Each hosted-agent version has its own identities: > > | Identity | Stable across versions? | Granted via | Grant Search Index Data Reader? | > |---|---|---|---| > | blueprint.principal_id | ✅ Yes (stable per agent name) | Bicep post-deploy script (read after first agent create) | YES | > | instance_identity.principal_id | ❌ No (changes every azd deploy agent) | Postdeploy script that re-reads after each version create | YES | > | Foundry project SystemAssigned MI | ✅ | Bicep principalId output | No (not used for outbound tool calls) | > | AI Services account SystemAssigned MI | ✅ | Bicep principalId output | No (not used for outbound tool calls) | > > Read the version's identities via: > ``bash > az rest --method GET \ > --url "https://.cognitiveservices.azure.com/api/projects//agents//versions/?api-version=2025-11-15-preview" \ > --resource "https://ai.azure.com" \ > --query "{blueprint:blueprint.principal_id, instance:instance_identity.principal_id}" > ` > > Then az role assignment create --assignee-object-id --assignee-principal-type ServicePrincipal --role "Search Index Data Reader" --scope for each. > > Persist this in IaC as a postdeploygrantagentsearchrbac.py hook > wired into azure.yaml after azd deploy agent — otherwise every new > agent version regresses the grant for the new instanceidentity. > > **RBAC propagation on AI Search is slow** — up to 5-10 minutes (vs 30-60s > for most resources). If the first corpusquery after a fresh grant > 403s, wait, don't re-grant. > > See foundry-doc-vision-speech` for the full keyless RBAC matrix across > all Cognitive Services. > > Purview ACL passthrough (2026-05-01-preview). Knowledge Bases > now honor document-level Purview sensitivity labels at query > time. When the KB ingests Files (or queries a Search index whose > documents carry Purview labels), each retrieved chunk is filtered > against the calling user's Purview permissions before the > agent ever sees it — meaning two users running the same query > against the same KB get different citations based on what they're > cleared to read. The filter is enforced server-side; no code > change in the agent. Requires Purview to be configured on the > source documents AND the caller's identity to flow through > (works out-of-the-box with hosted agents using user-on-behalf > tokens; for agent-as-service identity, the agent's MI permissions > are evaluated instead — beware of over-privileged agent identities > defeating the filter).

# Azure OpenAI Configuration
AZURE_OPENAI_ENDPOINT=https://.openai.azure.com
# AZURE_OPENAI_API_KEY=            # Optional — omit for keyless auth (REQUIRED to omit for threadlight pilots)
AZURE_OPENAI_API_VERSION=2025-04-01-preview

# Azure AI Search Configuration
AI_SEARCH_ENDPOINT=https://.search.windows.net
# AI_SEARCH_KEY=                    # Optional — omit for keyless auth (REQUIRED to omit for threadlight pilots)
# Pin to match the endpoint surface you use:
#   2025-01-01-prev

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aiappsgbb](https://github.com/aiappsgbb)
- **Source:** [aiappsgbb/awesome-gbb](https://github.com/aiappsgbb/awesome-gbb)
- **License:** MIT

Install and usage instructions live in the source repository linked above.