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 public preview. This preview is provided without a service-level agreement, and we don’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.

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
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

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.
• 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	Build (includes Read). Read alone isn’t sufficient because the agent generates model queries that require Build.
  Lakehouse	Read on the lakehouse item (and table access, if enforced).
  Warehouse	Read (SELECT on relevant tables).
  KQL database	Reader role on the database.

  For full details, see Underlying data source permissions.

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

• 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

  Before you run the samples, create a project connection to your Fabric data agent.

  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. In the left pane, select Management center, and then select Connected resources.
  3. Create a connection of type Microsoft Fabric.
  4. Enter the workspace_id and artifact_id values.
  5. Save the connection, and then copy the connection ID.

  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>.

  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.

Code example

• For more information, see Get ready to code.
• Your connection ID should be in the format of /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

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