Read this article in English

Numa revisão de arquitetura, o slide do agente tinha uma caixa só, escrita “Microsoft IQ”, e a primeira pergunta da sala foi qual IQ comprar. O time já tinha escolhido: Fabric IQ, para o assistente do gerente de relacionamento de um banco. A escolha fazia sentido — o dado do cliente mora no OneLake, e a ontologia já tinha Cliente, Contrato e Exposição. O protótipo respondia bem sobre limite e exposição e errava as outras três perguntas que o gerente faz antes de toda visita: o que ficou combinado na última reunião, o que a política de crédito permite renegociar e o que a imprensa publicou sobre o cliente. Nenhuma das três mora no OneLake. O produto estava certo para uma pergunta; o gerente fazia quatro.

A pergunta antes do produto Microsoft IQ é o nome de um conjunto, não de um produto. A documentação o apresenta como “a unified intelligence layer for enterprise AI”, feita de “four interconnected capabilities”: Work IQ, Fabric IQ, Foundry IQ e Web IQ. Cada camada responde a um tipo de pergunta, com lugar do dado, porta de entrada, status, identidade e fronteira próprios. A regra cabe numa linha — escolha a camada pela pergunta, não pelo nome do produto —, e este artigo é o mapa; os mergulhos em cada camada estão nos artigos linkados ao longo do texto.

O que é o Microsoft IQ?

O hub da documentação descreve cada camada pelo contexto que ela entrega ao agente:

• Work IQ — “live understanding of how employees work, with context on people, collaboration, and workflows”: o trabalho em andamento no Microsoft 365.
• Fabric IQ — “the live state of the business, so agents understand business entities and their relationships, properties, actions, and rules”: o estado do negócio, sobre o OneLake.
• Foundry IQ — “curated institutional knowledge on the context of policies, authoritative documents, and reusable knowledge bases”: o conhecimento curado, em bases reutilizáveis.
• Web IQ — “fresh, real-world intelligence from across the web”: o que o mundo publicou.

Cada camada é um produto com vida própria: “Each IQ workload is standalone, but you can use them together to provide comprehensive organizational context for agents.” Ninguém liga o Microsoft IQ; liga cada camada, no serviço dela, que cobra pelo que está por baixo — as moedas de cobrança ficam para um artigo próprio. O Agent 365, citado no mesmo hub, fica fora das quatro capacidades: governar a frota de agentes é outra conversa.

Até a contagem varia: o hub fala em quatro, e as páginas do Foundry IQ, em “three IQ workloads”. A diferença coincide com o acesso limitado do Web IQ — e lembra que entra na arquitetura o que você consegue contratar, com o status que a página declara no dia em que você lê.

O problema que resolve

Agente corporativo responde mal por falta de contexto, e o contexto de uma empresa mora em lugares diferentes, com donos e permissões diferentes. Antes das camadas de IQ, cada time montava a sua ponte: um conector copiava e-mail e arquivos para um índice vetorial, um job de sync tentava manter a permissão em dia, uma camada semântica era redesenhada para o agente, um RAG próprio cuidava dos manuais e uma API de busca trazia a web. Cada ponte tinha pipeline, credencial e modo de falha próprios.

As camadas de IQ tiram essas pontes das suas mãos, cada uma no seu território. O Work IQ consulta o Microsoft 365 ao vivo, com a permissão do usuário — o artigo sobre o Work IQ mostra o índice que deixa de existir. O Fabric IQ dá vocabulário de negócio ao dado do OneLake, com o modelo semântico e a ontologia; o contrato de entrada do data agent e o preço do refresh da ontologia cobrem essa camada. O Foundry IQ transforma o RAG de cada agente numa base compartilhada: “Multiple agents can share the same knowledge base.” E o Web IQ entrega a web pronta para o contexto do modelo.

O que as camadas não resolvem é a escolha. O nome em comum sugere um produto só, mas uma pergunta de negócio raramente cabe numa camada: a do gerente cabia em quatro. O nome é um; a decisão são quatro — e cada uma tem status, identidade e fronteira próprios.

Como funciona — passo a passo

1. Decomponha a pergunta. “Posso renegociar com este cliente?” vira quatro: qual é a exposição dele, o que ficou combinado na última reunião, o que a política permite e o que saiu sobre ele na imprensa. Cada parte tem um lugar onde o dado mora.
2. Mapeie cada parte para a camada do dado. Conversa, reunião e arquivo do Microsoft 365 vão para o Work IQ; número e entidade de negócio no OneLake, para o Fabric IQ; política, contrato e manual curados, para o Foundry IQ; o que está publicado na web, para o Web IQ.
3. Confira o status por componente e por versão de API. No Foundry IQ, ele depende da versão da API REST; no Fabric IQ, o data agent é GA dentro de um workload em preview.
4. Defina quem responde em cada parte. Para cada camada, anote de quem é a identidade que chega ao dado: o usuário, direto ou por on-behalf-of (OBO); a identidade gerenciada de um projeto; ou ninguém, quando a fonte é pública.
5. Escolha a porta da composição. Ou o agente chama cada camada como ferramenta, ou uma knowledge base do Foundry IQ reúne as fontes. A regra do artigo sobre o Work IQ vale aqui: compor por agente preserva a identidade; compor por catálogo troca a identidade.
6. Registre a fronteira de cada parte. Onde o dado é processado e sob quais termos — da fronteira do Microsoft 365 até fora da fronteira do Azure, no caso da web.
7. Date a decisão. Status e versões de API mudam entre uma revisão e outra; guarde a página e a data da leitura. As deste artigo foram conferidas em 03/10/2026.

As quatro perguntas, uma por camada

O jeito mais rápido de escolher é perguntar o que o agente precisa saber. A tabela resume a correspondência; as subseções dizem o que a documentação garante em cada camada.

Work IQ: o trabalho em andamento

O Work IQ entende como as pessoas trabalham: e-mail, reunião, chat, arquivo e, segundo a visão geral, também “business and workflow data from Dynamics 365 and Power Platform”. A porta é a Work IQ API: “Work IQ API endpoints include A2A, a remote MCP server, and a REST API. Usage is independent of Microsoft 365 Copilot licensing”. O anúncio de licenciamento marcou a disponibilidade geral — “On June 16, Work IQ API reaches general availability” —, com cobrança em Copilot Credits e uma frase que encerra a discussão de licença: “There is no separate Work IQ API subscription, SKU, or per-user license.” A identidade é sempre a do usuário; endpoints, consentimento e composição estão no artigo sobre o Work IQ.

Fabric IQ: o estado do negócio

O Fabric IQ traz “three layers of business context into Microsoft IQ: unified data, business intelligence, and operational intelligence”, entregues por dois itens centrais, a ontologia, em preview, e o modelo semântico, sobre o OneLake. A ontologia descreve entidades, relações, regras e métricas e pode nascer de um modelo semântico, com as measures DAX virando métricas. Ao redor, o “IQ (preview) workload” agrupa Planning, Graph, data agent e operations agent. A pergunta dessa camada é de número e de estado: exposição, saldo, inadimplência, posição. Quem responde, em geral, é o data agent — “a generally available feature”, que pede capacidade F2 ou superior, ou P1 ou superior.

Foundry IQ: o conhecimento curado

O Foundry IQ é o RAG que virou serviço, e a FAQ diz de onde ele vem: “Foundry IQ is built on Azure AI Search’s agentic retrieval capabilities. You must create a knowledge base in Azure AI Search to use Foundry IQ.” A knowledge base agrupa knowledge sources — índices existentes, Blob, OneLake, SharePoint, a web e, em preview, o próprio Work IQ — atrás de um endpoint só. O agente do Microsoft Foundry a consulta pela ferramenta knowledge_base_retrieve, e a página de conexão é taxativa: “This is the only tool currently supported for use with Foundry Agent Service.” A recuperação agêntica por baixo — planejamento de consulta, subconsultas, reranking — está no artigo sobre RAG avançado.

Web IQ: o que está lá fora

O Web IQ é “a suite of AI-native APIs” sobre páginas, notícias, imagens e vídeos, “built on twenty years of Bing search infrastructure”, com acesso por “REST, MCP (JSON-RPC 2.0), or SDK”. A página anuncia 164 ms de p95. Mas o que decide o desenho é o acesso: o Web IQ “is currently available in limited access to select enterprise customers building AI agents and applications at scale”, com prioridade para quem trabalha com o time de conta da Microsoft. A pergunta dessa camada é externa — notícia, norma publicada, movimento de mercado —, e ela traz uma decisão de fronteira que as outras três não trazem.

O status não é uniforme

Perguntar se o Microsoft IQ é GA não tem resposta. O status mora em cada componente e, no Foundry IQ, ainda depende da versão da API. A tabela é a foto do que as páginas declaravam em 03/10/2026.

Três leituras saem dessa tabela.

O status é por versão de API. A página do Foundry IQ diz: “Some Foundry IQ features are now generally available, while others remain in preview. Availability depends on the Search Service REST API version you use. The Microsoft Foundry portal and Azure portal continue to provide preview-only access to all agentic retrieval features.” Na 2026-04-01, “the searchIndex, azureBlob, indexedOneLake, and web knowledge source types are generally available. Other knowledge source types remain in preview.” Quem monta a knowledge base pelo portal está em preview, mesmo usando um tipo de fonte que é GA na API. Para produção com SLA, a knowledge base nasce por código, na versão estável.

As integrações que passam pelo Foundry IQ estão em preview. O Work IQ como knowledge source, a ontologia como knowledge source, o índice do AI Search dentro do data agent e a própria conexão do agente à knowledge base estão em preview. Já o encontro no Copilot — dados do Power BI no Copilot Chat e o plugin do Fabric IQ no Cowork — é GA. Nas páginas lidas para este artigo, o caminho mais maduro entre duas camadas passa pelo Microsoft 365 Copilot, não pelo Foundry.

O GA de um componente não promove o vizinho. O data agent é GA; publicá-lo no Microsoft 365 Copilot, não. A Work IQ API é GA; usá-la como knowledge source, não. A ontologia segue em preview e ganhou uma experiência nova — a antiga sai em 31/01/2027, como registra a nota no artigo sobre a ontologia. A revisão de arquitetura precisa de uma linha por componente, não por produto.

Quem responde em cada camada

Em agente corporativo, a pergunta de segurança não é se o dado está protegido. É de quem é a identidade que chega ao dado em cada chamada. As quatro camadas respondem de jeitos diferentes.

No Work IQ, a regra é simples e rígida: delegado, com OBO aceito, e “Application-only authentication isn’t supported.” A página da API completa: “Microsoft 365 permissions, sensitivity labels, and compliance policies are enforced automatically.” No Fabric, o data agent “uses the requesting user’s credentials and permissions to enforce least-privilege access”, e as respostas do Power BI no Copilot Chat respeitam a segurança por linha e por objeto (RLS e OLS) do modelo semântico. A exceção está no MCP da ontologia: “Due to a known issue, you can’t currently use Service Principal to access the ontology MCP.”

No Foundry IQ mora a armadilha. A conexão do agente à knowledge base usa a identidade gerenciada do projeto; o filtro por usuário depende de outro token, que o seu código precisa encaminhar no header x-ms-query-source-authorization. A página de conexão é explícita: “Without the token, permission-enabled sources return results unfiltered.” E a FAQ põe o limite do que é filtrado: “User-level access controls are only enforced when the knowledge source supports document-level permissions and when those permissions have been explicitly configured for synchronization.” Na versão estável falta uma peça: o guia de migração manda remover o ingestionPermissionOptions das fontes azureBlob e indexedOneLake, porque “This property isn’t supported in 2026-04-01.” E a aplicação de permissão na consulta está documentada como preview.

O knowledge source do Work IQ tem regras próprias. A autenticação é OBO, por um app registration do cliente; o token vai num header separado, x-ms-query-work-iq-source-authorization — “not x-ms-query-source-authorization”. A página ainda traz um aviso que muda a natureza da fonte: “In this preview, a Work IQ knowledge source might use Work IQ capabilities that perform actions, not just retrieve information. Use it with care, limit access to trusted applications and users…” Uma fonte de recuperação que pode agir não entra numa knowledge base compartilhada sem revisão.

Na ontologia como knowledge source, a página pede o papel Search Index Data Contributor para o projeto do Foundry, no recurso do Azure AI Search, e avisa que, sem ele, “you see a 403 error in the Foundry agent”. Ela não diz com que identidade a consulta chega à ontologia. Sem essa resposta escrita, teste com dois usuários de permissões diferentes antes de levar dado com RLS por esse caminho. No sentido inverso, a página do índice do AI Search como fonte do data agent é clara: “the Data Agent sends the user’s identity to the Azure AI Search index.”

A regra do artigo sobre o Work IQ segue sendo o melhor atalho, e a knowledge base fica no meio dela. Fonte remota — Work IQ, SharePoint remoto, web — consulta o sistema na hora, com o token do usuário quando a fonte usa um. Fonte indexada é cópia: o filtro só existe se a permissão veio na ingestão e se o token chega na consulta.

Onde as camadas se encontram

As camadas se encontram em três lugares, e cada encontro tem status e identidade próprios.

No agente. O agente chama cada camada como ferramenta — o Work IQ por OBO, o data agent do Fabric, a knowledge base do Foundry IQ — e cada plataforma aplica a própria permissão. É o caminho que preserva a identidade, e o artigo sobre o Work IQ mostra as ferramentas e as exceções.

Na knowledge base do Foundry IQ. O dado das outras três camadas chega a ela como fonte: o do Work IQ, em preview; o do Fabric, pela ontologia, em preview, ou pelo OneLake indexado, GA; e a web, GA — mas pelo Grounding with Bing, não pelo Web IQ.

             agente no Foundry Agent Service
                           │
      knowledge_base_retrieve, por MCP (preview)
                           │
           knowledge base no Azure AI Search
   ┌──────────────┬────────┴─────┬──────────────┐
   │              │              │              │
 Work IQ        ontologia      OneLake, Blob  web: Grounding
 remota, OBO    do Fabric      e índice       with Bing
 (preview)      (preview)      (GA)           (GA, fora do DPA)

O endpoint MCP da knowledge base usa a 2026-08-01-preview, e a conexão do projeto a ele é do tipo RemoteTool, também em preview, autenticada pela identidade gerenciada do projeto. Para quem quer só a knowledge base estável, o caminho é a API REST na 2026-04-01, chamada pelo próprio código.

No Microsoft 365 Copilot. As respostas com dados do Power BI no Copilot Chat são GA, e o Copilot “interprets and reconciles data answers with your broader Microsoft 365 context, including your files, chats, and emails.” É o contexto do Fabric encontrando o do trabalho, dentro do Copilot. O preço de entrada está na mesma página: “Microsoft 365 Copilot Premium license: Required for all users.” O frescor é o do modelo: “Answers reflect the data from the last refresh of the semantic model, not real-time data.” E data agent e ontologia não entram sozinhos: “Fabric data agents and ontologies can’t answer questions in Copilot Chat without an explicitly published Microsoft 365 agent.” — e a publicação do data agent no Microsoft 365 Copilot está em preview.

Entre o segundo e o terceiro encontro há uma parede. Diz a FAQ do Foundry IQ: “you can’t use Foundry IQ knowledge sources in Copilot, and you can’t use Copilot knowledge sources in Foundry IQ.” A knowledge source definida no Foundry não serve de fonte no Copilot, e o conhecimento configurado no Copilot não entra no Foundry. A passagem documentada é pelo agente: a página do Foundry IQ mostra como adicionar ao Copilot Studio o agente do Foundry Agent Service já conectado à knowledge base. Escolher o ponto de encontro é escolher o ecossistema da resposta; o que atravessa a parede é o agente, não a fonte.

A fronteira de cada camada

Em banco e seguradora, a pergunta que encerra a revisão é até onde o dado vai. A resposta muda de camada para camada — e, no Fabric, muda conforme a porta.

No Fabric, a porta muda a fronteira. Para o Copilot Chat, “Power BI data answering requires Azure OpenAI processing in the United States or European Union. For Fabric tenants outside these geographies, enable this setting to allow the required cross-geography processing.” Um tenant no Brasil só usa o recurso com o processamento cross-geo ligado. O data agent tem as suas chaves — “Enable cross-geo processing and cross-geo storing for AI” — e uma trava de região: ele “can’t execute queries when the data source’s workspace capacity is in a different region than the data agent’s workspace capacity”. Publicado no Microsoft 365 Copilot, o termo muda: “responses returned by Fabric data agents may be sent outside of Fabric’s compliance boundary or geographic region, and processed and/or stored according to the Microsoft 365’s terms…”

No Foundry IQ, a fronteira é a dos serviços por baixo: ele “is subject to the regional availability and billing of its underlying services: Azure AI Search and, if applicable, Azure OpenAI in Foundry Models”.

A web é onde a fronteira cai. A fonte web do Foundry IQ usa o Grounding with Bing — “Bing Custom Search is always the search provider for Web Knowledge Source” — e a página não suaviza: “The Microsoft Data Protection Addendum doesn’t apply to data sent to Web Knowledge Source. When Customer uses Web Knowledge Source, Customer Data flows outside the Azure compliance and Geo boundary.” Sem lista de domínios, “Web Knowledge Source has unrestricted access to the entire public internet.” A página das ferramentas de Bing no Foundry diz o que sai: “the only information sent to Bing is the Bing search query, tool parameters, and your resource key”. Nenhum dado do usuário final vai junto, mas a consulta é montada a partir do que o usuário perguntou — e pode levar o nome do cliente.

O Web IQ não é o mesmo serviço. A página do produto o separa do Bing — “Web IQ is purpose-built for AI agents and multi-step workflows, while Grounding with Bing is designed for traditional search…” — e acrescenta: “Grounding with Bing remains available for existing customers as an accessible entry point.” Ela não publica termos de privacidade nem de conformidade, e o acesso é limitado. Em instituição sujeita à LGPD e às normas do Banco Central sobre nuvem, a camada web passa pelo encarregado de dados e pelo compliance antes de passar pela arquitetura.

Como escolher

A árvore resume a decisão para cada parte da pergunta.

A parte da pergunta é sobre...
├─ quem disse, decidiu ou combinou?  ──► Work IQ
├─ quanto, quantos, em que estado?   ──► Fabric IQ
├─ o que diz a política, o contrato? ──► Foundry IQ
└─ o que o mundo publicou?           ──► web *

Uma parte só?  Use a camada sozinha.
Mais de uma?   Componha pelo agente quando a identidade
               do usuário importa; pela knowledge base
               quando as fontes são documentos e índices.

* Web IQ em acesso limitado; no Foundry IQ, a fonte web
  é o Grounding with Bing, fora do DPA.

No caso do gerente de relacionamento, o desenho final ficou assim. A exposição veio do data agent do Fabric, GA, com RLS por carteira. A última reunião veio do Work IQ, por OBO. A política de renegociação veio de uma knowledge base do Foundry IQ sobre os documentos da área de crédito, num tipo de fonte GA e criada por código na 2026-04-01; a conexão do agente a ela, em preview, entrou como risco registrado. E a notícia ficou fora do agente até o compliance decidir sobre a fonte web. O agente compõe as três primeiras como ferramentas, com o token do gerente em cada chamada. Ninguém comprou o Microsoft IQ. Cada parte da pergunta ganhou a sua camada, o seu status e a sua identidade.

Um caso de uso: o sinistro na seguradora

A mesma árvore serve fora do banco. Na seguradora, a pergunta que segura a fila é a do analista de sinistros: “posso pagar este sinistro?”. Num seguro residencial, com aviso de sinistro por alagamento depois de um temporal, ela vira quatro:

• A apólice está em vigor e tem a cobertura contratada? Vigência, coberturas, prêmio pago e histórico do segurado moram no OneLake. É o Fabric IQ, pelo data agent, GA, com RLS por regional.
• O que o corretor e o perito já disseram? O laudo chegou por e-mail, e a vistoria foi combinada numa reunião. É o Work IQ, por OBO, com as permissões do analista.
• O que dizem as condições gerais e o manual de regulação? Franquia, limites e exclusões da cobertura. É o Foundry IQ, numa knowledge base: com os documentos no Blob, o tipo de fonte é GA na 2026-04-01; no SharePoint, é preview.
• O que o mundo publicou sobre o temporal? Notícia, alerta da Defesa Civil, decreto de emergência. É a camada web: o Web IQ, em acesso limitado, ou a fonte web do Foundry IQ, que é o Grounding with Bing.

O agente compõe as três primeiras como ferramentas. O data agent e o Work IQ chegam ao dado com a identidade do analista; a knowledge base, com a identidade do projeto, mais o token do analista no header. Nas condições gerais, o token não filtra nada, porque elas valem para todos os analistas — é isso que permite deixá-las no Blob, na versão GA, em que o ingestionPermissionOptions não é suportado. Se a base recebesse o laudo do perito, que nem todo analista pode ler, a conta mudaria: permissão por documento, que no Blob fica fora da versão GA. A conexão do agente à knowledge base segue em preview e entra como risco registrado, como no caso do gerente.

A quarta parte espera o compliance. A consulta web é montada a partir do aviso de sinistro e pode levar o endereço do segurado, dado pessoal sob a LGPD; pela fonte web do Foundry IQ, ela sai da fronteira do Azure. Até a decisão, o analista confere o evento por fora do agente, como já fazia.

O ganho não é um produto novo. É uma resposta em quatro partes, cada uma com a sua origem, no lugar de quatro sistemas abertos lado a lado. A pergunta do analista é uma; as camadas são quatro — e a decisão de compliance vem antes da quarta.

Na prática: montando o agente do sinistro

O caso diz o que entra no agente; esta seção mostra como montá-lo, em seis passos, na ordem em que um depende do outro. Os nomes — sinistros-kb, fabric-apolices, agente-sinistros — são exemplos; comandos, papéis e versões de API vêm das páginas oficiais listadas nas referências.

O ponto de partida é o inventário, uma linha por parte da pergunta:

A última coluna pede uma linha no registro de riscos: as três ligações do agente estão em preview, mesmo quando o que está atrás delas é GA. Registre cada uma com a página e a data.

Passo 1 — A knowledge base das condições gerais

É a peça que não depende das outras. Os PDFs das condições gerais e do manual de regulação vão para um container do Blob, e a knowledge base nasce por código, na 2026-04-01 — pelo portal, ela seria preview. Três identidades precisam de papel: a identidade gerenciada do serviço de busca, de Storage Blob Data Reader na conta de armazenamento e de Cognitive Services User no recurso do Microsoft Foundry; quem cria, de Search Service Contributor e Search Index Data Contributor; quem testa, de Search Index Data Reader.

# Token: az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv
@search-endpoint = https://<servico-de-busca>.search.windows.net
@search-access-token = <token>
@aoai-endpoint = <endpoint-do-azure-openai>

### 1. Knowledge source: o container das condições gerais
PUT {{search-endpoint}}/knowledgesources/sinistros-condicoes-ks?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "sinistros-condicoes-ks",
  "kind": "azureBlob",
  "description": "Condições gerais do seguro residencial e manual de regulação de sinistros.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "ResourceId=<id-da-conta-de-armazenamento>",
    "containerName": "condicoes-gerais",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
      "identity": null,
      "disableImageVerbalization": null,
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "gpt-5-mini",
          "modelName": "gpt-5-mini"
        }
      },
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      },
      "contentExtractionMode": "minimal",
      "ingestionSchedule": null
    }
  }
}

### 2. Status da ingestão
GET {{search-endpoint}}/knowledgesources/sinistros-condicoes-ks/status?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}

### 3. Knowledge base
PUT {{search-endpoint}}/knowledgebases/sinistros-kb?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "sinistros-kb",
  "description": "Franquias, limites e exclusões das coberturas do seguro residencial.",
  "knowledgeSources": [{ "name": "sinistros-condicoes-ks" }],
  "encryptionKey": null
}

### 4. Teste de recuperação
POST {{search-endpoint}}/knowledgebases/sinistros-kb/retrieve?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "intents": [{ "type": "semantic", "search": "franquia e exclusões da cobertura de alagamento" }]
}

A ingestão terminou quando lastSynchronizationState.endTime tem valor e itemsUpdatesFailed é zero; o erro de cada documento aparece em currentSynchronizationState.errors. A criação gera data source, skillset, indexer e índice, e a página pede que eles não sejam editados à mão. Na 2026-04-01, a recuperação é mínima e extrativa: a knowledge base devolve os trechos, e quem redige é o agente. É aqui também que o laudo do perito fica de fora: permissão por documento no Blob depende do ingestionPermissionOptions, que só existe na 2026-08-01-preview.

Passo 2 — O data agent das apólices

A RLS vem antes do agente. No modelo semântico, uma tabela de mapeamento liga cada analista à sua regional, e o papel de segurança filtra por ela com [EmailAnalista] = USERPRINCIPALNAME(). A página de RLS traz três detalhes que decidem se o filtro funciona: a tabela guarda o UPN, não o atributo de e-mail do Entra ID; os membros entram no papel pelo serviço, na página de segurança do modelo; e a RLS não vale para Admin, Member nem Contributor do workspace. Por isso o analista recebe só Read no modelo — que, pelo data agent, basta para consultar, sem papel no workspace.

Com o modelo protegido, o data agent sai em quatro movimentos:

1. Crie o data agent e adicione o modelo semântico. Cabem até cinco fontes por agente.
2. Escreva as instruções em inglês. São até 15.000 caracteres, e a página de conceitos é direta: “The Fabric data agent doesn’t currently support non-English languages.” Modelo semântico não aceita pares de exemplo de consulta, então o peso fica nas instruções — o contrato de entrada do data agent detalha o que isso muda.
3. Publique com uma descrição. Ela ajuda “other AI systems/orchestrators to effectively invoke the Fabric data agent” — aqui, o agente do Foundry.
4. Compartilhe o agente e o dado, depois de publicar. Compartilhado antes, quem tem só a permissão padrão não consegue consultar; e, sem a permissão mínima na fonte, as consultas “fail or return empty results”.

Quatro pré-requisitos da ferramenta costumam passar despercebidos: capacidade F2 ou P1, no mínimo; data agent e projeto do Foundry no mesmo tenant; agente e fontes em capacidades da mesma região; e nada de service principal, que a ferramenta do Fabric não aceita.

Passo 3 — A conexão do Work IQ

O Work IQ tem a montagem mais longa, porque parte dela é do tenant, e não do projeto. Na ordem:

1. Cobrança. A Work IQ API usa cobrança por uso, em Copilot Credits, num plano configurado no Copilot Studio; sem ela, a chamada volta 403.
2. Service principal do Work IQ, criado uma vez por tenant por um Global Administrator, com o papel ativado just in time pelo PIM e desativado no fim. Sem esse passo, o Work IQ nem aparece na busca de permissões de API.
3. App registration da seguradora, de um tenant só, com a permissão delegada WorkIQAgent.Ask e consentimento de administrador. É o único caminho: “Only Bring your own Entra app (On-Behalf-Of authentication) is supported for Work IQ connections.”
4. Segredo do app no Key Vault. A página manda guardá-lo num cofre aprovado, nunca no código nem em log, e girá-lo antes de expirar.
5. Conexão no projeto, criada por quem tem Foundry Project Manager.

# Uma vez por tenant, com o Global Administrator ativado pelo PIM
az ad sp create --id fdcc1f02-fc51-4226-8753-f668596af7f7

# A conexão do projeto; o segredo vem do cofre, nunca do código
PROJECT_ENDPOINT="https://<conta>.services.ai.azure.com/api/projects/<projeto>"
TENANT_ID="<id-do-tenant>"
CLIENT_ID="<id-do-app-registration>"
CLIENT_SECRET="$(az keyvault secret show --vault-name "<cofre>" --name workiq-client-secret --query value -o tsv)"

azd ai connection create workiq-conn \
  --project-endpoint "$PROJECT_ENDPOINT" \
  --kind remote-a2a \
  --target https://workiq.svc.cloud.microsoft/a2a/ \
  --auth-type oauth2 \
  --authorization-url "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/authorize" \
  --token-url "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  --refresh-url "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET" \
  --scopes "api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access"

Criada a conexão, o Foundry mostra uma URL de redirecionamento OAuth, que entra no app registration em Authentication > Add a platform > Web. Os campos da conexão não se editam depois: errou, apague e recrie. O papel Foundry User no projeto vai para o desenvolvedor, para a identidade de runtime do agente e para cada analista; se aparecer “Principal does not have access to API/Operation”, a página manda atribuí-lo também no escopo da conta. E um aviso da página vai para o compliance, ao lado do da web: chamado pelo agente, o dado do Work IQ “might be processed outside the Azure compliance boundary”.

Passo 4 — O agente com as três ferramentas

Com as três peças de pé, o agente é um script. Ele cria as duas conexões que faltam — o MCP da knowledge base e o data agent —, monta as três ferramentas e faz a primeira pergunta.

# pip install "azure-ai-projects>=2.3.0" azure-identity requests
import os

import requests
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    FabricDataAgentToolParameters,
    MCPTool,
    MicrosoftFabricPreviewTool,
    PromptAgentDefinition,
    StructuredInputDefinition,
    ToolProjectConnection,
    WorkIQPreviewTool,
)
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

credential = DefaultAzureCredential()
project = AIProjectClient(endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], credential=credential)
project_resource_id = os.environ["FOUNDRY_PROJECT_RESOURCE_ID"]  # /subscriptions/.../accounts/<conta>/projects/<projeto>
search_endpoint = os.environ["SEARCH_ENDPOINT"]  # https://<servico-de-busca>.search.windows.net

# Conexões do projeto, pelo Azure Resource Manager (exige connections/write no projeto)
arm_token = get_bearer_token_provider(credential, "https://management.azure.com/.default")
arm = {"Authorization": f"Bearer {arm_token()}"}
connections = f"https://management.azure.com{project_resource_id}/connections"

# 1. MCP da knowledge base: a identidade gerenciada do projeto chega ao AI Search
kb_mcp = f"{search_endpoint}/knowledgebases/sinistros-kb/mcp?api-version=2026-08-01-preview"
requests.put(
    f"{connections}/sinistros-kb-mcp?api-version=2025-10-01-preview",
    headers=arm,
    json={
        "name": "sinistros-kb-mcp",
        "type": "Microsoft.MachineLearningServices/workspaces/connections",
        "properties": {
            "authType": "ProjectManagedIdentity",
            "category": "RemoteTool",
            "target": kb_mcp,
            "isSharedToAll": True,
            "audience": "https://search.azure.com/",
            "metadata": {"ApiType": "Azure"},
        },
    },
).raise_for_status()

# 2. Data agent publicado: os GUIDs vêm da URL .../groups/<workspace_id>/aiskills/<artifact_id>
requests.put(
    f"{connections}/fabric-apolices?api-version=2025-04-01-preview",
    headers=arm,
    json={
        "properties": {
            "category": "CustomKeys",
            "authType": "CustomKeys",
            "credentials": {
                "keys": {
                    "workspace_id": os.environ["FABRIC_WORKSPACE_ID"],
                    "artifact_id": os.environ["FABRIC_DATA_AGENT_ID"],
                }
            },
        }
    },
).raise_for_status()

fabric_id = project.connections.get("fabric-apolices").id
workiq_id = project.connections.get("workiq-conn").id  # criada no passo 3

# Em inglês, como as perguntas que o agente repassa ao data agent
INSTRUCTIONS = """
You help home insurance claims analysts decide whether a claim can be paid.
- Policy status, coverage, premium payments and claim history: use the Fabric tool.
  Ask it in English.
- What the broker and the adjuster said in email, chats and meetings: use Work IQ.
- Policy terms, deductibles, limits and exclusions: use the knowledge base.
  If it has no answer, say "I don't know".
- You have no web access. Ask the analyst to check news, weather alerts and
  emergency decrees outside this agent.
Answer in the language of the question and cite the source of each part.
"""

project.agents.create_version(
    agent_name="agente-sinistros",
    definition=PromptAgentDefinition(
        model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
        instructions=INSTRUCTIONS,
        tools=[
            MicrosoftFabricPreviewTool(
                fabric_dataagent_preview=FabricDataAgentToolParameters(
                    project_connections=[ToolProjectConnection(project_connection_id=fabric_id)]
                )
            ),
            WorkIQPreviewTool(project_connection_id=workiq_id),
            MCPTool(
                server_label="condicoes-gerais",
                server_url=kb_mcp,
                require_approval="never",
                allowed_tools=["knowledge_base_retrieve"],
                project_connection_id="sinistros-kb-mcp",  # aqui vai o nome, não o ID
                headers={"x-ms-query-source-authorization": "{{search_auth_token}}"},
            ),
        ],
        structured_inputs={
            "search_auth_token": StructuredInputDefinition(
                description="Per-user Azure AI Search bearer token",
                required=True,
                schema={"type": "string"},
            )
        },
    ),
)

# A chamada. No script, o token é de quem está logado; no app, é o do analista, obtido por OBO
search_token = get_bearer_token_provider(credential, "https://search.azure.com/.default")()
response = project.get_openai_client().responses.create(
    input="Posso pagar o sinistro SIN-48213? Alagamento depois do temporal.",
    extra_body={
        "agent_reference": {"name": "agente-sinistros", "type": "agent_reference"},
        "structured_inputs": {"search_auth_token": search_token},
    },
)
print(response.output_text)

Quatro detalhes do script vêm das páginas e costumam custar uma tarde:

• O project_connection_id muda de forma. No MCP, é o nome da conexão; no Fabric e no Work IQ, o ID completo, que o connections.get(...).id resolve.
• A versão do endpoint MCP é a da página do Foundry, a 2026-08-01-preview. A página de recuperação documenta o mesmo endpoint na 2026-04-01, em que a recuperação é sempre mínima e extrativa e devolve só dados de grounding. Nos dois casos, a conexão RemoteTool é preview.
• Cada ferramenta tem a sua linha nas instruções. É a recomendação da página do Fabric — o exemplo dela é “For customer and product sales data, use the Fabric tool” —, e o tool_choice força o uso quando o modelo hesita.
• O token de busca vai em toda chamada, mesmo sem filtrar nada nas condições gerais. No dia em que a base receber um documento com permissão, o filtro já está no lugar; sem o token, a fonte com permissão volta sem filtro.

Passo 5 — O teste com dois analistas

O agente só está pronto quando dois analistas de regionais diferentes fazem as mesmas perguntas e recebem respostas diferentes onde devem. Repita a chamada do fim do passo 4 logado como cada um, com az login, sem recriar conexões nem agente: o DefaultAzureCredential passa a ser o analista, e o token de busca também.

Se Bruno enxergar a apólice da Sul, olhe primeiro o papel dele no workspace: Admin, Member e Contributor passam por cima da RLS. E teste com contas reais, porque o Test as role do Power BI avalia a RLS dinâmica com a sua própria identidade — o USERPRINCIPALNAME() devolve o seu UPN, não o do analista. A página do Work IQ pede o mesmo: “Test permission trimming with representative users and restricted content before deployment”.

Passo 6 — O que fica de fora, e como entraria

O temporal não entra no agente; a instrução já manda o analista conferir por fora. Se o compliance aprovar, ele entra como knowledge source web na mesma knowledge base, com allowedDomains limitado a sites oficiais, como os da Defesa Civil e da meteorologia. Sem lista de domínios, a fonte tem “unrestricted access to the entire public internet”; a página diz que ela “works best alongside other knowledge sources”; e, na 2026-04-01, a knowledge base passa a precisar de uma referência de modelo. A saída do DPA, que vem com o Grounding with Bing, vai para a ata da decisão.

Antes de abrir o agente para a fila, confira:

• a knowledge source terminou a ingestão sem falhas;
• a RLS foi testada com contas reais de duas regionais;
• o data agent está publicado e compartilhado junto com o dado;
• o segredo do app está no Key Vault, e o Global Administrator foi desativado;
• o registro de riscos lista as três ligações em preview e a decisão pendente sobre a web.

Boas práticas para produção

• Decomponha a pergunta antes de escolher o produto. Uma linha por parte: camada, componente, status, identidade e fronteira.
• Registre o status por componente e por versão de API, com a página e a data. “O Foundry IQ é GA” e “o Fabric IQ é preview” são as duas frases erradas mais prováveis da revisão.
• Crie a knowledge base por código, na versão estável. O portal dá acesso só a preview; fixe a api-version e trate a troca de versão como mudança de contrato.
• Encaminhe sempre o token do usuário no x-ms-query-source-authorization e teste com dois usuários de permissões diferentes. Sem o token, a fonte com permissão volta sem filtro.
• Isole o knowledge source do Work IQ. Ele pode agir, não só recuperar; limite o acesso a aplicações e usuários confiáveis.
• Restrinja domínios na fonte web e leve a saída do DPA ao compliance antes do primeiro teste com dado real.
• Revise o cross-geo do tenant antes de ligar o Copilot Chat com dados do Power BI ou de publicar o data agent no Microsoft 365 Copilot.
• Não planeje service principal onde a página não aceita. O Work IQ é delegado, e o MCP da ontologia não aceita service principal.
• Escolha o ecossistema da resposta. Knowledge source do Copilot e do Foundry IQ não se cruzam; decida onde o usuário vai perguntar.
• Reveja o mapa a cada revisão de arquitetura. As páginas usadas aqui foram atualizadas entre junho e outubro de 2026.

O que precisa estar de pé

A ordem abaixo é causal, não cronológica: cada estágio existe porque o anterior ficou de pé.

Fundação — cada pergunta tem camada e dono. As perguntas que o agente precisa responder estão escritas e decompostas; cada parte aponta para uma camada, um componente e um dono do dado; o status de cada componente está registrado com página, data e versão de API.

Está de pé quando qualquer pessoa do time aponta, para cada pergunta do agente, a camada, o componente e o status em que ela se apoia.

Produção com contexto — identidade e fronteira decididas por parte. Cada caminho tem a identidade que chega ao dado testada com usuários de permissões diferentes; o token do usuário vai em toda chamada à knowledge base; cross-geo, fonte web e publicação no Microsoft 365 Copilot passaram pelo compliance.

Está de pé quando, para cada resposta do agente, alguém diz de quem era a identidade que leu o dado e onde ele foi processado.

Escala e eficiência — o mapa vira produto. As knowledge bases são compartilhadas entre agentes, com versão de API fixada; o modelo de decomposição faz parte da entrada de todo agente novo; a revisão de status entra no ciclo de arquitetura.

Está de pé quando um agente novo chega à revisão com o mapa de camadas pronto, e ninguém pergunta qual IQ comprar.

Pular estágio não acelera nada: sem a pergunta decomposta, a escolha volta a ser pelo nome do produto; sem identidade e fronteira decididas, escalar é multiplicar agentes que ninguém sabe auditar.

Perguntas frequentes (FAQ)

Preciso das quatro camadas?

Não. “Each IQ workload is standalone”, diz a página do Foundry IQ. Comece pela pergunta que o agente precisa responder; se ela cabe numa camada, use só essa. A composição é decisão, não pré-requisito.

São três ou quatro IQs?

O hub conta quatro; as páginas do Foundry IQ, “three IQ workloads”. A diferença coincide com o acesso limitado do Web IQ. Desenhe com o que você consegue contratar.

O Foundry IQ substitui o Azure AI Search?

Não; ele roda sobre o Azure AI Search. “You must create a knowledge base in Azure AI Search to use Foundry IQ.” Disponibilidade e cobrança seguem o AI Search e, se houver modelo, o Azure OpenAI.

Dá para usar dados do Fabric no Copilot Chat?

Dá: as respostas com dados do Power BI são GA, respeitam RLS e OLS e exigem licença Premium do Microsoft 365 Copilot para todos os usuários — e, fora dos EUA e da UE, processamento cross-geo. Data agent e ontologia só entram por um agente do Microsoft 365 publicado, e a publicação do data agent está em preview.

Web IQ ou Grounding with Bing?

A fonte web do Foundry IQ usa o Grounding with Bing, e para ele a documentação diz que o DPA não se aplica e que o dado sai da fronteira do Azure. O Web IQ é outro serviço, em acesso limitado, e a página do produto não publica termos de dados. Nos dois casos, a decisão começa no compliance.

Dá para rodar tudo com service principal?

Não. A Work IQ API não aceita autenticação só de aplicação, e o MCP da ontologia não aceita service principal, por um problema conhecido. No Foundry IQ, a identidade gerenciada do projeto conecta o agente à knowledge base, mas o filtro por usuário depende do token do usuário. Agente sem usuário perde o Work IQ e, no Foundry IQ, perde o filtro.

Conclusão

Microsoft IQ é um nome bom para o slide e ruim para a arquitetura. Embaixo dele há quatro camadas, cada uma com a sua pergunta, o seu lugar do dado, o seu status por componente, a sua identidade e a sua fronteira. O erro mais caro não é escolher a camada errada; é escolher uma só para uma pergunta que era quatro.

O mapa resolve: decomponha a pergunta, dê a cada parte a sua camada e registre o que as páginas garantem no dia em que você leu. Escolha a camada pela pergunta, não pelo nome do produto — e só então desenhe a composição.

Referências oficiais

• Microsoft IQ — visão geral
• Work IQ — visão geral
• Work IQ API — visão geral
• Work IQ API — anúncio de disponibilidade geral
• Habilitar o Work IQ no tenant
• Fabric IQ — visão geral
• Ontologia — visão geral
• Data agent do Fabric — conceitos
• Criar um data agent do Fabric
• Compartilhar o data agent e os dados
• Dados do Power BI no Microsoft 365 Copilot Chat
• Fabric IQ no Microsoft 365 Copilot Cowork
• Data agent no Microsoft 365 Copilot
• Servidor MCP da ontologia
• Ontologia como knowledge source do Foundry IQ
• Índice do Azure AI Search no data agent
• Segurança em nível de linha no Power BI
• O que é o Foundry IQ
• FAQ do Foundry IQ
• Conectar o Foundry IQ a um agente
• Ferramenta do Work IQ no Foundry
• Ferramenta do data agent do Fabric no Foundry
• Migração do agentic retrieval para a 2026-04-01
• Knowledge source do Blob
• Criar uma knowledge base
• Consultar uma knowledge base
• Knowledge source do Work IQ
• Knowledge source da web
• Ferramentas do Grounding with Bing no Foundry
• Web IQ

👉 Se você está desenhando um agente que mistura Microsoft 365, dados do Fabric, documentos e web — especialmente em banco ou seguradora, onde a fronteira do dado é requisito regulatório —, comece pelo mapa: decomponha a pergunta, dê uma camada a cada parte e registre status, identidade e fronteira antes de escolher a composição.
Quer trocar ideia sobre Microsoft IQ e arquitetura de agentes? Me chama no LinkedIn.