Fabric-tietoagentti Python SDK (esikatselu)

Fabric-dataagentti Python SDK tarjoaa ohjelmallisen pääsyn Fabric-dataagentin artefakteihin. Se on suunniteltu koodiin keskittyville käyttäjille, jotka haluavat luoda, konfiguroida, päivittää ja julkaista dataagentteja ilman Fabric-portaalin käyttöä. Voit ajaa SDK:n Microsoft Fabric -muistikirjan sisällä tai omasta ympäristöstäsi sen jälkeen, kun olet tunnistanut Fabric:lle.

Tärkeää

Fabric Data Agent SDK siirtyy OpenAI Assistants API:sta OpenAI Responses API:hin dataagenttien kyselyihin. Jos kysyt dataagenttia Fabric OpenAI -asiakkaalla, voit aloittaa siirtymisen Fabric OpenAI Responses -asiakkaaseen 11. elokuuta 2026 alkaen ennen kuin Assistants API:n vanhentuminen astuu voimaan 26. elokuuta 2026. Vain kyselykoodisi muuttuu – dataagenttien luominen, konfigurointi ja julkaiseminen pysyy ennallaan. Migraatiovaiheet ja ajettavan esimerkin löydät Responses API -esimerkkimuistikirjasta.

Tärkeää

Tämä ominaisuus on esikatseluvaiheessa.

Hallintataso ja ajoaika

SDK on hallintatasotyökalu. Käytä sitä dataagentin elinkaaren hallintaan: luo artefakti, lisää ja konfiguroi tietolähteitä, aseta käskyjä ja esimerkkikyselyitä sekä julkaise. Se toimii Fabric Public REST API:lla, joka on sama pinta, jota käytät jo muissa työtiloissa ja kohteissa, joten autentikointi ja pyyntökuviot ovat samat.

Hallintataso on erillinen siitä, miten dataagenttia haetaan ajonaikaisesti. Kun olet julkaissut dataagentin, kysy sitä sen Model Context Protocol (MCP) -päätepisteen kautta työkaluista, sovelluksista ja muista agenttisista kokemuksista. Lisätietoja löytyy kohdasta Data agent mallin kontekstiprotokollapalvelimena.

Prerequisites

  • Fabric-työtila, jonka kapasiteetti tukee dataagentteja.
  • Tuettu tietolähde työtilassa, kuten järvitalo, varasto, Power BI-semanttinen malli tai KQL-tietokanta.
  • Python 3.10 tai uudempi.
  • Fabric-muistikirjan ulkopuolella suoritukseen on tapa todentaa Fabric, kuten Azure CLI tai palvelupäähenkilö.

Installation

SDK julkaistaan PyPI:ssä nimellä fabric-data-agent-sdk. Asenna se käyttämällä pip:tä:

%pip install fabric-data-agent-sdk

Authenticate to Fabric

Kun ajat SDK:n Fabric-muistikirjan sisällä, se hoitaa tunnistautumisen puolestasi.

Kun ajat SDK:n Fabric-sivuston ulkopuolella, kirjaudu ensin Fabric-palveluun. Seuraava esimerkki kirjautuu sisään Azure CLI -tunnisteella ja asettaa sen istunnon oletuksena. Voit käyttää joko käyttäjätiliä tai palvelupäätä.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Muistio

Tilillä tai palvelupäähenkilöllä, jonka kanssa tunnistat, täytyy saada lupa luoda ja hallita kohteita kohdetyötilassa.

Luo dataagentti

Luo dataagentti työtilaan. Korvaa työtilan ID sen työtilan ID:llä, jossa dataagentti sijaitsee.

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

Määritä dataagentti ja lisää tietolähteitä

Aseta agentin ohjeet ja lisää sitten tietolähde. Käytä olemassa olevan järvenrakennuksen, varaston, semanttisen mallin tai KQL-tietokannan artefakti-ID:tä.

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

Voit myös lisätä tietolähteiden ohjeita ja esimerkkikyselyitä parantaaksesi dataagentin vastausten laatua. Lisätietoja saat katsomalla Fabric-dataagentin SDK-näytteet GitHub-sivustolla.

Julkaise dataagentti

Julkaise vaiheittainen konfiguraatio, jotta dataagentti on saatavilla kyselyihin.

agent.publish_staging(description="Initial publish")

Muistio

SDK:n kautta julkaiseminen toimii sekä Fabric:n sisällä että ulkopuolella. Dataagentin julkaiseminen Microsoft 365 Copilot -ohjelmaan ei vielä käytä julkista API:a, joten se tehdään edelleen Fabric:n sisältä, joko portaalissa tai ajamalla SDK:ta Fabric-muistikirjassa.

Hae julkaistua dataagenttia

Kun olet julkaissut dataagentin, tee siitä kysely sen MCP-päätepisteen kautta. MCP-päätepiste on dataagentin ajonaikainen ja kulutuspinta. Voit yhdistää siihen työkaluista, sovelluksista ja muista agenteista tiedustellut dataagenttia, esittääksesi kysymyksiä ja vastaanottaaksesi vastauksia. Asennusvaiheet ja tuetut asiakkaat löytyvät kohdasta Data agent as a Model Context Protocol -palvelin.

Tärkeää

Dataagentti toimii MCP-palvelimena vasta julkaisun jälkeen. Jos et julkaise dataagenttia, MCP-päätepiste ei toimi.

Hae päätepisteen URL

MCP-päätepisteen URL-osoitteen saa kahdella tavalla:

  • Kopioi se dataagentin asetuksista. Kun olet julkaissut dataagentin, avaa Model Context Protocol -välilehti agentin asetuksista ja kopioi MCP-palvelimen URL-osoite. Lisätietoja löytyy kohdasta Data agentti mallin kontekstiprotokollapalvelimena.

  • Rakenna se manuaalisesti. Rakenna URL työtilan ID:stä ja dataagentin (artefakti) ID:stä seuraavalla muodolla:

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

    Korvaa paikkamerkit julkaistun dataagenttisi arvoilla:

    Paikkamerkki Description
    {WorkspaceId} Fabric-työtilan ID, joka sisältää dataagentin.
    {DataAgentId} Julkaistun dataagentin tunnus.

    Manuaalisesti rakennettu URL-osoite toimii vasta sen jälkeen, kun olet julkaissut dataagentin. Jos dataagenttia ei julkaista, päätepiste palauttaa virheen, vaikka URL olisi oikea.

Todennus

MCP-päätepisteelle lähetetyt pyynnöt on autentikoitu Fabric-järjestelmää vastaan. Varmista, että asiakkaassasi on voimassa oleva kantajatunniste, jolla on oikeudet käyttää kohdetyötilaa ja dataagenttia. Token voi edustaa joko käyttäjäidentiteettiä tai palvelupäähenkilöä (SPN).

Käytettävissä olevat työkalut

Fabric-dataagentti paljastaa MCP-palvelimen, joka tarjoaa yhden työkalun. Asiakkaat kutsuvat tätä työkalua lähettääkseen kysymyksen dataagentille ja saadakseen generoidun vastauksen.

Kysy dataagenttia Python:sta

Seuraava esimerkki yhdistää MCP-päätepisteen, löytää työkalun, lähettää kysymyksen ja tulostaa vastauksen. Se käyttää credential uudelleen from Authenticate to Fabric -vaihetta ja MCP Python SDK:ta. Asenna SDK ensin:

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

Aiheeseen liittyvä sisältö

  • Last updated on