Consumir um agente de dados Fabric com o SDK do cliente Python (versão prévia)

Este artigo mostra como usar o SDK do cliente Python para adicionar um agente de dados Fabric a aplicativos Web e outros clientes usando a autenticação interativa do navegador. Você entra por meio de um navegador com suas credenciais de Microsoft Entra ID e o agente de dados é executado com suas permissões. Ao adicionar o agente de dados a aplicativos externos, você pode criar interfaces personalizadas, inserir insights em fluxos de trabalho existentes, automatizar relatórios e permitir que os usuários executem consultas de dados de linguagem natural. Essa abordagem oferece recursos de agente de dados enquanto você mantém controle total da experiência do usuário e da arquitetura do aplicativo.

Importante

O código deste documento e do repositório External Client do Fabric Data Agent usam a API Assistants da OpenAI (beta.assistants, beta.threads, beta.threads.runs), que a OpenAI descontinuou, com encerramento previsto para 26 de agosto de 2026. O código atual continua funcionando até 26 de agosto de 2026, mas planeja migrar para o ponto de extremidade MCP antes dessa data.

Importante

Quando você usa Python SDK do cliente para adicionar um agente de dados Fabric a aplicativos Web ou outros clientes, as respostas retornadas por Fabric agentes de dados podem ser enviadas fora do limite de conformidade ou da região geográfica do Fabric. O aplicativo Web aplicável ou as políticas de gerenciamento de dados e termos do cliente regem como essas respostas são processadas e armazenadas.

Pré-requisitos

Configurar seu ambiente no VS Code

  1. Faça o clone ou baixe o repositório Fabric Data Agent External Client. Em seguida, abra-o no VS Code e execute o cliente de exemplo.

  2. Crie e ative um ambiente virtual Python (recomendado) e instale as dependências necessárias.

    python -m venv .venv

  3. Ative o ambiente virtual.

    .venv\Scripts\activate

Instalar dependências

Execute o seguinte comando para instalar dependências:

pip install -r requirements.txt

Observação

  • O pacote azure-identity incluído no requirements.txt permite que você se autentique com Microsoft Entra ID.
  • InteractiveBrowserCredential do pacote azure-identity abre um navegador para que você possa fazer login com uma conta do Microsoft Entra ID. Use-o para desenvolvimento local ou aplicativos que permitem a entrada interativa.

Configurar o cliente

Escolha um desses métodos para definir os valores necessários (TENANT_ID e DATA_AGENT_URL):

Defina os valores no seu shell. Substitua o texto do espaço reservado em colchetes angulares por seus próprios valores.

export TENANT_ID=<your-azure-tenant-id>
export DATA_AGENT_URL=<your-fabric-data-agent-url>

Consulte a documentação para localizar a URL do agente de dados publicado. Siga as instruções para localizar a ID do locatário.

Authenticate

Use a classe InteractiveBrowserCredential para autenticar com Microsoft Entra ID em um navegador.

from azure.identity import InteractiveBrowserCredential
from fabric_data_agent_client import FabricDataAgentClient
credential = InteractiveBrowserCredential()

Criar o cliente do agente de dados

client = FabricDataAgentClient(credential=credential)

Observação

  • O pacote fabric-data-agent-client fornece o SDK do cliente para se conectar ao agente de dados Fabric.
  • O cliente Python usa a autenticação interativa do navegador: quando você executa o script, o navegador padrão é aberto para que você entre no locatário que hospeda o agente de dados Fabric.

Faça uma pergunta ao agente de dados

Depois de autenticar, interaja com o agente de dados usando o cliente Python.

response = client.ask("What were the total sales last quarter?")
print(f"Response: {response}")

O client.ask método envia sua pergunta ao agente de dados e retorna um objeto com a resposta. Você pode exibir as etapas executadas pelo agente de dados e as consultas correspondentes geradas para obter a resposta.

run_details = client.get_run_details("What were the total sales last quarter?")
messages = run_details.get('messages', {}).get('data', [])
assistant_messages = [msg for msg in messages if msg.get('role') == 'assistant']

print("Answer:", assistant_messages[-1])

Opcional: inspecione as etapas e a consulta correspondente

Inspecione as etapas que o agente de dados tomou para chegar à resposta, incluindo erros durante a execução.

for step in run_details['run_steps']['data']:
        tool_name = "N/A"
        if 'step_details' in step and step['step_details'] and 'tool_calls' in step['step_details']:
            tool_calls = step['step_details']['tool_calls']
            if tool_calls and len(tool_calls) > 0 and 'function' in tool_calls[0]:
                tool_name = tool_calls[0]['function'].get('name', 'N/A')
        print(f"Step ID: {step.get('id')}, Type: {step.get('type')}, Status: {step.get('status')}, Tool Name: {tool_name}")
        if 'error' in step:
            print(f"  Error: {step['error']}")

Essa saída ajuda você a entender como o agente produziu sua resposta e fornece transparência quando você trabalha com seus dados no cliente Python.

Conteúdo relacionado

  • Last updated on