Como Conectar uma Base de Conhecimento Foundry IQ ao LangGraph via MCP

Um guia passo a passo para fundamentar um agente LangGraph na recuperação agentica do Microsoft Foundry IQ — sem reconstruir seu pipeline RAG.

Por que essa integração vale a pena

Se você constrói agentes no LangGraph e seu conteúdo empresarial vive no Azure, provavelmente você escreveu o mesmo código duas vezes: um chunker, um trabalho de embedding, um armazenamento vetorial, um recuperador, um reranker e um filtro de permissões acoplado no final. Cada novo agente recebe sua própria cópia. Cada cópia se desvia.

O Foundry IQ move esse trabalho por trás de um único endpoint. Uma base de conhecimento envolve uma ou mais fontes de conhecimento, e o mecanismo de recuperação agentica lida com planejamento de consultas, execução paralela, reranking semântico e (opcionalmente) síntese de respostas. Crucial para qualquer um fora da pilha de agentes da Microsoft: cada base de conhecimento é também um servidor MCP autônomo expondo uma ferramenta, knowledge_base_retrieve. Qualquer cliente compatível com MCP pode chamá-la — incluindo LangGraph, via langchain-mcp-adapters.

Essa é toda a integração. As partes interessantes são os quatro lugares onde ela não se comporta como um recuperador normal, que este tutorial cobre em detalhes:

1. O resultado da ferramenta MCP tem uma forma diferente da resposta de recuperação REST/SDK.
2. Tokens Bearer expiram, e um dicionário de cabeçalhos estáticos falhará uma hora em um gráfico de longa duração.
3. A filtragem de permissões por usuário requer um segundo token, distinto de suas credenciais de serviço.
4. A base de conhecimento é ela mesma um planejador, então você tem dois planejadores por turno e precisa decidir quem faz o quê.

No final, você terá um agente LangGraph funcionando fundamentado em uma base de conhecimento do Foundry IQ, com citações preservadas no estado do gráfico e um provedor de tokens que sobrevive a longas sessões.

O que você já deve saber: noções básicas do LangGraph (StateGraph, ToolNode, o loop ReAct), e o suficiente sobre Azure para criar um recurso e atribuir um papel.

Arquitetura

Figura 1 — A base de conhecimento possui a recuperação. LangGraph possui a orquestração. MCP é o contrato entre eles.

Três coisas merecem ser notadas antes de você escrever qualquer código.

A base de conhecimento é reutilizável. Não está restrita a um agente. A mesma base de conhecimento pode fundamentar um agente LangGraph, um agente do Foundry Agent Service e uma integração do Copilot simultaneamente. Esse é o ponto da abstração, e muda como você nomeia as coisas — nomeie as bases de conhecimento após tópicos (hr-policy-kb, product-docs-kb), não após o agente que acontece de consumi-las primeiro.

Fontes vêm em dois sabores. Fontes indexadas (Blob, OneLake, um índice de busca existente) são ingeridas, divididas em partes e vetorizadas em um índice em seu serviço de busca. Fontes federadas (SharePoint remoto, web, servidores MCP) são consultadas ao vivo no momento da recuperação e nunca são ingeridas. Essa distinção importa para permissões, que retornamos no Passo 7.

A identidade flui em dois canais. Seu aplicativo se autentica no serviço de busca com uma identidade de serviço. Opcionalmente, você também passa a identidade do usuário final em um cabeçalho separado para que o mecanismo filtre documentos que esse usuário pode não ver. Confundir esses dois é a fonte mais comum de bugs do tipo "por que todos estão vendo tudo".

Pré-requisitos

• Um serviço de busca AI do Azure com recuperação agentica disponível em sua região. Nível básico ou superior se você quiser suporte à identidade gerenciada.
• Um projeto e recurso do Microsoft Foundry, com uma implantação de LLM (por exemplo, gpt-5-mini) e um modelo de embedding (por exemplo, text-embedding-3-large).
• O papel de Leitor de Dados do Índice de Busca atribuído à identidade que consultará a base de conhecimento.
• Se sua base de conhecimento especifica um LLM, o serviço de busca precisa de uma identidade gerenciada com Usuário de Serviços Cognitivos no recurso do Foundry.
• Python 3.10+.

Instale as bibliotecas cliente:

# SDK de Pré-visualização — necessário para síntese de respostas, esforço de raciocínio configurável,
# permissões em nível de documento e recuperação de múltiplas interações.
pip install --pre azure-search-documents

# SDK Estável é suficiente se você só precisa de recursos GA em 2026-04-01:
# pip install azure-search-documents

pip install azure-identity langchain-mcp-adapters langgraph langchain-openai httpx

Uma palavra sobre versões de API antes de você começar

Esta é a decisão que irá te prejudicar mais tarde se você errar, então faça isso deliberadamente agora.

A recuperação agentica está geralmente disponível na API REST 2026-04-01. A 2026-05-01-preview adiciona síntese de respostas, esforço de raciocínio configurável, a entrada messages, permissões em nível de documento e metadados de rótulo de sensibilidade. Tanto o portal do Azure quanto o portal do Microsoft Foundry expõem um comportamento apenas de pré-visualização, independentemente do que seu código usa, o que significa que o portal não é uma pré-visualização confiável do que seu código de produção fará.

A versão da API também muda o comportamento do MCP diretamente. Com 2026-05-01-preview, a base de conhecimento pode retornar respostas sintetizadas quando configurada com um LLM e um esforço de raciocínio compatível. Com 2026-04-01, a recuperação MCP é sempre mínima e extrativa, e a conexão retorna apenas dados de fundamentação.

Escolha 2026-04-01 se você está enviando para produção agora e pode viver com fundamentação extrativa. Escolha 2026-05-01-preview se você precisa de síntese ou filtragem de permissões, e aceite que não há SLA.

Passo 1 — Crie a fonte de conhecimento e a base de conhecimento

Uma fonte de conhecimento aponta para seu conteúdo. Uma base de conhecimento envolve uma ou mais fontes com configuração de recuperação. Crie a fonte primeiro.

import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    KnowledgeBase,
    KnowledgeSourceReference,
    KnowledgeBaseAzureOpenAIModel,
    AzureOpenAIVectorizerParameters,
    SearchIndexKnowledgeSource,
    SearchIndexKnowledgeSourceParameters,
)