SDK Python dell'agente dei dati di Fabric (anteprima)

L'SDK Python dell'agente dati di Fabric consente l'accesso programmatico agli artefatti dell'agente dati di Fabric. È progettato per gli utenti code-first che vogliono creare, configurare, aggiornare e pubblicare agenti dati senza usare il portale di Fabric. È possibile eseguire l'SDK all'interno di un notebook Microsoft Fabric o dal proprio ambiente dopo l'autenticazione a Fabric.

Piano di controllo e ambiente di esecuzione

L'SDK è uno strumento del piano di gestione. Usarlo per gestire il ciclo di vita di un agente dati: creare l'artefatto, aggiungere e configurare origini dati, impostare istruzioni e query di esempio e pubblicare. Viene eseguito nell'API REST pubblica Fabric, che è la stessa superficie già usata per altre aree di lavoro ed elementi, quindi l'autenticazione e i modelli di richiesta sono gli stessi.

Il piano di controllo è separato dal modo in cui si interroga l'agente dati in fase di esecuzione. Dopo aver pubblicato un agente di dati, interrogarlo tramite il relativo endpoint Model Context Protocol (MCP) da strumenti, applicazioni e altre esperienze basate su agenti. Per ulteriori informazioni, vedi Agente di dati come server del Model Context Protocol.

Prerequisiti

• Un'area di lavoro Fabric con una capacità che supporta gli agenti dati.
• Un'origine dati supportata nell'area di lavoro, ad esempio un lakehouse, un data warehouse, un modello semantico di Power BI o un database KQL.
• Python 3.10 o versione successiva.
• Per l'esecuzione all'esterno di un notebook Fabric, un modo per eseguire l'autenticazione a Fabric, ad esempio l'interfaccia della riga di comando di Azure o un'entità servizio.

Installazione

L'SDK viene pubblicato in PyPI come fabric-data-agent-sdk. Installarlo usando pip:

%pip install fabric-data-agent-sdk

Eseguire l'autenticazione per Fabric

Quando si esegue l'SDK all'interno di un notebook Fabric, il notebook gestisce automaticamente l'autenticazione.

Quando si esegue l'SDK all'esterno di Fabric, accedere prima a Fabric. Nell'esempio seguente viene eseguito l'accesso con la credenziale interfaccia della riga di comando di Azure e viene impostata come predefinita per la sessione. È possibile usare un account utente o un'entità servizio.

from azure.identity import AzureCliCredential
from fabric.analytics.environment.credentials import (
    SetFabricAnalyticsDefaultTokenCredentialsGlobally,
)

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Creare un agente di dati

Creare un agente dati in un'area di lavoro. Sostituire l'ID dell'area di lavoro con l'ID dell'area di lavoro in cui è presente l'agente dati.

from fabric.dataagent.client import create_data_agent

workspace_id = "<your-workspace-id>"

agent = create_data_agent(
    data_agent_name="Quickstart data agent",
    workspace_id=workspace_id,
)

Configurare l'agente dati e aggiungere origini dati

Impostare le istruzioni dell'agente, quindi aggiungere un'origine dati. Usare l'ID dell'artefatto di un lakehouse, warehouse, modello semantico o database KQL esistente.

agent_instructions = "<your agent instructions>"
datasource_id = "<your-datasource-id>"

agent.update_settings(ai_instructions=agent_instructions)

agent.add_staging_datasource(
    artifact_name_or_id=datasource_id,
    workspace_id_or_name=workspace_id,
)

È anche possibile aggiungere istruzioni sull'origine dati e query di esempio per migliorare la qualità delle risposte dell'agente dati. Per altre informazioni, vedere gli esempi dell'SDK dell'agente dati Fabric su GitHub.

Pubblicare l'agente dei dati

Pubblica la configurazione di staging per rendere disponibile l'agente dati per le query.

agent.publish_staging(description="Initial publish")

Eseguire query su un agente dati pubblicato

Dopo aver pubblicato l'agente di dati, interrogarlo tramite il relativo endpoint MCP. L'endpoint MCP è l'interfaccia di runtime e di utilizzo per l'agente di dati. È possibile connettersi ad esso da strumenti, applicazioni e altri agenti per eseguire query sull'agente dati, porre domande e ricevere risposte. Per la procedura di configurazione e i client supportati, consulta Agente dati come server Model Context Protocol.

Ottenere l'URL dell'endpoint

È possibile ottenere l'URL dell'endpoint MCP in due modi:

• Copialo dalle impostazioni dell'agente dati. Dopo aver pubblicato l'agente dati, aprire la scheda Model Context Protocol nelle impostazioni dell'agente e copiare l'URL del server MCP. Per informazioni dettagliate, vedere Agente dati come server del protocollo di contesto del modello.

• Creala manualmente. Costruisci l'URL a partire dall'ID dell'area di lavoro e dall'ID dell'agente dati (artefatto) utilizzando il seguente formato:

  https://api.fabric.microsoft.com/v1/mcp/workspaces/{WorkspaceId}/dataagents/{DataAgentId}/agent
  

  Sostituisci i segnaposto con i valori del tuo agente dati pubblicato:

  Segnaposto	Description
  {WorkspaceId}	L'ID dell'area di lavoro Fabric che contiene l'agente dati.
  {DataAgentId}	L'ID dell'agente dati pubblicato.

  Un URL compilato manualmente funziona solo dopo la pubblicazione dell'agente dati. Se l'agente dati non è pubblicato, l'endpoint restituisce un errore anche quando l'URL è corretto.

Authentication

Le richieste all'endpoint MCP devono essere autenticate con Fabric. Assicurarsi che il client includa un bearer token valido con le autorizzazioni necessarie per accedere all'area di lavoro di destinazione e all'agente dati. Il token può rappresentare un'identità utente o un'entità servizio (SPN).

Strumenti disponibili

L'agente dati Fabric espone un server MCP che fornisce un singolo strumento. I client chiamano questo strumento per inviare una domanda all'agente dati e ricevere la risposta generata.

Eseguire query sull'agente dati da Python

L'esempio seguente si connette all'endpoint MCP, individua lo strumento, invia una domanda e stampa la risposta. Riutilizza il credential del passaggio Autenticazione a Fabric e usa l'MCP Python SDK. Installare prima l'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)

Contenuto correlato

• Creare un agente dei dati di Fabric
• Agente dati come server del protocollo di contesto del modello
• Esempi di SDK dell'agente dati Fabric
• Riferimento API REST di Fabric