Fabric data agent Python SDK (forhåndsvisning)

Fabric-dataagenten Python SDK gir programmatisk tilgang til Fabric-dataagent-artefakter. Den er designet for kode-først-brukere som ønsker å lage, konfigurere, oppdatere og publisere dataagenter uten å bruke Fabric-portalen. Du kan kjøre SDK-en inne i en Microsoft Fabric-notebook, eller fra ditt eget miljø etter at du har autentisert deg til Fabric.

Viktig!

Fabric Data Agent SDK er i overgang fra OpenAI Assistants API til OpenAI Responses API for forespørsler på dataagenter. Hvis du spør en dataagent med Fabric OpenAI-klienten, kan du begynne å migrere til Fabric OpenAI Responses-klienten fra 11. august 2026 før Assistants API-avviklingen trer i kraft 26. august 2026. Bare endringene i koden du spørrer – opprettelse, konfigurasjon og publisering av data-agenter forblir de samme. For migreringssteg og et kjørbart eksempel, se Responses API-eksempelnotatboken.

Viktig!

Denne funksjonen er i forhåndsversjon.

Administrasjonsplan og kjøretid

SDK-en er et styringsplan-verktøy. Bruk det til å styre livssyklusen til en dataagent: lag artefaktet, legg til og konfigurer datakilder, sett instruksjoner og eksempelforespørsler, og publiser. Den kjører på Fabric sitt offentlige REST API, som er den samme overflaten du allerede bruker for andre arbeidsområder og elementer, så autentisering og forespørselsmønstre er de samme.

Administrasjonsplanet er separat fra hvordan du spør dataagenten under kjøring. Etter at du har publisert en dataagent, spør den gjennom Model Context Protocol (MCP)-endepunktet fra verktøy, applikasjoner og andre agentiske opplevelser. For mer informasjon, se Data agent som en Model Context Protocol-server.

Prerequisites

  • Et Fabric-arbeidsområde med kapasitet som støtter dataagenter.
  • En støttet datakilde i arbeidsområdet, som et lakehouse, lager, Power BI semantisk modell eller KQL-database.
  • Python 3.10 eller nyere.
  • For utførelse utenfor en Fabric-notebook, en måte å autentisere til Fabric, som Azure CLI eller en tjenesteprincipal.

Installation

SDK-en publiseres på PyPI som fabric-data-agent-sdk. Installer den ved å bruke pip:

%pip install fabric-data-agent-sdk

Autentiser til Fabric

Når du kjører SDK-en inne i en Fabric-notebook, håndterer notebooken autentiseringen for deg.

Når du kjører SDK-en utenfor Fabric, logg inn på Fabric først. Følgende eksempel logger inn med Azure CLI-legitimasjonen og setter den som standard for økten. Du kan bruke enten en brukerkonto eller en tjenesteprinsipp.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Bemerkning

Kontoen eller tjenestelederen du autentiserer deg med må ha tillatelse til å opprette og administrere elementer i målarbeidsområdet.

Opprett en dataagent

Opprett en dataagent i et arbeidsområde. Erstatt arbeidsområdets ID med ID-en til arbeidsområdet der dataagenten befinner seg.

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 legg til datakilder

Sett agentinstruksjonene, og legg deretter til en datakilde. Bruk artefakt-ID-en til en eksisterende lakehouse, lager, semantisk modell 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å legge til instruksjoner for datakilden og eksempelforespørsler for å forbedre kvaliteten på dataagentens svar. For å lære mer, se Fabric data agent SDK-eksemplene på GitHub.

Publiser dataagenten

Publiser den trinnvise konfigurasjonen for å gjøre dataagenten tilgjengelig for forespørsler.

agent.publish_staging(description="Initial publish")

Bemerkning

Publisering gjennom SDK-en fungerer både innenfor og utenfor Fabric. Å publisere en dataagent til Microsoft 365 Copilot bruker ikke det offentlige API-et ennå, så du gjør fortsatt det fra Fabric, enten i portalen eller ved å kjøre SDK-en i en Fabric-notatbok.

Søk en publisert dataagent

Etter at du har publisert dataagenten, spør den via MCP-endepunktet. MCP-endepunktet er kjøretids- og forbruksflaten for dataagenten. Du kan koble deg til den fra verktøy, applikasjoner og andre agenter for å spørre dataagenten, stille spørsmål og motta svar. For oppsettssteg og støttede klienter, se Data agent som en Model Context Protocol-server.

Viktig!

Dataagenten fungerer som en MCP-server bare etter at du har publisert den. Hvis du ikke publiserer dataagenten, fungerer ikke MCP-endepunktet.

Hent endepunkts-URL-en

Du kan få MCP-endepunktets URL på to måter:

  • Kopier det fra dataagent-innstillingene. Etter at du har publisert dataagenten, åpne fanen Model Context Protocol i agentinnstillingene og kopier MCP-serverens URL. For detaljer, se Data agent som en Model Context Protocol-server.

  • Bygg det manuelt. Konstruer URL-en fra arbeidsområdets ID og dataagentens (artefakts) ID ved å bruke følgende format:

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

    Erstatt plassholderne med verdier fra din publiserte dataagent:

    Plassholder Beskrivelse
    {WorkspaceId} ID-en til Fabric-arbeidsområdet som inneholder dataagenten.
    {DataAgentId} ID-en til den publiserte dataagenten.

    En manuelt bygget URL fungerer bare etter at du har publisert dataagenten. Hvis dataagenten ikke er publisert, returnerer endepunktet en feil selv om URL-en er korrekt.

Godkjenning

Forespørsler til MCP-endepunktet må autentiseres mot Fabric. Sørg for at klienten din inkluderer en gyldig bærertoken med tillatelser til å få tilgang til målarbeidsområdet og dataagenten. Tokenet kan representere enten en brukeridentitet eller en tjenesteprincipal (SPN).

Tilgjengelige verktøy

Fabric-dataagenten eksponerer en MCP-server som tilbyr ett enkelt verktøy. Kunder kaller dette verktøyet for å sende et spørsmål til dataagenten og motta det genererte svaret.

Spør dataagenten fra Python

Følgende eksempel kobles til MCP-endepunktet, oppdager verktøyet, sender et spørsmål og skriver ut svaret. Den gjenbruker steget credential fra Authenticate to Fabric og bruker 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)

Relatert innhold

  • Last updated on