Use the Microsoft Fabric data agent with Foundry agents

Learn how to connect a Microsoft Fabric data agent to Foundry Agent Service so your agent can analyze enterprise data by using identity passthrough.

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

See best practices for information on optimizing tool usage.

Use the Microsoft Fabric data agent with Foundry Agent Service to analyze enterprise data in chat. The Fabric data agent turns enterprise data into a conversational question and answer experience.

First, build and publish a Fabric data agent. Then, connect your Fabric data agent with the published endpoint. When a user sends a query, the agent determines if it should use the Fabric data agent. If so, it uses the end user’s identity to generate queries over data they have access to. Lastly, the agent generates responses based on queries returned from the Fabric data agent. By using identity passthrough (On-Behalf-Of) authorization, this integration simplifies access to enterprise data in Fabric while maintaining robust security, ensuring proper access control and enterprise-grade protection.

Prerequisites

• The model you select during agent setup is only used for orchestration and response generation. It doesn’t affect which model the Fabric data agent uses for NL2SQL.
• To help your agent invoke the Fabric tool reliably, include clear tool guidance in your agent instructions (for example, “For customer and product sales data, use the Fabric tool”). You can also force tool use with tool_choice.

• Create and publish a Fabric data agent.
• Use a paid F2 or higher Fabric capacity, or a Power BI Premium P1 or higher capacity with Microsoft Fabric enabled.
• Configure cross-geo processing and storage tenant settings for Fabric data agents if your deployment requires them.
• Assign developers and end users at least the Foundry User Azure RBAC role. For more information, see Azure role-based access control in Foundry.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

• Give developers and end users at least READ access to the Fabric data agent. Users also need the minimum permission on each underlying data source:

  Data source	Minimum permission
  Power BI semantic model	Read. Row-level security and column-level security continue to apply.
  Lakehouse	Read on the lakehouse item (and table access, if enforced).
  Warehouse	Read (SELECT on relevant tables).
  KQL database	Reader role on the database.
  Mirrored database	Read access to the mirrored database and its selected data.
  Ontology	Read access to the ontology and its bound data sources.
  Microsoft Graph	Delegated access to the Microsoft 365 content requested by the signed-in user.

  For full details, see Underlying data source permissions.

• Ensure your Fabric data agent and Foundry project are in the same tenant.

• Keep the data agent and its data sources on capacities in the same region. The data agent can’t execute a query when a data source’s workspace capacity is in a different region.

• Use user identity authentication. Service principal authentication isn’t supported for the Fabric data agent.

• Get these values before you run the samples:

  • Your Foundry project endpoint: FOUNDRY_PROJECT_ENDPOINT.
  • Your model deployment name: FOUNDRY_MODEL_DEPLOYMENT_NAME.
  • Your Fabric connection ID (project connection ID): FABRIC_PROJECT_CONNECTION_ID.

• For the REST sample, also set:

  • AGENT_TOKEN (a bearer token). You can get a temporary token with Azure CLI:

    az account get-access-token --scope https://ai.azure.com/.default
    

Set up the Microsoft Fabric connection

In the Foundry portal, add the Microsoft Fabric data agent tool to your agent. You don’t need to create the connection separately in the management center. When you add the tool, Foundry prompts you for the Fabric data agent information and creates the project connection.

1. In Microsoft Fabric, open your data agent.
2. Copy the workspace_id and artifact_id values from the URL.

The URL path looks similar to .../groups/<workspace_id>/aiskills/<artifact_id>.... Both values are GUIDs.

1. In the Foundry portal, open your project.
2. Create or open an agent, and then add the Microsoft Fabric data agent tool.
3. Enter the workspace_id and artifact_id values.
4. Complete the tool setup. Foundry creates the project connection.
5. Copy the connection ID from the tool configuration.

Use the connection ID as the value for FABRIC_PROJECT_CONNECTION_ID. The value looks like: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<foundryAccountName>/projects/<foundryProjectName>/connections/<connectionName>.

Create the connection with the REST API

To automate connection creation, send an Azure Resource Manager PUT request. The caller needs the Microsoft.CognitiveServices/accounts/projects/connections/write permission on the Foundry project.

Get an Azure Resource Manager access token:

  az account get-access-token \
    --resource https://management.azure.com/ \
    --query accessToken \
    --output tsv

Use the token to create the project connection:

  PUT https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<foundry-account-name>/projects/<foundry-project-name>/connections/<connection-name>?api-version=2025-04-01-preview
  Authorization: Bearer <access-token>
  Content-Type: application/json

  {
    "properties": {
      "category": "CustomKeys",
      "authType": "CustomKeys",
      "credentials": {
        "keys": {
          "workspace_id": "<fabric-workspace-id>",
          "artifact_id": "<fabric-data-agent-id>"
        }
      }
    }
  }

The response id property is the project connection ID. Use this value for FABRIC_PROJECT_CONNECTION_ID in the agent samples.

Identity passthrough and access control

This integration uses identity passthrough (On-Behalf-Of). The Fabric tool runs queries by using the identity of the signed-in user.

• Give each end user access to the Fabric data agent and its underlying data sources, or the tool call fails.
• Use user identity authentication. Service principal authentication isn’t supported for the Fabric data agent.
• For more information about how agent identity works, see Agent identity.

Usage support

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Create an agent with the Microsoft Fabric tool

Troubleshooting

Issue	Cause	Resolution
Artifact Id should not be empty and needs to be a valid GUID.	Fabric connection created with invalid workspace_id or artifact_id	Recreate the Fabric connection. Copy workspace_id and artifact_id from the data agent URL path .../groups/<workspace_id>/aiskills/<artifact_id>....
Can't add messages to thread_... while a run ... is active.	A run is still active for the thread	Start a new conversation or wait for the active run to finish, then try again.
unauthorized	End user lacks access to the Fabric data agent or its underlying data sources	Grant the end user access in Fabric, and confirm you’re using user identity authentication.
Cannot find the requested item or configuration not found	Fabric data agent isn’t published or its configuration changed	Publish the Fabric data agent and confirm it’s active and its data sources are valid.
Connection timeout errors	Network latency or Fabric service delays	Increase timeout settings in your client configuration. Consider implementing retry logic with exponential backoff.
Data query returns empty results	Query doesn’t match available data	Verify the data sources in the Fabric data agent contain the expected data. Test queries directly in Fabric first.
Invalid workspace ID format	Workspace ID isn’t a valid GUID	Copy the exact workspace GUID from the Fabric URL or portal. Don’t modify the ID format.
Agent doesn’t use the Fabric tool	Tool not properly configured or prompt doesn’t trigger it	Verify the Fabric tool is enabled in the agent definition. Update the prompt to reference data that requires Fabric access.

Next steps

Tool use best practices

Agent identity

Get started with the SDK