# Foundry Iq

> >

- **Type:** Skill
- **Install:** `agentstack add skill-aiappsgbb-awesome-gbb-foundry-iq`
- **Verified:** Pending review
- **Seller:** [aiappsgbb](https://agentstack.voostack.com/s/aiappsgbb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aiappsgbb](https://github.com/aiappsgbb)
- **Source:** https://github.com/aiappsgbb/awesome-gbb/tree/main/skills/foundry-iq

## Install

```sh
agentstack add skill-aiappsgbb-awesome-gbb-foundry-iq
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 `postdeploy_grant_agent_search_rbac.py` hook
> wired into `azure.yaml` after `azd deploy agent` — otherwise every new
> agent version regresses the grant for the new `instance_identity`.
>
> **RBAC propagation on AI Search is slow** — up to 5-10 minutes (vs 30-60s
> for most resources). If the first `corpus_query` 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).

```bash
# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aiappsgbb-awesome-gbb-foundry-iq
- Seller: https://agentstack.voostack.com/s/aiappsgbb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.