Fabric-dataagent Python SDK (prøveversion)

Fabric data agent Python SDK giver programmatisk adgang til Fabric data agent-artefakter. Det er designet til brugere med kode-først, som ønsker at oprette, konfigurere, opdatere og offentliggøre dataagenter uden at bruge Fabric-portalen. Du kan køre SDK'en inde i en Microsoft Fabric-notebook eller fra dit eget miljø, efter du har autentificeret dig til Fabric.

Vigtigt!

Denne funktion er i prøveversion.

Ledelsesplan og køretid

SDK'et er et management-plane-værktøj. Brug det til at styre livscyklussen for en dataagent: skab artefaktet, tilføj og konfigurér datakilder, sæt instruktioner og eksempelforespørgsler, og publicér. Det kører på Fabric public REST API, som er den samme overflade, du allerede bruger til andre arbejdsområder og items, så autentificering og anmodningsmønstre er de samme.

Managementplanet er adskilt fra, hvordan du forespørger dataagenten under kørsel. Efter du har offentliggjort en dataagent, skal du forespørge den gennem dens Model Context Protocol (MCP)-endpoint fra værktøjer, applikationer og andre agentiske oplevelser. For mere information, se Data agent som en Model Context Protocol-server.

Prerequisites

  • Et Fabric-arbejdsområde med en kapacitet, der understøtter dataagenter.
  • En understøttet datakilde i arbejdsområdet, såsom et lakehouse, lager, Power BI semantisk model eller KQL-database.
  • Python 3.10 eller nyere.
  • Til udførelse uden for en Fabric-notebook findes der en måde at autentificere til Fabric, såsom Azure CLI eller en service principal.

Installation

SDK'et er offentliggjort på PyPI som fabric-data-agent-sdk. Installer det ved at bruge pip:

%pip install fabric-data-agent-sdk

Autentificér til Fabric

Når du kører SDK'en inde i en Fabric-notebook, håndterer notebooken autentificeringen for dig.

Når du kører SDK'en uden for Fabric, skal du først logge ind på Fabric. Det følgende eksempel logger ind med Azure CLI-legitimationen og sætter den som standard for sessionen. Du kan bruge enten en brugerkonto eller en servicehovedperson.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Bemærkning

Den konto eller tjenesteprincipal, du autentificerer med, skal have tilladelse til at oprette og administrere elementer i det målrettede arbejdsområde.

Opret en dataagent

Opret en dataagent i et arbejdsområde. Erstat arbejdsområdets ID med ID'et for det arbejdsområde, hvor dataagenten findes.

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

Konfigurer dataagenten og tilføj datakilder

Indstil agentinstruktionerne, og tilføj derefter en datakilde. Brug artefakt-ID'et fra en eksisterende lakehouse, lager, semantisk model eller KQL-database.

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

Du kan også tilføje instruktioner til datakilden og eksempelforespørgsler for at forbedre kvaliteten af dataagentens svar. For at lære mere, se Fabric data agent SDK-eksemplerne på GitHub.

Offentliggør dataagenten

Offentliggør den trinsatte konfiguration, så dataagenten er tilgængelig for forespørgsler.

agent.publish_staging(description="Initial publish")

Bemærkning

Udgivelse gennem SDK'en fungerer både inden for og uden for Fabric. At publicere en dataagent til Microsoft 365 Copilot bruger endnu ikke det offentlige API, så du gør det stadig fra Fabric, enten i portalen eller ved at køre SDK'en i en Fabric-notebook.

Forespørg en offentliggjort dataagent

Efter du har offentliggjort dataagenten, skal du forespørge den via dens MCP-endpoint. MCP-endpointet er køretids- og forbrugsoverfladen for dataagenten. Du kan forbinde til det fra værktøjer, applikationer og andre agenter for at forespørge dataagenten, stille spørgsmål og modtage svar. For opsætningstrin og understøttede klienter, se Data agent som en Model Context Protocol-server.

Vigtigt!

Dataagenten fungerer kun som en MCP-server efter du har udgivet den. Hvis du ikke publicerer dataagenten, virker MCP-endpointet ikke.

Få endpoint-URL'en

Du kan få MCP-endpointets URL på to måder:

  • Kopier det fra dataagent-indstillingerne. Efter du har offentliggjort dataagenten, åbner du fanen Model Context Protocol i agentindstillingerne og kopierer MCP-serverens URL. For detaljer, se Data agent som en Model Context Protocol-server.

  • Byg det manuelt. Konstruer URL'en ud fra dit arbejdsområde-ID og dataagent-ID (artefakt) ved at bruge følgende format:

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

    Erstat pladsholderne med værdier fra din publicerede dataagent:

    Pladsholder Beskrivelse
    {WorkspaceId} ID'et for Fabric-arbejdsområdet, der indeholder dataagenten.
    {DataAgentId} ID'et på den publicerede dataagent.

    En manuelt opbygget URL virker kun, efter du har offentliggjort dataagenten. Hvis dataagenten ikke er offentliggjort, returnerer endpointet en fejl, selv når URL'en er korrekt.

Godkendelse

Forespørgsler til MCP-endpointet skal autentificeres mod Fabric. Sørg for, at din klient inkluderer et gyldigt bærertoken med tilladelser til at få adgang til målarbejdsområdet og dataagenten. Tokenet kan repræsentere enten en brugeridentitet eller en serviceprincipal (SPN).

Tilgængelige værktøjer

Fabric-dataagenten eksponerer en MCP-server, der leverer et enkelt værktøj. Kunder kalder dette værktøj for at sende et spørgsmål til dataagenten og modtage det genererede svar.

Forespørg dataagenten fra Python

Følgende eksempel forbinder til MCP-endpointet, opdager værktøjet, sender et spørgsmål og printer svaret. Den genbruger steget credential fra Authenticate to Fabric og bruger MCP Python SDK. Installer SDK'en først:

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

Relateret indhold

  • Last updated on