Exemplo de agente de dados do Fabric com o conjunto de dados AdventureWorks (versão prévia)

Este artigo mostra como configurar um agente de dados em Microsoft Fabric usando um lakehouse como a fonte de dados de exemplo. Primeiro criamos e populamos uma lakehouse, depois criamos um agente de dados Fabric e adicionamos o lakehouse a ele. Se você já tiver um modelo semântico Power BI, verifique se tem permissão de leitura para interagir com ele por meio de um agente de dados (a permissão de gravação só é necessária para modificar o modelo semântico ou usar recursos como o Prep for AI). Para um armazém, um banco de dados KQL ou uma ontologia, siga as mesmas etapas e selecione essa fonte. Embora este passo a passo use uma lakehouse, o padrão é o mesmo para outras fontes; apenas a seleção da fonte de dados é diferente.

Pré-requisitos

• Uma capacidade paga de Fabric F2 ou superior ou uma capacidade Power BI Premium por capacidade (P1 ou superior) com Microsoft Fabric habilitado.
• Habilite o processamento e armazenamento entre regiões geográficas para IA de acordo com os requisitos especificados nas configurações de locatário do agente de dados do Fabric.
• Pelo menos uma dessas fontes de dados, com dados: um warehouse, um lakehouse, um modelo semântico do Power BI, um banco de dados KQL, um banco de dados espelhado ou uma ontologia. Você deve ter acesso de leitura à fonte de dados.

Crie um lakehouse com o AdventureWorksLH

Primeiro, crie um lakehouse e preencha-o com os dados necessários.

Se você já tiver uma instância do AdventureWorksLH em um depósito ou lakehouse, pode ignorar esta etapa. Caso contrário, você pode usar as instruções a seguir de um notebook Fabric para preencher o lakehouse com os dados.

1. Crie um novo bloco de anotações no workspace em que você deseja criar seu agente de dados Fabric.

2. No lado esquerdo do painel Explorer, selecione + Fontes de dados. Essa opção permite que você adicione um lakehouse já existente ou crie um novo lakehouse. Para fins de clareza, crie um novo lakehouse e atribua um nome a ele.

3. Na célula superior, adicione o seguinte snippet 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.

Criar um agente de dados Fabric

Para criar um novo agente de dados Fabric, navegue até o workspace e selecione o botão + Novo Item, conforme mostrado nesta captura de tela:

Na guia Todos os itens, pesquise agente de dados do Fabric para localizar a opção apropriada. Depois de selecionado, um prompt solicita que você forneça um nome para o agente de dados Fabric, conforme mostrado nesta captura de tela:

Depois de inserir o nome, prossiga com as etapas a seguir para alinhar o agente de dados Fabric com seus requisitos específicos.

Selecione os dados

Selecione o lakehouse que você criou na etapa anterior e, em seguida, selecione Adicionar, conforme mostrado na seguinte captura de tela:

Depois que o lakehouse é adicionado como uma fonte de dados, o painel Explorer no lado esquerdo da página do agente de dados Fabric mostra o nome do lakehouse. Selecione o lakehouse para exibir todas as tabelas disponíveis. Use as caixas de seleção para selecionar as tabelas que você deseja disponibilizar para a IA. Para este 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 usuários só precisam de permissão de leitura em um modelo semântico Power BI para adicioná-lo a um agente de dados e fazer perguntas por meio do agente. O acesso ao workspace (função membro) e a permissão Build não são necessários para interação por meio de agentes de dados. A permissão de gravação é necessária apenas para modificar o modelo semântico ou usar recursos como Preparação para IA.

Essa alteração de permissões se aplica somente a interações por meio de agentes de dados. Outros padrões de acesso (por exemplo, Analisar em Excel ou criação direta de relatório) seguem permissões de Power BI padrão.

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 instruções a seguir.

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

• dimcustomer, para informações detalhadas de dados demográficos e de contato do cliente
• dimdate, para dados relacionados à data – por exemplo, informações de calendário e fiscais
• dimgeography, para obter detalhes geográficos, incluindo nomes de cidade e códigos de região do país.

Use essa fonte de dados para consultas e análises que envolvem detalhes do cliente, eventos baseados em 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 com suporte. Para cada fonte de dados, você pode selecionar Adicionar ou Editar Consultas de Exemplo para inserir os exemplos relevantes, conforme mostrado na seguinte captura de tela:

Aqui, você deve adicionar consultas de exemplo para a fonte de dados do 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

Testar e revisar o agente de dados Fabric

Agora que você configurou o agente de dados do Fabric, adicionou instruções do agente de dados do Fabric e forneceu consultas de exemplo para o lakehouse, você pode interagir com ele, fazendo perguntas e recebendo respostas. À medida que você continua testando, você 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 comentários e, com base em suas entradas, verifique se as consultas e instruções de exemplo fornecidas se alinham 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, você poderá decidir publicá-lo para que possa compartilhá-lo com seus colegas que desejam fazer Q& Um sobre dados. Nesse caso, selecione Publicar conforme mostrado nesta captura de tela:

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

Nesta caixa, selecione Publish para publicar o agente de dados Fabric. Uma vez publicado, o agente de dados pode ser consumido como um servidor de protocolo de contexto modelo (MCP).

Usar o agente de dados Fabric programaticamente

Você pode usar o agente de dados Fabric programaticamente em um bloco de anotações Fabric. Para determinar se o agente de dados Fabric tem ou não um valor de URL publicado, selecione Settings, conforme mostrado na captura de tela a seguir:

Antes de publicar o agente de dados Fabric, ele não tem um valor de URL publicado, conforme mostrado na captura de tela a seguir:

Se você não tiver publicado o agente de dados do Fabric antes, poderá publicá-lo seguindo as instruções nas etapas anteriores. Em seguida, você pode copiar a URL publicada e usá-la no bloco de anotações Fabric. Dessa forma, você pode consultar o agente de dados Fabric fazendo chamadas para a API do agente de dados Fabric em um bloco de anotações Fabric. Cole a URL copiada neste snippet de código. Em seguida, substitua a pergunta por qualquer consulta relevante para o agente de dados Fabric. Este exemplo usa \<generic published URL value\> como a URL.

%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

Consultar o agente de dados de Python

O exemplo a seguir conecta-se ao ponto de extremidade MCP, descobre a ferramenta, envia uma pergunta e imprime a resposta. Reutiliza o credential da etapa Autenticação no Fabric e usa o SDK do MCP para Python. Instale o SDK primeiro:

%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 Fabric
• Criar um agente de dados Fabric