Creación de un origen de conocimiento de Fabric Data Agent (versión preliminar)

Note

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Importante

Estas características y funcionalidades forman parte de la API REST 2026-05-01-preview. La versión preliminar 2026-05-01-preview se le concede bajo licencia como parte de su suscripción de Azure y está sujeta a los términos aplicables a las "Versiones preliminares" establecidos en los Microsoft Product Terms, el Microsoft Products and Services Data Protection Addendum ("DPA") y los Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

La 2026-05-01-preview admite conexiones a otros servicios de Microsoft y a servicios de terceros. El uso de estos servicios está sujeto a sus respectivos términos y podría dar lugar a procesamiento o almacenamiento de datos fuera del límite de cumplimiento de Azure, así como a los datos que fluyen a los límites de cumplimiento de Azure.

Al conectarse a Fabric IQ, es posible que se produzcan costos y que los datos se envíen fuera del límite de cumplimiento de Azure y se procesen según los términos de servicio y las directivas de control de datos aplicables. Es su responsabilidad gestionar si sus datos saldrán fuera de los límites geográficos y de cumplimiento normativo de su organización, así como cualquier implicación relacionada, y garantizar que se hayan establecido los permisos, límites y aprobaciones adecuados.

Es responsable de revisar y probar cuidadosamente las aplicaciones que compile en el contexto de sus casos de uso específicos y de tomar todas las decisiones y personalizaciones adecuadas. Esto incluye implementar sus propias mitigaciones de IA responsables, como metaprompts, filtros de contenido u otros sistemas de seguridad, y garantizar que las aplicaciones cumplan los estándares de calidad, confiabilidad, seguridad y confiabilidad adecuados. Para obtener más información, consulte la nota de transparencia Búsqueda de Azure AI.

Una fuente de conocimientos de agente de datos de Fabric (versión preliminar) conecta su Agente de datos de Microsoft Fabric a una canalización de recuperación de agentes en Búsqueda de Azure AI. Los orígenes de conocimiento se crean de forma independiente, se hace referencia en una base de conocimiento y se usan como datos de base cuando se consulta la base de conocimiento en tiempo de ejecución.

El agente de datos actúa como analista virtual, generando y ejecutando consultas en los datos de Microsoft Fabric para devolver respuestas, tablas y gráficos en lenguaje natural. Esto hace que las fuentes de conocimientos del agente de datos de Fabric sean útiles para datos con alta rotación y consultas analíticas.

A diferencia de los orígenes de conocimiento indexados, los orígenes de conocimiento del Agente de datos de Fabric consultan datos en vivo directamente en el momento de la recuperación. No se necesita ninguna canalización de ingesta. Las consultas requieren un token de acceso de usuario final, que el motor de recuperación usa para consultar el agente de datos de Fabric en nombre del usuario final.

Soporte para el uso

Azure Portal	Portal de Microsoft Foundry	SDK de .NET	SDK de Python	SDK de Java	SDK de JavaScript	REST API
❌	✔️	✔️	✔️	✔️	✔️	✔️

Prerrequisitos

Un servicio de Búsqueda de Azure AI en cualquier región que proporcione recuperación mediante agentes.
Un área de trabajo de Microsoft Fabric con un agente de datos.
El servicio de búsqueda y el espacio de trabajo deben estar en el mismo inquilino de Microsoft Entra ID.
Permisos para crear orígenes de conocimiento. Configure la autenticación sin clave con el rol Colaborador del servicio de búsqueda asignado a su cuenta de usuario (recomendado) o use una clave de API.

El paquete de versión preliminar Azure.Search.Documents más reciente: dotnet add package Azure.Search.Documents --prerelease

El paquete de versión preliminar azure-search-documents más reciente: pip install --pre azure-search-documents

La versión 2026-05-01-preview de las API REST del servicio de búsqueda.

Gobernanza y cumplimiento de datos

Fabric IQ procesa las solicitudes dentro del límite de cumplimiento de Microsoft Fabric para la región del área de trabajo. Los siguientes compromisos se aplican al enrutar las consultas del agente a través de Fabric IQ.

Ubicación de almacenamiento de datos

Fabric IQ recupera y procesa datos dentro de la región donde reside el área de trabajo de Microsoft Fabric. Los datos no cruzan los límites regionales durante la ejecución de la consulta. La región aplicable y su ámbito de cumplimiento están determinados por la ubicación del área de trabajo. Para obtener la lista de regiones admitidas y los marcos de cumplimiento que satisface cada región, consulte Microsoft Fabric disponibilidad de la región.

Note

Si el servicio Búsqueda de Azure AI está en una región de Azure diferente a la del área de trabajo de Fabric, los resultados de la consulta se devuelven entre regiones. Consulte la disponibilidad regional de Microsoft Fabric y los requisitos de residencia de datos de su organización antes de conectar un área de trabajo de Fabric ubicada en otra región.

Certificaciones de cumplimiento

Fabric IQ hereda las certificaciones de cumplimiento de Microsoft Fabric para la región del área de trabajo. Para obtener documentación de cumplimiento, informes de auditoría y marcos aplicables a cada región, consulte Microsoft Fabric disponibilidad de la región.

Comprobación de orígenes de conocimiento existentes

Un origen de conocimiento es un objeto reutilizable de nivel superior. Conocer los orígenes de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos.

Ejecute el código siguiente para enumerar los orígenes de conocimiento por nombre y tipo.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

Reference:SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

Reference:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

Reference:Knowledge Sources - List

También puede devolver un único origen de conocimiento por nombre para revisar la definición JSON de este.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

Reference:SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

Reference:SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

Referencia:Orígenes de conocimiento - Obtener

El siguiente json es una respuesta de ejemplo para un origen de conocimiento de Fabric Data Agent.

{
  "name": "my-fabric-data-agent-ks",
  "kind": "fabricDataAgent",
  "description": "A Fabric Data Agent knowledge source.",
  "encryptionKey": null,
  "fabricDataAgentParameters": {
    "workspaceId": "00000000-0000-0000-0000-000000000000",
    "dataAgentId": "00000000-0000-0000-0000-000000000001"
  }
}

Creación de un origen de conocimiento

Ejecute el código siguiente para crear un origen de conocimiento de Fabric Data Agent.

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

Uri searchEndpoint = new Uri("<search-service-url>");
AzureKeyCredential credential = new AzureKeyCredential("<api-key>");
var indexClient = new SearchIndexClient(searchEndpoint, credential);

var fabricDataAgent = new FabricDataAgentKnowledgeSource(
    "<knowledge-source-name>",
    new FabricDataAgentKnowledgeSourceParameters("<fabric-workspace-id>", "<fabric-data-agent-id>"))
{
    Description = "A Fabric Data Agent knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(fabricDataAgent);

Reference:SearchIndexClient

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    FabricDataAgentKnowledgeSource,
    FabricDataAgentKnowledgeSourceParameters,
)

index_client = SearchIndexClient(
    endpoint="<search-service-url>",
    credential=AzureKeyCredential("<api-key>")
)

knowledge_source = FabricDataAgentKnowledgeSource(
    name="<knowledge-source-name>",
    description="A Fabric Data Agent knowledge source.",
    fabric_data_agent_parameters=FabricDataAgentKnowledgeSourceParameters(
        workspace_id="<fabric-workspace-id>",
        data_agent_id="<fabric-data-agent-id>"
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)

Reference:SearchIndexClient

### Create a Fabric Data Agent knowledge source
PUT {{search-url}}/knowledgesources/my-fabric-data-agent-ks?api-version=2026-05-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "my-fabric-data-agent-ks",
  "kind": "fabricDataAgent",
  "description": "A Fabric Data Agent knowledge source.",
  "fabricDataAgentParameters": {
    "workspaceId": "{fabric-workspace-id}",
    "dataAgentId": "{fabric-data-agent-id}"
  }
}

Referencia:Orígenes de conocimiento: crear o actualizar

Asignar a una base de conocimiento

Si está satisfecho con el origen de conocimiento, agréguelo a una base de conocimiento.

Importante

Las fuentes de conocimientos del agente de datos de Fabric no admiten el minimalesfuerzo de razonamiento de recuperación. Use low o medium en su lugar.

Consulta de una base de conocimiento

Una vez configurada la base de conocimiento, llame a la acción de recuperación o al extremo de MCP para consultar el contenido de Fabric Data Agent. Esta fuente de conocimientos tiene características únicas de respuesta y cumplimiento de permisos en tiempo de consulta.

Aplicar autorizaciones en el momento de la consulta

Las fuentes de conocimientos del agente de datos de Fabric utilizan un flujo de tokens en nombre de (OBO). El token de acceso del usuario final se pasa en el encabezado de x-ms-query-source-authorization en la solicitud de recuperación. El token debe estar limitado a la audiencia de Búsqueda de Azure AI (https://search.azure.com/.default). El motor de recuperación intercambia este token por un token con ámbito de Microsoft Fabric y lo usa para consultar el agente de datos de Fabric en nombre del usuario final.

También se requiere la autenticación Búsqueda de Azure AI estándar en la solicitud de recuperación. El x-ms-query-source-authorization token se pasa por separado y no reemplaza la autenticación del servicio.

Para obtener instrucciones sobre cómo pasar el token, consulte Aplicar permisos en tiempo de consulta (versión preliminar).

Campos de respuesta específicos de Fabric Data Agent

Las fuentes de conocimientos del agente de datos de Fabric devuelven resultados en el objeto sourceData de cada entrada references y los diagnósticos de consulta en la matriz activity. sourceData Contiene:

fabricAnswer: respuesta en lenguaje natural del agente de datos.
fabricEmbeddedResources: cualquier recurso incrustado, como tablas y gráficos, cuando la consulta genera resultados estructurados.

En el ejemplo siguiente se muestra una respuesta de recuperación que contiene una referencia de origen de conocimiento de Fabric Data Agent y su registro de actividad correspondiente. Para obtener instrucciones más amplias sobre cómo interpretar las respuestas de recuperación, consulte Revisión de la respuesta.

Tip

Para recibir sourceData para referencias, establezca includeReferenceSourceData en true en la entrada de la fuente de conocimientos dentro de knowledgeSourceParams en la solicitud de recuperación.

{
  "response": [
      // ... Response omitted for brevity
  ],
  "activity": [
    {
      "type": "fabricDataAgent",
      "id": 1,
      "knowledgeSourceName": "my-fabric-data-agent-ks",
      "queryTime": "2026-05-11T19:37:11.600Z",
      "count": 1,
      "fabricDataAgentArguments": {
        "search": "my query"
      }
    },
    {
      // ... Additional activity records omitted for brevity 
    }
  ],
  "references": [
    {
      "type": "fabricDataAgent",
      "id": "0",
      "activitySource": 1,
      "rerankerScore": 2.57,
      "workspaceId": "00000000-0000-0000-0000-000000000000",
      "dataAgentId": "00000000-0000-0000-0000-000000000001",
      "sourceData": {
        "fabricAnswer": "There were 47 airline delays in Q1 2026. The majority occurred on transcontinental routes.",
        "fabricEmbeddedResources": [
          {
            "title": "Q1 2026 Airline Operations Report",
            "mimeType": "text/csv",
            "content": "Route | Delays | Avg. Delay (min)\n--- | --- | ---\nJFK–LAX | 18 | 42\nORD–MIA | 12 | 31"
          }
        ]
      }
    },
    {
      // ... Additional references omitted for brevity 
    }
  ]
}

Eliminación de un origen de conocimiento

Para poder eliminar un origen de conocimiento, debe eliminar cualquier base de conocimiento que haga referencia a ella o actualizar la definición de la base de conocimiento para quitar la referencia. En el caso de los orígenes de conocimiento que generan una canalización de índice e indexador, también se eliminan todos los objetos generados . Sin embargo, si usó un índice existente para crear un origen de conocimiento, el índice no se eliminará.

Si intenta eliminar un origen de conocimiento que está en uso, se produce un error en la acción y devuelve una lista de bases de conocimiento afectadas.

Para eliminar un origen de conocimiento:

Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeBases = indexClient.GetKnowledgeBasesAsync();

Console.WriteLine("Knowledge Bases:");

await foreach (var kb in knowledgeBases)
{
    Console.WriteLine($"  - {kb.Name}");
}

Reference:SearchIndexClient

Una respuesta de ejemplo podría ser similar a la siguiente:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

Reference:SearchIndexClient

Una respuesta de ejemplo podría ser similar a la siguiente:

 {
   "Name": "earth-knowledge-base",
   "KnowledgeSources": [
     {
       "Name": "earth-knowledge-source"
     }
   ],
   "Models": [
     {}
   ],
   "RetrievalReasoningEffort": {},
   "OutputMode": {},
   "ETag": "\u00220x8DE278629D782B3\u0022",
   "EncryptionKey": null,
   "Description": null,
   "RetrievalInstructions": null,
   "AnswerInstructions": null
 }

Elimine la base de conocimiento o, si tiene varios orígenes de conocimiento, actualice la base de conocimiento para quitar el origen. En este ejemplo se muestra la eliminación.

using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

Reference:SearchIndexClient

Elimine el origen de conocimiento.

await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");

Reference:SearchIndexClient

Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

# Get knowledge bases
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

print("Knowledge Bases:")
for kb in index_client.list_knowledge_bases():
    print(f"  - {kb.name}")

Reference:SearchIndexClient

Una respuesta de ejemplo podría ser similar a la siguiente:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

# Get a knowledge base definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
kb = index_client.get_knowledge_base("knowledge_base_name")
print(kb)

Reference:SearchIndexClient

Una respuesta de ejemplo podría ser similar a la siguiente:

 {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks"
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

Elimine la base de conocimiento o, si tiene varios orígenes de conocimiento, actualice la base de conocimiento para quitar el origen. En este ejemplo se muestra la eliminación.

# Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

Reference:SearchIndexClient

Elimine el origen de conocimiento.

# Delete a knowledge source
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_source("knowledge_source_name")
print(f"Knowledge source deleted successfully.")

Reference:SearchIndexClient

Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

### Get knowledge bases
GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
Authorization: Bearer {{token}}

Reference:Knowledge Bases - List

Una respuesta de ejemplo podría ser similar a la siguiente:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

### Get a knowledge base definition
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

Reference:Bases de Conocimiento - Obtener

Una respuesta de ejemplo podría ser similar a la siguiente:

 {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks"
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

Elimine la base de conocimiento o, si tiene varios orígenes de conocimiento, actualice la base de conocimiento para quitar el origen. En este ejemplo se muestra la eliminación.
```
### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}
```
Referencia:Bases de Conocimiento - Eliminar

Elimine el origen de conocimiento.

### Delete a knowledge source
DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

Referencia:Orígenes de conocimiento: Eliminar

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-06-30

Creación de un origen de conocimiento de Fabric Data Agent (versión preliminar)

Soporte para el uso

Prerrequisitos

Gobernanza y cumplimiento de datos

Ubicación de almacenamiento de datos

Certificaciones de cumplimiento

Comprobación de orígenes de conocimiento existentes

Creación de un origen de conocimiento

Asignar a una base de conocimiento

Consulta de una base de conocimiento

Aplicar autorizaciones en el momento de la consulta

Campos de respuesta específicos de Fabric Data Agent

Eliminación de un origen de conocimiento

Contenido relacionado

Comentarios

Recursos adicionales