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 retrieval object | One per Knowledge Base; select the API generation and supported controls from SPEC § 7 | | `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/<knowledge-skill>/SKILL.md` | Skill that wraps the Knowledge Agent retrieval call as a tool | | User env in the [selected hosted profile](../foundry-hosted-agents/references/hosted-contract.json) | `APP_IQ_INDEX`, `APP_IQ_AGENT_NAME`, `AI_SEARCH_ENDPOINT`. In 2.0, migrate the former `FOUNDRY_IQ_*` keys: the hosted platform reserves `FOUNDRY_*`; do not declare those old names in a container. | --- ## 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 `2025-05-01-preview` Knowledge Agents with explicit model and target-index definitions; retrieves with the matching message contract | | `scripts/azure_openai_client.py` | LLM Client | Azure OpenAI client for chat completions; PolicyBot combining retrieval + generation | | `test-fixture/consumer_prompt.md` | Live smoke | Creates and reads a GA `searchIndex` knowledge source on REST `2026-04-01` | | `test-fixture/azure.yaml` + `infra/` | CI infrastructure | azd+Bicep source for the standing keyless Azure AI Search service | --- ## 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. > ### Agentic retrieval API surface map (July 2026) > > Three data-plane surfaces exist side by side. They are **not > interchangeable**: > > | Surface | API version | Status | Endpoint shape | > |---------|-------------|--------|----------------| > | First-generation Knowledge Agents used by this skill's scripts | `2025-05-01-preview` | Preview | `/agents('<name>')` | > | Knowledge sources and Knowledge Bases | `2026-04-01` | Narrow GA programmatic slice | `/knowledgesources('<name>')`, `/knowledgebases('<name>')` | > | Expanded knowledge-source kinds and options | `2026-05-01-preview` | Preview | Same resource families with preview-only wire values | > > The scripts in this skill are pinned to the published first-generation > Knowledge Agent contract for compatibility only. New production code should use the `2026-04-01` > Knowledge Source and Knowledge Base REST resources directly and should > opt into `2026-05-01-preview` only when it needs a capability explicitly > marked preview in the matrix below. Do not migrate by changing only the > API-version string; endpoint paths and wire shapes also differ. --- ## Foundry IQ availability: GA vs preview Foundry IQ has a narrow GA programmatic slice on the stable Azure AI Search REST API `2026-04-01`. The Azure portal and Microsoft Foundry portal access to all agentic retrieval features remains preview. The latest `2026-05-01-preview` API adds source kinds and options that are not covered by the GA service contract. <!-- GA_KNOWLEDGE_SOURCE_MATRIX_START --> | Wire kind | Status on `2026-04-01` | Knowledge source | Indexed or remote | |-----------|-------------------------|------------------|-------------------| | `searchIndex` | GA | [Existing Azure AI Search index](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-search-index) | Indexed | | `azureBlob` | GA | [Azure Blob Storage or ADLS Gen2](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-blob) | Indexed | | `indexedOneLake` | GA | [OneLake](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-onelake) | Indexed | | `web` | GA | [Bing-grounded public web](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-web) | Remote | | `indexedSql` | Preview | [Azure SQL](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-azure-sql) | Indexed | | `file` | Preview | [Direct file upload](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-file) | Indexed | | `indexedSharePoint` | Preview | [Indexed SharePoint](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-sharepoint-indexed) | Indexed | | `remoteSharePoint` | Preview | [Remote SharePoint](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-sharepoint-remote) | Remote | | `fabricDataAgent` | Preview | [Fabric Data Agent](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-fabric-data-agent) | Remote | | `fabricOntology` | Preview | [Fabric Ontology](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-fabric-ontology) | Remote | | `mcpServer` | Preview | [External MCP server](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-mcp-server) | Remote | | `workIQ` | Preview | [Work IQ](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-work-iq) | Remote | <!-- GA_KNOWLEDGE_SOURCE_MATRIX_END --> The GA `web` kind is Bing-backed web grounding. It is not the separate Web IQ capability, and `mcpServer` is not GA. Foundry IQ, Work IQ, Fabric IQ, and Web IQ are standalone Microsoft IQ capabilities that can be combined; they are not one merged GA layer. Work IQ and Fabric IQ integrations into Foundry remain preview. Use [the migration guide](https://learn.microsoft.com/azure/search/agentic-retrieval-how-to-migrate) before moving code between stable and preview versions. Use the [`2026-04-01` create-or-update reference](https://learn.microsoft.com/rest/api/searchservice/knowledge-sources/create-or-update?view=rest-searchservice-2026-04-01) for the stable wire contract. --- ## 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. API-generation-specific retrieval controls Reasoning and answer-synthesis controls are API-generation-specific. The bundled `2025-05-01-preview` helper does not send persisted reasoning-effort or output-mode properties because that contract doesn't define them. Stable `2026-04-01` Knowledge Bases provide minimal extractive retrieval, while newer preview Knowledge Base versions add documented reasoning and synthesis controls. Never copy those newer fields into a 2025-05 agent request. ### 4. Knowledge Sources For production code on stable `2026-04-01`, choose exactly one or more of `searchIndex`, `azureBlob`, `indexedOneLake`, and `web`. The first three use indexed content; `web` queries Bing at retrieval time. All other kinds in the availability matrix require `2026-05-01-preview`. In particular, direct `file` upload and external `mcpServer` connections are preview-only. Never describe those kinds as GA or treat the GA `web` wire value as Web IQ. --- ## Project Structure The recommended project structure for a Foundry IQ implementation: ``` project-root/ |