SDK de Python del agente de datos de Fabric (vista previa)

El SDK de Python del agente de datos de Fabric proporciona acceso mediante programación a los artefactos del agente de datos de Fabric. Está diseñado para usuarios orientados al código que quieren crear, configurar, actualizar y publicar agentes de datos sin necesidad de usar el portal de Fabric. Puede ejecutar el SDK dentro de un cuaderno de Microsoft Fabric o desde su propio entorno después de autenticarse en Fabric.

Plano de administración y tiempo de ejecución

El SDK es una herramienta de plano de administración. Úselo para administrar el ciclo de vida de un agente de datos: cree el artefacto, agregue y configure orígenes de datos, establezca instrucciones y consultas de ejemplo y publique. Se ejecuta en la API rest pública de Fabric, que es la misma superficie que ya usa para otras áreas de trabajo y elementos, por lo que la autenticación y los patrones de solicitud son los mismos.

El plano de administración es independiente de cómo se consulta el agente de datos en tiempo de ejecución. Después de publicar un agente de datos, consúltalo a través de su endpoint del Protocolo de Contexto de Modelo (MCP) desde herramientas, aplicaciones y otras experiencias agénticas. Para obtener más información, vea Agente de datos como servidor de protocolo de contexto de modelo.

Prerrequisitos

• Un espacio de trabajo de Fabric con una capacidad compatible con agentes de datos.
• Un origen de datos admitido en el espacio de trabajo, como un lakehouse, un almacén, un modelo semántico de Power BI o una base de datos KQL.
• Python 3.10 o posterior.
• Para ejecutar fuera de un cuaderno de Fabric, un método para autenticarse en Fabric, como la CLI de Azure o una entidad de servicio.

Instalación

El SDK se publica en PyPI como fabric-data-agent-sdk. Instálelo usando pip:

%pip install fabric-data-agent-sdk

Autenticación en Fabric

Al ejecutar el SDK dentro de un cuaderno de Fabric, el cuaderno controla la autenticación por usted.

Al ejecutar el SDK fuera de Fabric, inicie sesión en Fabric primero. En el ejemplo siguiente se inicia sesión con la credencial de CLI de Azure y se establece como valor predeterminado para la sesión. Puede usar una cuenta de usuario o una entidad de servicio.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Crear un agente de datos

Cree un agente de datos en un área de trabajo. Reemplace el identificador del área de trabajo por el identificador del área de trabajo donde existe el agente de datos.

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

Configuración del agente de datos y adición de orígenes de datos

Establezca las instrucciones del agente y agregue un origen de datos. Use el identificador de artefacto de una base de datos existente de lakehouse, warehouse, semantic model o KQL.

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

También puede agregar instrucciones de origen de datos y consultas de ejemplo para mejorar la calidad de las respuestas del agente de datos. Para más información, consulte los ejemplos del SDK del agente de datos de Fabric en GitHub.

Publica el agente de datos

Publique la configuración almacenada provisionalmente para que el agente de datos esté disponible para realizar consultas.

agent.publish_staging(description="Initial publish")

Consultar un agente de datos publicado

Después de publicar el agente de datos, consúltalo a través de su endpoint de MCP. El punto de conexión de MCP es la superficie de tiempo de ejecución y consumo para el agente de datos. Puede conectarse a él desde herramientas, aplicaciones y otros agentes para consultar al agente de datos, formular preguntas y recibir respuestas. Para conocer los pasos de instalación y los clientes admitidos, consulte Agente de datos como servidor de protocolo de contexto de modelo.

Obtención de la dirección URL del punto de conexión

Puede obtener la dirección URL del punto de conexión de MCP de dos maneras:

• Cópielo desde la configuración del agente de datos. Después de publicar el agente de datos, abra la pestaña Protocolo de contexto de modelo en la configuración del agente y copie la dirección URL del servidor MCP. Para obtener más información, consulte Agente de datos como servidor de protocolo de contexto de modelo.

• Compile manualmente. Construya la dirección URL a partir del identificador del área de trabajo y el identificador del agente de datos (artefacto) mediante el siguiente formato:

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

  Sustituya los marcadores de posición con los valores de su agente de datos publicado:

  Marcador de posición	Description
  {WorkspaceId}	El ID del área de trabajo de Fabric que contiene el agente de datos.
  {DataAgentId}	El ID del agente de datos publicado.

  Una dirección URL compilada manualmente solo funciona después de publicar el agente de datos. Si el agente de datos no está publicado, el punto de conexión devuelve un error incluso cuando la dirección URL es correcta.

Authentication

Las solicitudes al punto de conexión de MCP deben autenticarse en Fabric. Asegúrese de que el cliente incluye un token de portador válido con permisos para acceder al área de trabajo de destino y al agente de datos. El token puede representar una identidad de usuario o una entidad de servicio (SPN).

Herramientas disponibles

El agente de datos Fabric expone un servidor MCP que proporciona una sola herramienta. Los clientes llaman a esta herramienta para enviar una pregunta al agente de datos y recibir la respuesta generada.

Consulta del agente de datos desde Python

El ejemplo siguiente se conecta al punto de conexión de MCP, detecta la herramienta, envía una pregunta e imprime la respuesta. Reutiliza el credential del paso Autenticarse en Fabric y utiliza el SDK de Python para MCP. Instale primero el 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)

Contenido relacionado

• Creación de un agente de datos de Fabric
• Agente de datos como un servidor de Model Context Protocol
• ejemplos del SDK del agente de datos de Fabric
• Referencia de la API REST de Fabric