Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
De Fabric gegevensagent Python SDK biedt programmatische toegang tot Fabric gegevensagentartefacten. Het is ontworpen voor code-first-gebruikers die gegevensagenten willen maken, configureren, bijwerken en publiceren zonder de Fabric-portal te gebruiken. U kunt de SDK uitvoeren in een Microsoft Fabric notebook of vanuit uw eigen omgeving nadat u zich hebt geverifieerd bij Fabric.
Belangrijk
De Fabric Data Agent SDK maakt de overstap van de OpenAI Assistants API naar de OpenAI Responses API voor het opvragen van data-agenten. Als je een dataagent vraagt via de Fabric OpenAI-client, kun je vanaf 11 augustus 2026 beginnen met migreren naar de Fabric OpenAI Responses-client voordat de Assistants API-deprecatie op 26 augustus 2026 van kracht wordt. Alleen je query-code verandert—het aanmaken, configureren en publiceren van dataagenten blijft hetzelfde. Voor migratiestappen en een uitvoerbaar voorbeeld, zie het voorbeeldnotitieboek Responses API.
Belangrijk
Deze functie is beschikbaar als preview-versie.
Beheervlak en uitvoeringsomgeving
De SDK is een hulpmiddel voor het beheervlak. Hiermee kunt u de levenscyclus van een gegevensagent beheren: het artefact maken, gegevensbronnen toevoegen en configureren, instructies en voorbeeldquery's instellen en publiceren. Deze wordt uitgevoerd op de Fabric openbare REST API. Dit is hetzelfde oppervlak dat u al gebruikt voor andere werkruimten en items, dus verificatie en de aanvraagpatronen zijn hetzelfde.
Het beheervlak staat los van de wijze waarop u tijdens runtime query's uitvoert op de gegevensagent. Nadat u een gegevensagent hebt gepubliceerd, voert u een query uit via het MCP-eindpunt (Model Context Protocol) vanuit hulpprogramma's, toepassingen en andere agentische ervaringen. Zie Gegevensagent als een Model Context Protocol-server voor meer informatie.
Vereiste voorwaarden
- Een Fabric werkruimte met een capaciteit die ondersteuning biedt voor gegevensagenten.
- Een ondersteunde gegevensbron in de werkruimte, zoals een lakehouse, magazijn, Power BI semantisch model of KQL-database.
- Python 3.10 of hoger.
- Voor uitvoering buiten een Fabric-notebook hebt u een manier nodig om u bij Fabric te authenticeren, zoals de Azure CLI of een service-principal.
Installatie
De SDK wordt gepubliceerd op PyPI als fabric-data-agent-sdk. Installeer het met behulp van pip:
%pip install fabric-data-agent-sdk
Verifiëren bij Fabric
Wanneer u de SDK uitvoert in een Fabric notebook, verwerkt het notebook verificatie voor u.
Wanneer u de SDK buiten Fabric uitvoert, meldt u zich eerst aan bij Fabric. In het volgende voorbeeld meldt u zich aan met de Azure CLI-aanmeldingsgegevens en worden deze ingesteld als de standaard voor de sessie. U kunt een gebruikersaccount of een service-principal gebruiken.
from azure.identity import AzureCliCredential
from fabric.analytics.environment.credentials import (
SetFabricAnalyticsDefaultTokenCredentialsGlobally,
)
credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)
Note
Het account of de service-principal waarmee u zich verifieert, moet gemachtigd zijn om items in de doelwerkruimte te maken en te beheren.
Een gegevensagent maken
Maak een gegevensagent in een werkruimte. Vervang de werkruimte-id door de id van de werkruimte waarin de gegevensagent bestaat.
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,
)
De gegevensagent configureren en gegevensbronnen toevoegen
Stel de instructies voor de agent in en voeg vervolgens een gegevensbron toe. Gebruik de artefact-id van een bestaande lakehouse-, magazijn-, semantische model- of 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,
)
U kunt ook instructies voor gegevensbronnen en voorbeeldquery's toevoegen om de kwaliteit van de antwoorden van de gegevensagent te verbeteren. Zie de Fabric sdk-voorbeelden van de gegevensagent op GitHub voor meer informatie.
De gegevensagent publiceren
Publiceer de gefaseerde configuratie om de gegevensagent beschikbaar te maken voor het uitvoeren van query's.
agent.publish_staging(description="Initial publish")
Note
Publiceren via de SDK werkt binnen en buiten Fabric. Het publiceren van een gegevensagent naar Microsoft 365 Copilot maakt nog geen gebruik van de openbare API, dus u doet dat nog steeds vanuit Fabric, in de portal of door de SDK uit te voeren in een Fabric notebook.
Een query uitvoeren op een gepubliceerde gegevensagent
Nadat u de gegevensagent hebt gepubliceerd, voert u een query uit via het MCP-eindpunt. Het MCP-eindpunt is het runtime- en verbruiksoppervlak voor de gegevensagent. U kunt er verbinding mee maken vanuit hulpprogramma's, toepassingen en andere agents om een query uit te voeren op de gegevensagent, vragen te stellen en antwoorden te ontvangen. Zie Gegevensagent als modelcontextprotocolserver voor installatiestappen en ondersteunde clients.
Belangrijk
De gegevensagent werkt alleen als een MCP-server nadat u deze hebt gepubliceerd. Als u de gegevensagent niet publiceert, werkt het MCP-eindpunt niet.
De eindpunt-URL ophalen
U kunt de MCP-eindpunt-URL op twee manieren ophalen:
Kopieer deze vanuit de instellingen van de gegevensagent. Nadat u de gegevensagent hebt gepubliceerd, opent u het tabblad ModelContext Protocol in de agentinstellingen en kopieert u de URL van de MCP-server. Zie De gegevensagent als een Model Context Protocol-server voor meer informatie.
Bouw het handmatig. Stel de URL samen op basis van uw werkruimte-ID en de ID van de data-agent (artefact) in de volgende indeling:
https://api.fabric.microsoft.com/v1/mcp/workspaces/{WorkspaceId}/dataagents/{DataAgentId}/agentVervang de tijdelijke aanduidingen door waarden van uw gepubliceerde gegevensagent:
Placeholder Description {WorkspaceId}De id van de Fabric-werkruimte die de data-agent bevat. {DataAgentId}De ID van de gepubliceerde data-agent. Een handmatig gebouwde URL werkt alleen nadat u de gegevensagent hebt gepubliceerd. Als de gegevensagent niet is gepubliceerd, retourneert het eindpunt een fout, zelfs wanneer de URL juist is.
Authentication
Aanvragen voor het MCP-eindpunt moeten worden geverifieerd op basis van Fabric. Zorg ervoor dat uw client een geldig Bearer-token bevat met machtigingen voor toegang tot de doelwerkruimte en gegevensagent. Het token kan een gebruikersidentiteit of een SERVICE-principal (SPN) vertegenwoordigen.
Beschikbare hulpmiddelen
De Fabric gegevensagent maakt een MCP-server beschikbaar die één hulpprogramma biedt. Clients noemen dit hulpprogramma om een vraag naar de gegevensagent te verzenden en het gegenereerde antwoord te ontvangen.
Een query uitvoeren op de gegevensagent vanuit Python
In het volgende voorbeeld wordt verbinding gemaakt met het MCP-eindpunt, het hulpprogramma gedetecteerd, een vraag verzonden en het antwoord afgedrukt. Het maakt opnieuw gebruik van de credential uit de stap Verifiëren bij Fabric en gebruikt de MCP Python SDK. Installeer eerst de 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)