Fix Foundry IQ cookbooks: upgrade to azure-search-documents 12.1.0b1 (#44, #5)#50
Merged
Merged
Conversation
Upgrade the Foundry IQ cookbook series from the 11.7.0b2 beta to 12.1.0b1, the latest PyPI release that still supports the preview agentic-retrieval surface (the GA 12.0.0 retrieval request is intents-only and would break the series). Changes: - Bump azure-search-documents to 12.1.0b1 in all three notebooks and READMEs. - Relocate the KnowledgeRetrievalOutputMode import to azure.search.documents.knowledgebases.models (it moved out of indexes.models in 12.1.0b1); update cookbook.instructions.md accordingly. - Episode 3: fix the minimal reasoning-effort retrieval, which the service rejects with 'Messages input not supported when minimal reasoning effort is requested. Use intents input instead.' Minimal effort now uses intents=[KnowledgeRetrievalSemanticIntent(search=...)] in Step 2 and the Step 5 comparison loop. Fixes #44. - Episode 1: add a troubleshooting callout for the Foundry Agent + Search KB MCP integration (masked 401/405), covering RBAC roles, project alignment, AOAI base-endpoint format, and direct-retrieve isolation. Addresses #5. All three notebooks were run end-to-end against live Azure on 12.1.0b1. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the Foundry IQ cookbook series for azure-search-documents==12.1.0b1, aligning notebook code and cookbook guidance with the SDK’s updated agentic retrieval APIs and fixing the minimal reasoning-effort example from #44.
Changes:
- Upgrades cookbook install instructions and notebook
%pip installcells toazure-search-documents==12.1.0b1. - Moves
KnowledgeRetrievalOutputModeimports toazure.search.documents.knowledgebases.models. - Updates Episode 3 minimal reasoning retrieval to use
intentsand adds Episode 1 MCP troubleshooting guidance.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
Foundry-IQ/1-Foundry-IQ-Unlocking-Knowledge-for-Agents/cookbook/README.md |
Updates Episode 1 dependency install command. |
Foundry-IQ/1-Foundry-IQ-Unlocking-Knowledge-for-Agents/cookbook/foundry-iq-cookbook.ipynb |
Updates SDK pin/imports and adds agent/MCP troubleshooting documentation. |
Foundry-IQ/2-Foundry-IQ-Building-the-Data-Pipeline-with-Knowledge-Sources/cookbook/README.md |
Updates Episode 2 dependency install command. |
Foundry-IQ/2-Foundry-IQ-Building-the-Data-Pipeline-with-Knowledge-Sources/cookbook/foundry-iq-cookbook.ipynb |
Updates SDK pin and moved enum import. |
Foundry-IQ/3-Foundry-IQ-Querying-the-Multi-Source-AI-Knowledge-Bases/cookbook/README.md |
Updates Episode 3 dependency install command. |
Foundry-IQ/3-Foundry-IQ-Querying-the-Multi-Source-AI-Knowledge-Bases/cookbook/foundry-iq-cookbook.ipynb |
Updates SDK pin/imports and switches minimal reasoning requests to semantic intents. |
.github/instructions/cookbook.instructions.md |
Updates cookbook package guidance and knowledge base import example. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Maintenance pass on the Foundry IQ cookbook series that upgrades the SDK and fixes the two open technical issues. All three notebooks were run end-to-end against live Azure on the new SDK version before opening this PR.
What changed
1. SDK upgrade to
azure-search-documents==12.1.0b1Bumped from the old
11.7.0b2beta to12.1.0b1, the latest PyPI release that still supports the preview agentic-retrieval surface the cookbooks are built on.Updated in all 3 notebooks + 3 cookbook READMEs.
2. Fix
KnowledgeRetrievalOutputModeimport (all 3 episodes)This enum moved from
azure.search.documents.indexes.modelstoazure.search.documents.knowledgebases.modelsin12.1.0b1. Relocated the import in all notebooks and incookbook.instructions.md.3. Fix minimal reasoning-effort retrieval - Closes #44
The
minimalreasoning effort rejectsmessagesinput with:Episode 3 now uses
intents=[KnowledgeRetrievalSemanticIntent(search=...)]for minimal effort (Step 2 and the Step 5 comparison loop), whilelow/medium/highkeep usingmessages.4. Harden agent + MCP troubleshooting docs - addresses #5
Episode 1 gains a Troubleshooting the agent + MCP connection callout covering the masked
401/405tool-enumeration errors: required RBAC roles, keepingFOUNDRY_PROJECT_ENDPOINT/FOUNDRY_PROJECT_RESOURCE_IDon the same project, the AOAI base-endpoint format, and using a directretrievecall to isolate search vs. agent auth.Validation
Closes #44
Refs #5