SDK Python untuk Agen Data Fabric (pratinjau)

Agen data Fabric Python SDK menyediakan akses terprogram ke artefak agen data Fabric. Ini dirancang untuk pengguna code-first yang ingin membuat, mengonfigurasi, memperbarui, dan menerbitkan agen data tanpa menggunakan portal Fabric. Anda dapat menjalankan SDK di dalam buku catatan Microsoft Fabric, atau dari lingkungan Anda sendiri setelah Mengautentikasi ke Fabric.

Penting

Fabric Data Agent SDK sedang beralih dari API OpenAI Assistants ke API OpenAI Responses untuk melakukan kueri agen data. Jika Anda melakukan query pada agen data dengan klien Fabric OpenAI, Anda dapat mulai bermigrasi ke klien Fabric OpenAI Responses mulai 11 Agustus 2026 sebelum deprekasi API Assistants berlaku pada 26 Agustus 2026. Hanya kode kueri Anda yang berubah—membuat, mengonfigurasi, dan mempublikasikan agen data tetap sama. Untuk langkah migrasi dan contoh yang dapat dijalankan, lihat notebook contoh API Responses.

Penting

Fitur ini sedang dalam tahap pratinjau.

Lapisan manajemen dan runtime

SDK adalah alat sarana manajemen. Gunakan untuk mengelola siklus hidup agen data: membuat artefak, menambahkan dan mengonfigurasi sumber data, mengatur instruksi dan contoh kueri, dan menerbitkan. Ini berjalan pada REST API publik Fabric, yang merupakan permukaan yang sama yang sudah Anda gunakan untuk ruang kerja dan item lain, sehingga autentikasi dan pola permintaannya sama.

Bidang manajemen terpisah dari cara Anda mengkueri agen data saat runtime. Setelah Anda menerbitkan agen data, ajukan kueri ke agen tersebut melalui titik akhir Model Context Protocol (MCP)-nya dari alat, aplikasi, dan pengalaman agentik lainnya. Untuk informasi selengkapnya, lihat Agen data sebagai server Protokol Konteks Model.

Prasyarat

  • Ruang kerja Fabric dengan kapasitas yang mendukung agen data.
  • Sumber data yang didukung di ruang kerja, seperti lakehouse, gudang data, model semantik Power BI, atau basis data KQL.
  • Python 3.10 atau yang lebih baru.
  • Untuk menjalankan di luar notebook Fabric, Anda memerlukan metode autentikasi ke Fabric, seperti Azure CLI atau prinsipal layanan.

Instalasi

SDK diterbitkan di PyPI sebagai fabric-data-agent-sdk. Instal menggunakan pip:

%pip install fabric-data-agent-sdk

Mengautentikasi ke Fabric

Saat Anda menjalankan SDK di dalam buku catatan Fabric, buku catatan menangani autentikasi untuk Anda.

Saat Anda menjalankan SDK di luar Fabric, masuk ke Fabric terlebih dahulu. Contoh berikut masuk dengan kredensial Azure CLI dan mengaturnya sebagai default untuk sesi. Anda dapat menggunakan akun pengguna atau perwakilan layanan.

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

credential = AzureCliCredential()
SetFabricAnalyticsDefaultTokenCredentialsGlobally(credential)

Note

Akun atau perwakilan layanan yang Anda autentikasi harus memiliki izin untuk membuat dan mengelola item di ruang kerja target.

Membuat agen data

Buat agen data di ruang kerja. Ganti ID ruang kerja dengan ID ruang kerja tempat agen data berada.

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

Mengonfigurasi agen data dan menambahkan sumber data

Atur instruksi agen, lalu tambahkan sumber data. Gunakan ID artefak dari lakehouse, gudang, model semantik, atau database KQL yang ada.

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

Anda juga dapat menambahkan instruksi sumber data dan contoh kueri untuk meningkatkan kualitas jawaban agen data. Untuk mempelajari selengkapnya, lihat sampel SDK agen data Fabric di GitHub.

Menerbitkan agen data

Publikasikan konfigurasi yang dipentaskan agar agen data tersedia untuk dikueri.

agent.publish_staging(description="Initial publish")

Note

Penerbitan melalui SDK berfungsi di dalam dan di luar Fabric. Menerbitkan agen data ke Microsoft 365 Copilot belum menggunakan API publik, jadi Anda masih harus melakukannya melalui Fabric, baik melalui portal maupun dengan menjalankan SDK di notebook Fabric.

Membuat kueri pada agen data yang dipublikasikan

Setelah Anda mempublikasikan agen data, kueri agen tersebut melalui endpoint MCP-nya. Endpoint MCP adalah runtime dan antarmuka konsumsi bagi agen data. Anda dapat menyambungkannya dari alat, aplikasi, dan agen lain untuk mengkueri agen data, mengajukan pertanyaan, dan menerima jawaban. Untuk langkah-langkah penyiapan dan klien yang didukung, lihat Agen data sebagai server Protokol Konteks Model.

Penting

Agen data berfungsi sebagai server MCP hanya setelah Anda menerbitkannya. Jika Anda tidak menerbitkan agen data, titik akhir MCP tidak berfungsi.

Mendapatkan URL titik akhir

Anda bisa mendapatkan URL titik akhir MCP dengan dua cara:

  • Salin itu dari pengaturan agen data. Setelah Anda menerbitkan agen data, buka tab Protokol Konteks Model di pengaturan agen dan salin URL server MCP. Untuk detailnya, lihat Agen data sebagai server Protokol Konteks Model.

  • Buat secara manual. Buat URL dari ID ruang kerja dan ID agen data (artefak) Anda dengan menggunakan format berikut:

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

    Ganti placeholder dengan nilai dari agen data yang telah Anda publikasikan:

    Placeholder Deskripsi
    {WorkspaceId} ID ruang kerja Fabric yang berisi agen data.
    {DataAgentId} ID dari agen data yang dipublikasikan.

    URL yang dibuat secara manual hanya berfungsi setelah Anda menerbitkan agen data. Jika agen data tidak diterbitkan, titik akhir mengembalikan kesalahan bahkan ketika URL sudah benar.

Authentication

Permintaan ke titik akhir MCP harus diautentikasi terhadap Fabric. Pastikan klien Anda menyertakan token pembawa yang valid dengan izin untuk mengakses ruang kerja target dan agen data. Token dapat mewakili identitas pengguna atau perwakilan layanan (SPN).

Alat yang tersedia

Agen data Fabric mengekspos server MCP yang menyediakan satu alat. Klien memanggil alat ini untuk mengirim pertanyaan ke agen data dan menerima jawaban yang dihasilkan.

Mengkueri agen data dari Python

Contoh berikut terhubung ke titik akhir MCP, menemukan alat, mengirim pertanyaan, dan mencetak jawabannya. Ini menggunakan kembali credential dari langkah Autentikasi ke Fabric dan menggunakan MCP Python SDK. Instal SDK terlebih dahulu:

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

Konten terkait

  • Last updated on