The Fabric Data Agent SDK supports programmatic access for Fabric Data Agent artifacts.

This package is released as a preview and has been tested with Microsoft Fabric Python notebooks.

Getting started

Prerequisites

• A Microsoft Fabric subscription. Or sign up for a free Microsoft Fabric (Preview) trial.
• Sign in to Microsoft Fabric.
• Create a new notebook or a new spark job to use this package. Note that semantic link is supported only within Microsoft Fabric.

Install the fabric-data-agent-sdk package

To install the most recent version fabric-data-agent-sdk in your Fabric Python notebook kernel by executing this code in a notebook cell:

%pip install -U fabric-data-agent-sdk

Key concepts

Fabric Data Agent SDK has two main entry points:

• Data plane using OpenAI SDK for conversational interaction with an existing Data Agent artifact.
• Management plane to create, update and delete Data Agent artifacts.

OpenAI Responses API

Use FabricOpenAIResponses to interact with Data Agents through the Responses API:

from fabric.dataagent.client import FabricOpenAIResponses

client = FabricOpenAIResponses(artifact_name="my-agent")
conversation = client.conversations.create()

stream = client.responses.stream(
    input="What is total revenue?",
    conversation=conversation.id,
)
for event in stream:
    pass  # process response.* events as they arrive
response = stream.get_final_response()

print(response.output_text)

To chain follow-up calls without creating a conversation, use OpenAI's previous_response_id pattern:

first_response = client.responses.create(input="What is total revenue?")
follow_up_response = client.responses.create(
    input="Which month had the most revenue?",
    previous_response_id=first_response.id,
)

FabricOpenAIResponses sends gpt-5.1 by default when model is omitted. Pass model="..." to responses.create() or responses.stream() to override it. Non-streaming responses.create() and responses.retrieve() calls always return OpenAI Response objects, including when Fabric sends the underlying payload as a server-sent event stream.

Conversation diagnostics

Diagnostics are available for Responses API conversations through FabricOpenAIResponses.diagnostics:

payload = client.diagnostics.get(
    conversation.id,
    response_id=response.id,  # optional
    chat_scenario="fabric-notebook",  # optional
)

Export writes readable UTF-8 JSON and returns a pathlib.Path. With no path, the file is written to the current working directory using a safe filename based on the conversation ID:

path = client.diagnostics.export(conversation.id)

In a Fabric notebook with a default Lakehouse attached, pass a Files path to make the export available in Fabric/OneLake for download or sharing:

path = client.diagnostics.export(
    conversation.id,
    path="/lakehouse/default/Files/data-agent-diagnostics.json",
)

In an IDE, pass any local path:

path = client.diagnostics.export(
    conversation.id,
    path="./data-agent-diagnostics.json",
)

Evaluation uses the Responses API by default; existing calls do not need a client_class argument:

from fabric.dataagent.evaluation import evaluate_data_agent

evaluate_data_agent(
    df,
    data_agent_name="my-agent",
)

Responses evaluations keep the same output tables and evaluation ID return value. The thread_id column contains the conversation ID for compatibility with existing notebooks and tables. The thread_url and evaluation_thread_url fields link to the answer and judge responses respectively when response IDs are available. Failures without a deep link remain visible by conversation or evaluation-row ID. Unsuccessful API responses have an unclear evaluation judgement rather than being counted as answer mismatches. JSON file annotations support both tabular columns/rows data and other valid JSON, with bounded text previews for non-tabular content. If local answer processing fails, the row remains failed/unclear while retaining any received response ID, deep link, and tool telemetry.

Management plane API

Use create_data_agent and delete_data_agent to create and delete Data Agent items. Use FabricDataAgentManagement for management-plane APIs. Existing workload-host management methods such as add_datasource() remain available for compatibility and keep their original return types, but emit deprecation warnings with the public API method to use instead. Public API methods use explicit names such as get_settings(), update_settings(), add_staging_datasource(), list_datasources(), delete_staging_datasource(), publish_staging(), and reset_staging().

Change logs

0.1.32a0

• default evaluate_data_agent() to FabricOpenAIResponses instead of the deprecated Assistants API.
• populate answer and judge deep links for Responses evaluations while retaining the existing output column names.
• preserve failed-row notifications and report rendering when a deep link is unavailable, without emitting empty-target links.
• record conversation-creation request failures as failed rows without discarding completed rows, and leave infrastructure failures unscored.
• close both Responses HTTP clients after each evaluation row.
• support non-tabular JSON file annotations and retain response links and telemetry when local answer processing fails.

0.1.31a0

• add required LLM endpoint classification headers to Assistants and Responses API requests.
• add support for retrieving and exporting Responses API conversation diagnostics.

0.1.30a0

• bugfix - final-response proxy drops mapping-backed status and ID attributes.
• add Python 3.13 support.
• simplify package dependencies to avoid unnecessary installations.
• cap the openai dependency to >=1.101.0,<3 because of incompatibility.

0.1.29a0

• require aiohttp>=3.10 because Fabric runtime dependencies use timeout exception types introduced in that version.

0.1.28a0

• bugfix - normalizes non-streamed responses from Open AI.

0.1.27a0

• add support for the Open AI Responses APIs.

0.1.26a0

• add support for the public Data Agent management-plane APIs via FabricDataAgentManagement.

0.1.25a0

• upgrade the model used for fewshots validation from gpt-4.1 to gpt-5.1.

0.1.24a0

• rename SDK configuration parameter enable_experimental_features to enable_preview_runtime for consistency with the UI "Preview Runtime" label.

0.1.23a0

• add FabricOpenAIResponses for opt-in OpenAI Responses API support while keeping FabricOpenAI for Assistants API callers.
• fix duplicate fewshot bug in add_fewshots() by auto-renaming duplicate questions with [N] suffixes (case-insensitive match).
• update evaluation model and correct prompt typos.

0.1.22a0

• upgrade dependency semantic-link-labs=0.14.3 to allow for python 3.12 support.

0.1.21a0

• fix FabricOpenAI "Missing credentials" error with openai>=2.34.0.

0.1.20a0

• add support for enabling/disabling experimental features.

0.1.19a0

• fix data source type for update configurations and descriptions.

0.1.18a0

• adds data source type and element type support for Mirrored DB and SQL DB
• enable Publishing Data Agent to M365 Copilot Agent Store
• update failed thread message

0.1.17a0

• add conflict detection to few-shot validation with LLM-based semantic analysis
• add file support
• replace thread_url with message_url

0.1.16a0

• add the ontology data source support

0.1.15a0

• fix get datasources error caused by None value
• fix schema selection when adding data sources
• update example notebook

0.1.14a0

• fix thread url for fabcon tenant

0.1.13a0

• add support for granular quality feedback in few-shot validation and improve Dataframe output
• fix invalid data type for delta lake

0.1.12a0

• fix python error in the release pipeline
• add robust few-shot validation utilities to SDK with dual LLM support and DataFrame output
• update parameter type in add-datasource

0.1.11a0

• upgrade OneBranch Azure Linux Build Image: Migrating from 2.0 to 3.0
• remove "AISkill" from artifact name list due to invalid item type error in openai
• make Data Agent and Data Source Creation Idempotent
• add publish description
• refactoring the evaluation apis and add code coverage
• remove AISkill artifact type in data agent api

0.1.10a0

• fix get_evaluation_summary_per_question if no question fails

0.1.9a0

• Use correct workspace context in delete_data_agent function.
• Update notebooks with data source notes
• display failed threads and fix percentage

0.1.8a0

• evaluation API enhancements including parallelizing, number of variations and single thread.
• speed-up add_ground_truth_batch and stabilise Kusto tests
• ground-truth generation for Kusto (KQL) datasources

0.1.7a0

• added Warehouse to list of artifact types.
• added Method for Updating Ground Truth before Evaluation.
• made Publish Info Optional.

0.1.6a0

• update sdk to make compatible with both python and spark.

0.1.5a0

• add PySpark support for the evaluation APIs.
• added pipeline for running unit tests.

0.1.4a0

• switch to public apis for artifact management.

0.1.3a0

• add column/table descriptions for sql data sources.
• allow selection of multiple columns at once in the datasource.
• bug fix to address the run_steps response structure change.

0.1.2a0

• bugfix for fabric_openai artifact type - should support "DataAgent".
• bugfix for data source type ("datawarehouse" should be "warehouse").

0.1.1a0

• bugfix for create_data_agent where type should support "DataAgent".

0.1.0a0

• add upload_fewshots for adding multiple fewshots to DataSource.

0.0.4a0

• add evaluation APIs to the SDK

0.0.3a1

• return fewshot id from add_fewshots
• fix the aiskill stage parameter
• return datasource display name in pretty_print
• return thread object for get_or_create_thread API.

0.0.2a0

• rename module
• support Fabric get_or_create_thread to decouple from UX thread

0.0.1a0

Initial alpha release of the package.

• add: data plane client
• add: management plane client