Python SDK pro datového agenta Fabric (náhled)

Sada SDK pro Python pro datového agenta Fabric poskytuje programový přístup k artefaktům datového agenta Fabric. Je navržena pro uživatele preferující práci s kódem, kteří chtějí vytvářet, konfigurovat, aktualizovat a publikovat datové agenty bez použití portálu Fabric. SDK můžete spustit v poznámkovém bloku Microsoft Fabric nebo ze svého prostředí po ověření vůči Fabric.

Důležité

Fabric Data Agent SDK přechází z OpenAI Assistants API na OpenAI Responses API pro dotazování datových agentů. Pokud dotazujete datového agenta pomocí klienta Fabric OpenAI, můžete začít migraci na klienta Fabric OpenAI Responses od 11. srpna 2026, než vstoupí v platnost vyřazení API Assistants 26. srpna 2026. Pouze změny kódu při dotazování – vytváření, konfigurace a publikování datových agentů zůstávají stejné. Pro migrační kroky a spuštěný příklad viz ukázkový zápisník Responses API.

Důležité

Tato funkce je ve verzi Preview.

Rovina správy a modul runtime

Sada SDK je nástroj roviny správy. Slouží ke správě životního cyklu datového agenta: vytvoření artefaktu, přidání a konfigurace zdrojů dat, nastavení pokynů a ukázkových dotazů a publikování. Běží na Fabric veřejném rozhraní REST API, což je stejná plocha, kterou už používáte pro jiné pracovní prostory a položky, takže ověřování a vzory požadavků jsou stejné.

Rovina správy je oddělená od způsobu dotazování datového agenta za běhu. Po publikování datového agenta se na něj dotazujte prostřednictvím jeho koncového bodu protokolu MCP (Model Context Protocol) z nástrojů, aplikací a dalších agentních prostředí. Další informace najdete v tématu Agent dat jako server protokolu kontextu modelu.

Požadavky

  • Pracovní prostor Fabric s kapacitou, která podporuje datové agenty.
  • Podporovaný zdroj dat v pracovním prostoru, jako je lakehouse, warehouse, sémantický model Power BI nebo databáze KQL.
  • Python 3.10 nebo novější.
  • Pro spouštění mimo poznámkový blok Fabric potřebujete způsob ověření vůči Fabric, například Azure CLI nebo instanční objekt služby.

Instalace

SDK je publikováno na PyPI jako fabric-data-agent-sdk. Nainstalujte ho pomocí nástroje pip:

%pip install fabric-data-agent-sdk

Ověření v Fabric

Když spustíte sadu SDK v poznámkovém bloku Fabric, poznámkový blok za vás zajistí ověřování.

Při spuštění sady SDK mimo Fabric se nejprve přihlaste k Fabric. Následující příklad se přihlásí pomocí přihlašovacích údajů Azure CLI a nastaví ho jako výchozí pro relaci. Můžete použít buď uživatelský účet, nebo instanční objekt.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Note

Účet nebo instanční objekt služby, pomocí kterého se ověřujete, musí mít oprávnění k vytváření a správě položek v cílovém pracovním prostoru.

Vytvoření datového agenta

Vytvoření datového agenta v pracovním prostoru Nahraďte ID pracovního prostoru ID pracovního prostoru, ve kterém existuje datový agent.

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

Konfigurace datového agenta a přidání zdrojů dat

Nastavte pokyny agenta a pak přidejte zdroj dat. Použijte ID artefaktu existujícího objektu typu lakehouse, datového skladu, sémantického modelu nebo databáze 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,
)

Můžete také přidat pokyny ke zdroji dat a ukázkové dotazy, abyste zlepšili kvalitu odpovědí datového agenta. Další informace najdete v ukázkách sady SDK datového agenta Fabric na GitHub.

Publikujte datového agenta

Publikujte fázovanou konfiguraci, aby byl datový agent dostupný pro dotazování.

agent.publish_staging(description="Initial publish")

Note

Publikování prostřednictvím sady SDK funguje uvnitř a mimo Fabric. Publikování datového agenta do Microsoft 365 Copilot zatím nevyužívá veřejné rozhraní API, takže to stále musíte provést ve Fabric, a to buď v portálu, nebo spuštěním sady SDK v poznámkovém bloku Fabric.

Dotaz na publikovaného datového agenta

Po publikování datového agenta odesílejte na něj dotazy prostřednictvím jeho koncového bodu MCP. Koncový bod MCP je běhové prostředí a rozhraní pro využívání datového agenta. Můžete se k němu připojit z nástrojů, aplikací a dalších agentů a dotazovat se na agenta dat, klást otázky a získávat odpovědi. Postup nastavení a podporované klienty najdete v článku Datový agent jako server protokolu Model Context Protocol.

Důležité

Datový agent funguje jako server MCP až po jeho publikování. Pokud agenta dat nepublikujete, koncový bod MCP nefunguje.

Získání adresy URL koncového bodu

Adresu URL koncového bodu MCP můžete získat dvěma způsoby:

  • Zkopírujte ho z nastavení datového agenta. Po publikování datového agenta otevřete v nastavení agenta kartu Protokol kontextu modelu a zkopírujte adresu URL serveru MCP. Podrobnosti najdete v tématu Datový agent jako server protokolu Model Context Protocol.

  • Sestavujte ho ručně. Pomocí následujícího formátu vytvořte adresu URL z ID vašeho pracovního prostoru a ID datového agenta (artefaktu):

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

    Zástupné symboly nahraďte hodnotami z publikovaného datového agenta:

    Zástupný text Description
    {WorkspaceId} ID pracovního prostoru Fabric, který obsahuje datového agenta.
    {DataAgentId} ID publikovaného datového agenta.

    Ručně sestavená adresa URL funguje až po publikování datového agenta. Pokud datový agent není publikovaný, koncový bod vrátí chybu i v případě, že je adresa URL správná.

Authentication

Požadavky na koncový bod MCP musí být autentizovány vůči Fabric. Ujistěte se, že váš klient obsahuje platný nosný token s oprávněními pro přístup k cílovému pracovnímu prostoru a datovému agentovi. Token může představovat buď identitu uživatele, nebo instanční objekt služby (SPN).

Dostupné nástroje

Datový agent Fabric zveřejňuje server MCP, který poskytuje jeden nástroj. Klienti volají tento nástroj, aby odeslali dotaz datovému agentu a dostali vygenerovanou odpověď.

Dotazování datového agenta z Python

Následující příklad se připojí ke koncovému bodu MCP, zjistí nástroj, odešle otázku a vytiskne odpověď. Znovu použije credential z kroku Ověření do Fabricu a používá MCP Python SDK. Nejprve nainstalujte sadu 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)

Související obsah

  • Last updated on