Fabric-dataagent Python SDK (förhandsversion)

Fabric-dataagenten Python SDK ger programmatisk åtkomst till Fabric dataagentartefakter. Den är utformad för användare som föredrar att arbeta direkt i kod och vill skapa, konfigurera, uppdatera och publicera dataagenter utan att använda Fabric-portalen. Du kan köra SDK:t i en Microsoft Fabric notebook-fil eller från din egen miljö när du har autentiserat till Fabric.

Hanteringsskikt och körtid

SDK är ett hanteringsplanverktyg. Använd den för att hantera livscykeln för en dataagent: skapa artefakten, lägga till och konfigurera datakällor, ange instruktioner och exempelfrågor och publicera. Den körs på Fabric offentliga REST API, som är samma yta som du redan använder för andra arbetsytor och objekt, så autentisering och begärandemönster är desamma.

Hanteringsplanet är skilt från hur du gör frågor mot dataagenten vid körning. När du har publicerat en dataagent kan du ställa frågor till den via dess Model Context Protocol-slutpunkt (MCP) från verktyg, applikationer och andra agentbaserade upplevelser. Mer information finns i Dataagent som modellkontextprotokollserver.

Förutsättningar

• En Fabric arbetsyta med en kapacitet som stöder dataagenter.
• En datakälla som stöds i arbetsytan, till exempel ett lakehouse, ett informationslager, en semantisk modell i Power BI eller en KQL-databas.
• Python 3.10 eller senare.
• Vid körning utanför en Fabric-notebook behövs ett sätt att autentisera mot Fabric, till exempel med Azure CLI eller ett tjänsthuvudnamn.

Installation

SDK publiceras på PyPI som fabric-data-agent-sdk. Installera den med pip:

%pip install fabric-data-agent-sdk

Autentisera dig mot Fabric

När du kör SDK:t i en anteckningsbok i Fabric hanterar anteckningsboken autentiseringen åt dig.

När du kör SDK:et utanför Fabric loggar du in på Fabric först. Följande exempel loggar in med Azure CLI autentiseringsuppgifter och anger den som standard för sessionen. Du kan använda antingen ett användarkonto eller ett huvudnamn för tjänsten.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Skapa en dataagent

Skapa en dataagent på en arbetsyta. Ersätt arbetsytans ID med ID:t för arbetsytan där dataagenten finns.

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

Konfigurera dataagenten och lägg till datakällor

Ange agentinstruktionerna och lägg sedan till en datakälla. Använd artefakt-ID:t för en befintlig lakehouse-, lager-, semantisk modell- eller KQL-databas.

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 också lägga till instruktioner för datakällan och exempelfrågor för att förbättra kvaliteten på dataagentens svar. Mer information finns i SDK-exempel för Fabric dataagent på GitHub.

Publicera dataagenten

Publicera den mellanlagrade konfigurationen för att göra dataagenten tillgänglig för frågor.

agent.publish_staging(description="Initial publish")

Ställ frågor till en publicerad dataagent

När du har publicerat dataagenten, fråga den via dess MCP-slutpunkt. MCP-slutpunkten är körnings- och åtkomstytan för dataagenten. Du kan ansluta till den från verktyg, program och andra agenter för att fråga dataagenten, ställa frågor och få svar. Konfigurationssteg och klienter som stöds finns i Dataagent som en modellkontextprotokollserver.

Hämta URL för slutpunkt

Du kan hämta MCP-slutpunkts-URL:en på två sätt:

• Kopiera den från inställningarna för dataagenten. När du har publicerat dataagenten öppnar du fliken Modellkontextprotokoll i agentinställningarna och kopierar MCP-serverns URL. Mer information finns i Dataagent som modellkontextprotokollserver.

• Skapa den manuellt. Skapa URL:en från ditt arbetsyte-ID och dataagent-ID (artefakt) med följande format:

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

  Ersätt platshållarna med värden från din publicerade dataagent:

  Placeholder	Description
  {WorkspaceId}	ID:t för den Fabric arbetsyta som innehåller dataagenten.
  {DataAgentId}	ID:t för den publicerade dataagenten.

  En manuellt skapad URL fungerar bara när du har publicerat dataagenten. Om dataagenten inte publiceras returnerar slutpunkten ett fel även när URL:en är korrekt.

Authentication

Begäranden till MCP-slutpunkten måste autentiseras mot Fabric. Kontrollera att klienten innehåller en giltig ägartoken med behörighet att komma åt målarbetsytan och dataagenten. Token kan representera antingen en användaridentitet eller ett tjänsthuvudnamn (SPN).

Tillgängliga verktyg

Fabric-dataagenten exponerar en MCP-server som tillhandahåller ett enda verktyg. Klienter anropar det här verktyget för att skicka en fråga till dataagenten och ta emot det genererade svaret.

Fråga dataagenten med Python

Följande exempel ansluter till MCP-slutpunkten, identifierar verktyget, skickar en fråga och skriver ut svaret. Den återanvänder credential från autentisera till Fabric steg och använder MCP-Python SDK. Installera SDK:et 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)

Relaterat innehåll

• Skapa en Fabric-dataagent
• Dataagent som modellkontextprotokollserver
• Fabric SDK-exempel för dataagenten
• Fabric REST API-referens