Программный пакет разработки SDK на Python для агента данных Fabric (предварительная версия)

Пакет SDK Python агента данных Fabric предоставляет программный доступ к артефактам агента данных Fabric. Он предназначен для пользователей кода, которые хотят создавать, настраивать, обновлять и публиковать агенты данных без использования портала Fabric. Пакет SDK можно запустить в записной книжке Microsoft Fabric или из собственной среды после проверки подлинности в Fabric.

Это важно

SDK Fabric Data Agent переходит от API OpenAI Assistants к API OpenAI Responses для запросов к агентам данных. Если вы отправите запрос к агенту данных через клиент Fabric OpenAI, вы сможете начать миграцию на клиент Fabric OpenAI Responses с 11 августа 2026 года до того, как отмещение API Assistants вступит в силу 26 августа 2026 года. Меняется только код запросов — создание, настройка и публикация агентов данных остаются прежними. Для шагов миграции и запускаемого примера см. образец блокнота Responses API.

Это важно

Эта функция доступна в предварительной версии.

Плоскость управления и среда исполнения

SDK — это инструмент для уровня управления. Используйте его для управления жизненным циклом агента данных: создание артефакта, добавление и настройка источников данных, установка инструкций и примеры запросов и публикация. Он выполняется в общедоступном REST API Fabric, которая является той же поверхностью, которая уже используется для других рабочих областей и элементов, поэтому проверка подлинности и шаблоны запросов одинаковы.

Плоскость управления отделена от того, как выполняются запросы к агенту данных во время выполнения. После публикации агента данных обращайтесь к нему через его конечную точку Model Context Protocol (MCP) из инструментов, приложений и других агентных интерфейсов. Дополнительные сведения см. в разделе Агент данных в качестве сервера Model Context Protocol.

Предпосылки

  • Рабочая область Fabric с емкостью, поддерживающей агенты данных.
  • Поддерживаемый источник данных в рабочей области, такой как Lakehouse, хранилище, семантическая модель Power BI или база данных KQL.
  • Python 3.10 или более поздней версии.
  • Для выполнения вне записной книжки в Fabric требуется способ аутентификации в Fabric, например Azure CLI или субъект-службы.

Установка

Пакет SDK публикуется в PyPI как fabric-data-agent-sdk. Установите его с помощью pip:

%pip install fabric-data-agent-sdk

Выполните аутентификацию в Fabric

Когда вы запускаете SDK в записной книжке Fabric, записная книжка выполняет аутентификацию за вас.

При запуске пакета SDK за пределами Fabric сначала войдите в Fabric. В следующем примере выполняется вход с использованием учетных данных Azure CLI, и эти учетные данные устанавливаются в качестве учетных данных по умолчанию для сеанса. Вы можете использовать либо учетную запись пользователя, либо субъект-службу.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Note

Учетная запись или субъект-служба, с помощью которых выполняется проверка подлинности, должна иметь разрешение на создание и управление элементами в целевой рабочей области.

Создание агента данных

Создайте агент данных в рабочей области. Замените идентификатор рабочей области идентификатором рабочей области, в которой существует агент данных.

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

Настройка агента данных и добавление источников данных

Задайте инструкции агента, а затем добавьте источник данных. Используйте идентификатор артефакта существующей базы данных lakehouse, хранилища, семантической модели или базы данных 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,
)

Вы также можете добавить инструкции по источнику данных и примеры запросов, чтобы повысить качество ответов агента данных. Дополнительные сведения см. в примерах пакета SDK для агента данных Fabric GitHub.

Публикация агента данных

Опубликуйте подготовленную конфигурацию, чтобы агент данных стал доступен для выполнения запросов.

agent.publish_staging(description="Initial publish")

Note

Публикация через пакет SDK работает внутри и вне Fabric. Публикация агента данных в Microsoft 365 Copilot пока не выполняется через общедоступный API, поэтому это по-прежнему нужно делать в самой Fabric — либо на портале, либо запустив SDK в записной книжке Fabric.

Запросить опубликованного агента данных

После публикации агента данных запросите его через конечную точку MCP. Конечная точка MCP — это область выполнения и потребления для агента данных. Вы можете подключаться к нему из инструментов, приложений и других агентов, чтобы обращаться к агенту данных с запросами, задавать вопросы и получать ответы. Сведения о шагах настройки и поддерживаемых клиентах см. в разделе Агент данных как сервер протокола Model Context Protocol.

Это важно

Агент данных работает как сервер MCP только после публикации. Если агент данных не опубликован, конечная точка MCP не работает.

Получение URL-адреса конечной точки

URL-адрес конечной точки MCP можно получить двумя способами:

  • Скопируйте его из параметров агента данных. После публикации агента данных откройте вкладку "Протокол контекста модели " в параметрах агента и скопируйте URL-адрес сервера MCP. Подробности см. в разделе «Агент данных как сервер протокола контекста модели».

  • Создайте его вручную. Создайте URL-адрес из идентификатора рабочей области и идентификатора агента данных (артефакта) с помощью следующего формата:

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

    Замените заполнители значениями из опубликованного агента данных:

    Placeholder Description
    {WorkspaceId} Идентификатор рабочей области Fabric, содержащей агент данных.
    {DataAgentId} Идентификатор опубликованного агента данных.

    Созданный вручную URL-адрес работает только после публикации агента данных. Если агент данных не опубликован, конечная точка возвращает ошибку, даже если URL-адрес правильный.

Authentication

Запросы к конечной точке MCP должны проходить проверку подлинности в Fabric. Убедитесь, что ваш клиент передаёт действительный токен Bearer с разрешениями на доступ к целевой рабочей области и агенту данных. Токен может представлять собой либо идентификатор пользователя, либо субъект-службу (SPN).

Доступные средства

Агент данных Fabric предоставляет сервер MCP, предоставляющий один инструмент. Клиенты вызывают это средство для отправки вопроса агенту данных и получения созданного ответа.

Запрос агента данных из Python

Следующий пример подключается к конечной точке MCP, обнаруживает средство, отправляет вопрос и выводит ответ. Он повторно использует credential из шага аутентификации в Fabric и использует MCP Python SDK. Сначала установите пакет 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)

Связанный контент

  • Последнее обновление: