SDK Python de l’assistant de données Fabric (préversion)

Le sdk Fabric de l’agent de données Python fournit un accès programmatique aux artefacts de l’agent de données Fabric. Il est conçu pour les utilisateurs qui souhaitent créer, configurer, mettre à jour et publier des agents de données sans utiliser le portail Fabric. Vous pouvez exécuter le Kit de développement logiciel (SDK) à l’intérieur d’un bloc-notes Microsoft Fabric ou à partir de votre propre environnement après vous être authentifié auprès de Fabric.

Plan de gestion et runtime

Le Kit de développement logiciel (SDK) est un outil de plan de gestion. Utilisez-le pour gérer le cycle de vie d’un agent de données : créez l’artefact, ajoutez et configurez des sources de données, définissez des instructions et des exemples de requêtes et publiez. Il s’exécute sur l’API REST publique Fabric, qui est la même surface que celle que vous utilisez déjà pour d’autres espaces de travail et éléments, de sorte que l’authentification et les modèles de requête sont identiques.

Le plan de gestion est distinct de la façon dont vous interrogez l’agent de données au moment de l’exécution. Après avoir publié un agent de données, interrogez-le via son point de terminaison MCP (Model Context Protocol) à partir d’outils, d’applications et d’autres expériences agentiques. Pour plus d’informations, consultez l’agent de données en tant que serveur de protocole de contexte de modèle.

Conditions préalables

• Un espace de travail Fabric avec une capacité prenant en charge les agents de données.
• Une source de données prise en charge dans l’espace de travail, telle qu’un lakehouse, un entrepôt, un modèle sémantique Power BI ou une base de données KQL.
• Python 3.10 ou version ultérieure.
• Pour une exécution en dehors d’un bloc-notes Fabric, un moyen de s’authentifier auprès de Fabric, tel que le Azure CLI ou un principal de service.

Installation

Le Kit de développement logiciel (SDK) est publié sur PyPI en tant que fabric-data-agent-sdk. Installez-le à l’aide de pip :

%pip install fabric-data-agent-sdk

S’authentifier auprès de Fabric

Lorsque vous exécutez le Kit de développement logiciel (SDK) à l’intérieur d’un bloc-notes Fabric, le notebook gère l’authentification pour vous.

Lorsque vous exécutez le Kit de développement logiciel (SDK) en dehors de Fabric, connectez-vous d’abord à Fabric. L’exemple suivant se connecte avec les informations d’identification Azure CLI et le définit comme valeur par défaut pour la session. Vous pouvez utiliser un compte d’utilisateur ou un principal de service.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Créer un agent de données

Créez un agent de données dans un espace de travail. Remplacez l’ID de l’espace de travail par l’ID de l’espace de travail où existe l’agent de données.

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

Configurer l’agent de données et ajouter des sources de données

Définissez les instructions de l’agent, puis ajoutez une source de données. Utilisez l’ID d’artefact d’un lakehouse, d’un warehouse, d’un modèle sémantique ou d’une base de données KQL existant.

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

Vous pouvez également ajouter des instructions de source de données et des exemples de requêtes pour améliorer la qualité des réponses de l’agent de données. Pour plus d’informations, consultez les exemples de sdk de l’agent de données Fabric sur GitHub.

Publier l’agent de données

Publiez la configuration intermédiaire pour rendre l’agent de données disponible pour l’interrogation.

agent.publish_staging(description="Initial publish")

Interroger un agent de données publié

Après avoir publié l’agent de données, interrogez-le via son point de terminaison MCP. Le point de terminaison MCP est l’aire d’exécution et de consommation de l’agent de données. Vous pouvez vous y connecter à partir d’outils, d’applications et d’autres agents pour interroger l’agent de données, poser des questions et recevoir des réponses. Pour connaître les étapes d’installation et les clients pris en charge, consultez l’agent de données en tant que serveur de protocole de contexte de modèle.

Obtenir l’URL du point de terminaison

Vous pouvez obtenir l’URL du point de terminaison MCP de deux façons :

• Copiez-la depuis les paramètres de l’agent de données. Après avoir publié l’agent de données, ouvrez l’onglet Protocole de contexte de modèle dans les paramètres de l’agent et copiez l’URL du serveur MCP. Pour plus d’informations, consultez l’agent de données en tant que serveur de protocole de contexte de modèle.

• Générez-le manuellement. Construisez l’URL à partir de votre ID d’espace de travail et de votre ID d’agent de données (artefact) en utilisant le format suivant :

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

  Remplacez les espaces réservés par les valeurs issues de votre agent de données publié :

  Texte de remplacement	Description
  {WorkspaceId}	ID de l’espace de travail Fabric qui contient l’agent de données.
  {DataAgentId}	L’ID de l’agent de données publié.

  Une URL générée manuellement fonctionne uniquement après avoir publié l’agent de données. Si l’agent de données n’est pas publié, le point de terminaison retourne une erreur même lorsque l’URL est correcte.

Authentication

Les demandes adressées au point de terminaison MCP doivent être authentifiées sur Fabric. Assurez-vous que votre client inclut un jeton de porteur valide avec les autorisations nécessaires pour accéder à l’espace de travail cible et à l’agent de données. Le jeton peut représenter une identité utilisateur ou un principal de service (SPN).

Outils disponibles

L’agent de données Fabric expose un serveur MCP qui fournit un seul outil. Les clients appellent cet outil pour envoyer une question à l’agent de données et recevoir la réponse générée.

Interroger l’agent de données à partir de Python

L’exemple suivant se connecte au point de terminaison MCP, découvre l’outil, envoie une question et imprime la réponse. Il réutilise le credential de l’étape S’authentifier auprès de Fabric et utilise le SDK Python MCP. Installez d’abord le Kit de développement logiciel (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)

Contenu connexe

• Créer un agent de données Fabric
• Agent de données comme serveur Model Context Protocol
• exemples de sdk de l’agent de données Fabric
• Informations de référence sur l’API REST Fabric