Python-SDK für Fabric-Datenagent (Vorschau)

Das Fabric Data Agent Python SDK bietet programmgesteuerten Zugriff auf Artefakte des Fabric-Daten-Agenten. Es wurde für Code-first-Benutzer entwickelt, die Daten-Agents erstellen, konfigurieren, aktualisieren und veröffentlichen möchten, ohne das Fabric-Portal zu verwenden. Sie können das SDK in einem Microsoft Fabric-Notizbuch oder aus Ihrer eigenen Umgebung ausführen, nachdem Sie sich bei Fabric authentifiziert haben.

Verwaltungsebene und Laufzeit

Das SDK ist ein Verwaltungsebenentool. Verwenden Sie ihn zum Verwalten des Lebenszyklus eines Daten-Agents: Erstellen Sie das Artefakt, fügen Sie Datenquellen hinzu, konfigurieren Sie Datenquellen, legen Sie Anweisungen und Beispielabfragen fest und veröffentlichen Sie sie. Sie wird auf der Fabric öffentlichen REST-API ausgeführt, die die gleiche Oberfläche ist, die Sie bereits für andere Arbeitsbereiche und Elemente verwenden, sodass die Authentifizierung und die Anforderungsmuster identisch sind.

Die Management-Ebene ist davon getrennt, wie Sie den Daten-Agenten zur Laufzeit abfragen. Nachdem Sie einen Daten-Agent veröffentlicht haben, greifen Sie aus Tools, Anwendungen und anderen agentischen Umgebungen über seinen Model Context Protocol (MCP)-Endpunkt darauf zu. Weitere Informationen finden Sie unter Daten-Agent als Modellkontextprotokollserver.

Voraussetzungen

• Ein Fabric-Arbeitsbereich mit einer Kapazität, die Daten-Agenten unterstützt.
• Eine unterstützte Datenquelle im Arbeitsbereich, z. B. ein Seehaus, ein Lager, Power BI semantisches Modell oder eine KQL-Datenbank.
• Python 3.10 oder höher.
• Für die Ausführung außerhalb eines Fabric-Notebooks benötigen Sie eine Möglichkeit, sich bei Fabric zu authentifizieren, z. B. über die Azure CLI oder einen Serviceprinzipal.

Einrichtung

Das SDK wird auf PyPI als fabric-data-agent-sdk veröffentlicht. Installieren Sie es mithilfe von pip:

%pip install fabric-data-agent-sdk

Authentifizieren bei Fabric

Wenn Sie das SDK in einem Fabric Notizbuch ausführen, verarbeitet das Notizbuch die Authentifizierung für Sie.

Wenn Sie das SDK außerhalb Fabric ausführen, melden Sie sich zuerst bei Fabric an. Das folgende Beispiel meldet sich mit den Azure CLI Anmeldeinformationen an und legt sie als Standard für die Sitzung fest. Sie können entweder ein Benutzerkonto oder einen Service Principal verwenden.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Erstellen eines Daten-Agents

Erstellen Sie einen Datenagenten in einem Arbeitsbereich. Ersetzen Sie die Arbeitsbereichs-ID durch die ID des Arbeitsbereichs, in dem der Daten-Agent vorhanden ist.

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,
)

Konfigurieren des Daten-Agents und Hinzufügen von Datenquellen

Legen Sie die Agentanweisungen fest, und fügen Sie dann eine Datenquelle hinzu. Verwenden Sie die Artefakt-ID einer vorhandenen Seehaus-, Lager-, Semantik- oder KQL-Datenbank.

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,
)

Sie können auch Datenquellenanweisungen und Beispielabfragen hinzufügen, um die Qualität der Antworten des Datenagenten zu verbessern. Weitere Informationen finden Sie in den Fabric Data Agent SDK-Beispielen für GitHub.

Veröffentlichen des Daten-Agents

Veröffentlichen Sie die mehrstufige Konfiguration, um den Daten-Agent für die Abfrage verfügbar zu machen.

agent.publish_staging(description="Initial publish")

Einen veröffentlichten Daten-Agent abfragen

Nachdem Sie den Daten-Agent veröffentlicht haben, fragen Sie ihn über seinen MCP-Endpunkt ab. Der MCP-Endpunkt ist die Laufzeit- und Verbrauchsoberfläche für den Daten-Agent. Sie können über Tools, Anwendungen und andere Agents eine Verbindung herstellen, um den Daten-Agent abzufragen, Fragen zu stellen und Antworten zu erhalten. Informationen zu Setupschritten und unterstützten Clients finden Sie unter Data Agent als Modellkontextprotokollserver.

Abrufen der Endpunkt-URL

Sie können die MCP-Endpunkt-URL auf zwei Arten abrufen:

• Kopieren Sie es aus den Einstellungen des Datenagenten. Nachdem Sie den Daten-Agent veröffentlicht haben, öffnen Sie die Registerkarte " Modellkontextprotokoll " in den Agenteinstellungen, und kopieren Sie die MCP-Server-URL. Ausführliche Informationen finden Sie unter Daten-Agent als Modellkontextprotokollserver.

• Erstellen Sie es manuell. Erstellen Sie die URL anhand Ihrer Arbeitsbereichs-ID und der ID des Datenagenten (Artefakt-ID) im folgenden Format:

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

  Ersetzen Sie die Platzhalter durch Werte aus Ihrem veröffentlichten Daten-Agent:

  Platzhalter	Description
  {WorkspaceId}	Die ID des Fabric-Arbeitsbereichs, der den Daten-Agenten enthält.
  {DataAgentId}	Die ID des veröffentlichten Daten-Agents.

  Eine manuell erstellte URL funktioniert erst, nachdem Sie den Datenagent veröffentlicht haben. Wenn der Daten-Agent nicht veröffentlicht wird, gibt der Endpunkt auch dann einen Fehler zurück, wenn die URL korrekt ist.

Authentication

Anforderungen an den MCP-Endpunkt müssen für Fabric authentifiziert werden. Stellen Sie sicher, dass Ihr Client ein gültiges Bearertoken mit Berechtigungen für den Zugriff auf den Zielarbeitsbereich und den Daten-Agent enthält. Das Token kann entweder eine Benutzeridentität oder einen Dienstprinzipal (SPN) darstellen.

Verfügbare Tools

Der Fabric-Daten-Agent macht einen MCP-Server verfügbar, der ein einzelnes Tool bereitstellt. Clients rufen dieses Tool auf, um eine Frage an den Daten-Agent zu senden und die generierte Antwort zu erhalten.

Den Daten-Agent aus Python abfragen

Im folgenden Beispiel wird eine Verbindung mit dem MCP-Endpunkt hergestellt, das Tool ermittelt, eine Frage gesendet und die Antwort gedruckt. Dabei wird das credential aus dem Schritt Authenticate to Fabric wiederverwendet und das MCP Python SDK verwendet. Installieren Sie zuerst das 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)

Verwandte Inhalte

• Erstellen Sie einen Fabric-Datenagenten
• Daten-Agent als Modellkontextprotokollserver
• Beispiele für Fabric Data Agent SDK
• Fabric-REST-API-Referenz