Exemplo do agente de dados Fabric com o conjunto de dados AdventureWorks (pré-visualização)

Este artigo mostra como configurar um agente de dados no Microsoft Fabric usando uma casa de lago como fonte de dados de exemplo. Primeiro criamos e povoamos uma casa do lago, depois criamos um agente de dados Fabric e adicionamos a casa do lago. Se já tiver um modelo semântico do Power BI, certifique-se de que tem permissão de leitura para interagir com ele através de um agente de dados (a permissão de escrita só é necessária para modificar o modelo semântico ou usar capacidades como Prep for AI). Para um armazém, uma base de dados KQL ou uma ontologia, siga os mesmos passos e selecione essa fonte em vez disso. Embora este tutorial utilize um lakehouse, o padrão é o mesmo para outras fontes de dados; apenas a seleção da fonte de dados difere.

Importante

Este recurso está em pré-visualização.

Pré-requisitos

• Uma capacidade paga F2 ou superior do Fabric, ou uma capacidade do Power BI Premium (P1 ou superior) com Microsoft Fabric ativado.
• Permita o processamento e armazenamento entre geografias para IA com base nos requisitos explicados nas configurações do inquilino do agente de dados do Fabric.
• Pelo menos uma destas fontes de dados, com dados: um armazém, uma casa de lago, um modelo semântico Power BI, uma base de dados KQL, uma base de dados espelhada ou uma ontologia. Deve ter acesso de leitura à fonte de dados.

Importante

Garanta que a experiência autónoma do Copilot está ativada no portal de administração do Power BI (Definições do Inquilino > Copilot > Experiência autónoma do Copilot). Se não estiver ativado, não poderá usar o agente de dados dentro dos cenários do Copilot, mesmo que outros switches de inquilino do Copilot estejam ativos. Para mais detalhes, veja Copilot nas definições do locatário do Power BI.

Crie uma casa no lago com o AdventureWorksLH

Primeiro, crie uma casa de lago e preencha-a com os dados necessários.

Se você já tiver uma instância do AdventureWorksLH em uma casa no lago (ou em um armazém), ignore esta etapa. Caso contrário, pode usar as seguintes instruções de um notebook Fabric para preencher o lakehouse com os dados.

1. Crie um novo caderno no espaço de trabalho onde quer criar o seu agente de dados Fabric.

2. No lado esquerdo do painel Explorer , selecione + Fontes de dados. Esta opção permite ao utilizador adicionar uma lakehouse existente ou criar uma nova lakehouse. Por uma questão de clareza, crie uma nova casa do lago e atribua-lhe um nome.

3. Na célula superior, adicione o seguinte trecho de código:

   import pandas as pd
   from tqdm.auto import tqdm
   base = "https://synapseaisolutionsa.z13.web.core.windows.net/data/AdventureWorks"
   
   # load list of tables
   df_tables = pd.read_csv(f"{base}/adventureworks.csv", names=["table"])
   
   for table in (pbar := tqdm(df_tables['table'].values)):
       pbar.set_description(f"Uploading {table} to lakehouse")
   
       # download
       df = pd.read_parquet(f"{base}/{table}.parquet")
   
       # save as lakehouse table
       spark.createDataFrame(df).write.mode('overwrite').saveAsTable(table)
   

4. Selecione Executar tudo.

Após alguns minutos, o lakehouse é preenchido com os dados necessários.

Atenção

Notebooks que continuam a funcionar (por exemplo, devido a loops infinitos acidentais ou sondagens constantes) podem consumir a capacidade do Fabric indefinidamente. Após o término do carregamento dos dados, pare todas as células ativas e encerre a sessão do notebook (barra de ferramentas > do notebook Encerrar sessão) caso já não precise. Evite adicionar loops de longa duração sem um tempo limite.

Criar um agente de dados Fabric

Para criar um novo agente de dados Fabric, navegue até ao seu espaço de trabalho e selecione o botão + Novo Item, como mostrado nesta captura de ecrã:

No separador Todos os itens, pesquise por Fabric data agent para localizar a opção apropriada. Uma vez selecionado, um prompt pede-lhe que forneça um nome para o seu agente de dados Fabric, como mostrado nesta captura de ecrã:

Depois de inserir o nome, siga os seguintes passos para alinhar o agente de dados Fabric com os seus requisitos específicos.

Selecione os dados

Selecione a casa do lago que você criou na etapa anterior e, em seguida, selecione Adicionar, conforme mostrado na captura de tela a seguir:

Uma vez que a casa do lago é adicionada como fonte de dados, o painel Explorer no lado esquerdo da página do agente de dados Fabric mostra o nome da casa do lago. Selecione a casa do lago para ver todas as mesas disponíveis. Use as caixas de seleção para selecionar as tabelas que deseja disponibilizar para a IA. Para esse cenário, selecione estas tabelas:

• dimcustomer
• dimdate
• dimgeography
• dimproduct
• dimproductcategory
• dimpromotion
• dimreseller
• dimsalesterritory
• factinternetsales
• factresellersales

Permissões para modelos semânticos em agentes de dados

Os utilizadores só precisam de permissão de leitura num modelo semântico Power BI para o adicionar a um agente de dados e colocar questões através do agente. O acesso ao espaço de trabalho (função de membro) e a permissão de compilação não são necessários para interagir através de agentes de dados. A permissão de escrita é necessária apenas para modificar o modelo semântico ou utilizar capacidades como Prep for AI.

Esta alteração de permissões aplica-se apenas a interações através de agentes de dados. Outros padrões de acesso (por exemplo, Analisar em Excel ou autoria de relatórios diretos) seguem permissões padrão do Power BI.

Fornecer instruções

Para adicionar instruções, selecione o botão Instruções do agente de dados para abrir o painel de instruções à direita. Você pode adicionar as seguintes instruções.

A fonte de dados AdventureWorksLH contém informações de três tabelas:

• dimcustomer, para dados demográficos detalhados dos clientes e informações de contato
• dimdate, para dados relacionados com a data - por exemplo, calendário e informações fiscais
• dimgeography, para obter detalhes geográficos, incluindo nomes de cidades e códigos de região do país.

Use essa fonte de dados para consultas e análises que envolvam detalhes do cliente, eventos baseados no tempo e localizações geográficas.

Forneça exemplos

Para adicionar consultas de exemplo, selecione o botão Consultas de exemplo para abrir o painel de consultas de exemplo à direita. Este painel fornece opções para adicionar ou editar consultas de exemplo para todas as fontes de dados suportadas. Para cada fonte de dados, você pode selecionar Adicionar ou Editar Consultas de Exemplo para inserir os exemplos relevantes, conforme mostrado na captura de tela a seguir:

Aqui, você deve adicionar consultas de exemplo para a fonte de dados lakehouse que você criou.

Question: Calculate the average percentage increase in sales amount for repeat purchases for every zipcode. Repeat purchase is a purchase subsequent to the first purchase (the average should always be computed relative to the first purchase)

SELECT AVG((s.SalesAmount - first_purchase.SalesAmount) / first_purchase.SalesAmount * 100) AS AvgPercentageIncrease
FROM factinternetsales s
INNER JOIN dimcustomer c ON s.CustomerKey = c.CustomerKey
INNER JOIN dimgeography g ON c.GeographyKey = g.GeographyKey
INNER JOIN (
    SELECT *
    FROM (
        SELECT
            CustomerKey,
            SalesAmount,
            OrderDate,
            ROW_NUMBER() OVER (PARTITION BY CustomerKey ORDER BY OrderDate) AS RowNumber
        FROM factinternetsales
    ) AS t
    WHERE RowNumber = 1
) first_purchase ON s.CustomerKey = first_purchase.CustomerKey
WHERE s.OrderDate > first_purchase.OrderDate
GROUP BY g.PostalCode;

Question: Show the monthly total and year-to-date total sales. Order by year and month.

SELECT
    Year,
    Month,
    MonthlySales,
    SUM(MonthlySales) OVER (PARTITION BY Year ORDER BY Year, Month ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS CumulativeTotal
FROM (
    SELECT
       YEAR(OrderDate) AS Year,
       MONTH(OrderDate) AS Month,
       SUM(SalesAmount) AS MonthlySales
    FROM factinternetsales
    GROUP BY YEAR(OrderDate), MONTH(OrderDate)
) AS t

Observação

Adicionar pares de exemplos de consulta/pergunta não é atualmente suportado para fontes de dados de modelos semânticos do Power BI.

Testar e rever o agente de dados Fabric

Agora que configurou o agente de dados Fabric, adicionou instruções do agente de dados Fabric e forneceu consultas de exemplo para a casa do lago, pode interagir com ela fazendo perguntas e recebendo respostas. À medida que continua a testar, pode adicionar mais exemplos e refinar as instruções para melhorar ainda mais o desempenho do agente de dados Fabric. Colabore com seus colegas para coletar feedback e, com base em suas entradas, certifique-se de que as consultas e instruções de exemplo fornecidas estejam alinhadas com os tipos de perguntas que eles desejam fazer.

Publicar o agente de dados Fabric

Depois de validar o desempenho do agente de dados Fabric, pode decidir publicá-lo para depois partilhá-lo com os seus colegas que queiram realizar sessões de perguntas e respostas sobre dados. Nesse caso, selecione Publicar, conforme mostrado nesta captura de tela:

A caixa Publicar dados do agente é aberta, conforme mostrado nesta captura de tela.

Nesta caixa, selecione Publicar para publicar o agente de dados Fabric. Uma vez publicado, o agente de dados pode ser utilizado como um servidor do Model Context Protocol (MCP).

Use o agente de dados Fabric programaticamente

Podes usar o agente de dados Fabric programaticamente dentro de um notebook Fabric. Para determinar se o agente de dados Fabric tem ou não um valor de URL publicado, selecione Settings, como mostrado na seguinte captura de ecrã:

Antes de publicar o agente de dados Fabric, não tem um valor de URL publicado, como mostrado na seguinte captura de ecrã:

Se nunca publicou o agente de dados Fabric antes, pode publicá-lo seguindo as instruções dos passos anteriores. Depois podes copiar o URL publicado e usá-lo no caderno Fabric. Desta forma, pode consultar o agente de dados Fabric fazendo chamadas para a API do agente de dados Fabric num caderno Fabric. Cole o URL copiado neste trecho de código. Depois, substitua a pergunta por qualquer consulta relevante para o seu agente de dados Fabric. Este exemplo usa \<generic published URL value\> como URL.

Importante

Ao chamar um agente de dados programaticamente, implemente:

1. Um tempo limite de sondagem (veja o exemplo abaixo) para evitar loops indefinidos.
2. Frequência mínima de sondagem (comece em 2–5 segundos; aumente apenas se necessário).
3. Limpeza de threads ou recursos criados após a conclusão.
4. A sessão do notebook é encerrada quando finalizada para libertar a capacidade do Fabric.

Observação

Ajuste os fixadores de versão (openai, synapseml, pandas, tqdm) para as versões mais recentes validadas do seu runtime Fabric, caso estas versões exatas se tornem desatualizadas.

%pip install "openai==1.70.0"
%pip install "synapseml==1.0.5"  # Required for synapse.ml.mlflow (update version as needed)
%pip install pandas tqdm  # Skip if already available in the Fabric runtime

Importante

Desde que a OpenAI retirou a API dos Assistentes, as aplicações devem usar o endpoint MCP para interações com agentes. Ao contrário da API dos Assistentes, o endpoint MCP não fornece gestão integrada de conversas, pelo que quem faz as chamadas tem de orquestrar interações em várias rondas através da manutenção do estado da conversa e do fornecimento de contexto relevante ao longo dos pedidos.

Consultar o agente de dados a partir do Python

O exemplo seguinte liga-se ao endpoint MCP, descobre a ferramenta, envia uma pergunta e imprime a resposta. Reutiliza o credential do passo Autenticar no Fabric e utiliza o MCP Python SDK. Instala primeiro o SDK:

%pip install mcp

import asyncio

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

workspace_id = "<your-workspace-id>"
data_agent_id = "<your-data-agent-id>"
question = "<your question>"

mcp_url = (
    f"https://api.fabric.microsoft.com/v1/mcp/workspaces/{workspace_id}"
    f"/dataagents/{data_agent_id}/agent"
)


def get_auth_headers():
    token = credential.get_token("https://api.fabric.microsoft.com/.default")
    return {"Authorization": f"Bearer {token.token}"}


async def query_data_agent(question):
    headers = get_auth_headers()

    async with streamablehttp_client(mcp_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # The data agent exposes a single tool. Discover it, then call it.
            tools = await session.list_tools()
            tool = tools.tools[0]
            question_arg = next(iter(tool.inputSchema["properties"]))

            result = await session.call_tool(tool.name, {question_arg: question})

            answers = [block.text for block in result.content if block.type == "text"]
            return "\n".join(answers)


answer = asyncio.run(query_data_agent(question))
print(answer)

Conteúdo relacionado

• Conceito de agente de dados de rede
• Criar um agente de dados Fabric