Metadata-Version: 2.4
Name: fabric-data-agent-sdk
Version: 0.1.31a0
Summary: SDK for the Fabric Data Agent Library
Author: Microsoft Corporation
License-Expression: MIT
Project-URL: Repository, https://msdata.visualstudio.com/DefaultCollection/A365/_git/SynapseML-Agent-SDK
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: semantic-link-sempy>=0.14.1
Requires-Dist: openai<3,>=1.101.0
Requires-Dist: httpx==0.27.2
Requires-Dist: semantic-link-labs<0.18,>=0.15.2
Requires-Dist: azure-kusto-data>=4.5.0
Requires-Dist: azure-identity==1.17.1
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: markdown2==2.5.3
Requires-Dist: tabulate>=0.9.0
Dynamic: license-file

The Fabric Data Agent SDK supports programmatic access for [Fabric Data Agent](https://learn.microsoft.com/en-us/fabric/data-science/concept-ai-skill) artifacts.

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

# Getting started

## Prerequisites

* A [Microsoft Fabric subscription](https://learn.microsoft.com/en-us/fabric/enterprise/licenses). Or sign up for a free [Microsoft Fabric (Preview) trial](https://learn.microsoft.com/en-us/fabric/get-started/fabric-trial).
* Sign in to [Microsoft Fabric](https://fabric.microsoft.com/).
* Create [a new notebook](https://learn.microsoft.com/en-us/fabric/data-engineering/how-to-use-notebook#create-notebooks) or a new [spark job](https://learn.microsoft.com/en-us/fabric/data-engineering/create-spark-job-definition) 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:

  ```python
  %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

Existing Assistants API users can continue using `FabricOpenAI`. To migrate to
the Responses API, opt in with `FabricOpenAIResponses`:

```python
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:

```python
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`:

```python
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:

```python
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:

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

In an IDE, pass any local path:

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

For evaluation, keep the default Assistants path or pass the Responses client
explicitly:

```python
from fabric.dataagent.client import FabricOpenAIResponses
from fabric.dataagent.evaluation import evaluate_data_agent

evaluate_data_agent(
    df,
    data_agent_name="my-agent",
    client_class=FabricOpenAIResponses,
)
```
## 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.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
