Como fazer: Conectar seu aplicativo de software aos agentes do Microsoft Copilot Studio

Microsoft Copilot Studio agentes trazem recursos de IA para seus aplicativos de código. Este artigo mostra como adicionar o conector Microsoft Copilot Studio ao aplicativo de código e invocar agentes para processar a entrada do usuário e retornar respostas inteligentes.

Pré-requisitos

• Um projeto de aplicativo de código inicializado
• Um agente de Microsoft Copilot Studio publicado em seu ambiente
• Compreensão básica de como conectar aplicativos de código a dados

Verifique se você tem uma conexão Microsoft Copilot Studio

Para conectar seu aplicativo de código a um agente do Copilot Studio, você precisa de uma conexão Microsoft Copilot Studio em seu ambiente. Verifique se já existe um ou crie um novo.

Verificar se há conexões existentes

Para ver se você já tem uma conexão Microsoft Copilot Studio usando o comando pac connection list:

pac connection list

Procure uma conexão com o ID da API /providers/Microsoft.PowerApps/apis/shared_microsoftcopilotstudio e copie o valor connectionId.

Criar uma nova conexão

Se você não tiver uma conexão existente, deverá criar uma por meio da interface do usuário do portal do criador de Power Apps. Siga as instruções sobre como conectar aplicativos de código aos dados e garanta que você copie o connectionId.

Adicionar conector Microsoft Copilot Studio

Depois de criar uma conexão Microsoft Copilot Studio, use o comando PAC CLI pac code add-data-source para adicioná-la ao seu aplicativo de código:

pac code add-data-source -a "shared_microsoftcopilotstudio" -c <connectionId>

Este comando é automaticamente:

• Atualiza o arquivo power.config.json com a fonte de dados do Copilot Studio
• Gera arquivos de modelo e de serviço typeScript na src/generated pasta

Publicar e obter o nome do seu agente

Antes de invocar um agente do seu aplicativo de código, você precisa publicá-lo e obter seu nome.

Publicar seu agente

1. Abra seu agente no Copilot Studio
2. Selecione Publicar para publicar seu agente

Obter o nome do agente

1. No Copilot Studio, vá para Channels.
2. Selecione o aplicativo Web.
3. Verifique o connection string para localizar o nome do agente.

O formato do URL é:

https://{id}.environment.api.powerplatform.com/copilotstudio/dataverse-backed/authenticated/bots/{agentName}/conversations?api-version=2022-03-01-preview

Nome do agente de exemplo:cr3e1_customerSupportAgent

Dica

Copie o nome do agente exatamente como ele aparece na URL. Os nomes de agente diferenciam maiúsculas de minúsculas e normalmente incluem um prefixo do editor.

Invocar um agente do Copilot Studio

Com o conector adicionado, você pode chamar um agente do Copilot Studio do seu aplicativo de código. As etapas a seguir mostram como importar o serviço gerado, enviar uma mensagem para o agente e lidar com sua resposta.

Usar a ação ExecuteCopilotAsyncV2

Use a ação ExecuteCopilotAsyncV2 para invocar agentes de aplicativos de código. Essa ação retorna as respostas do agente de forma síncrona. É a ação Execute Agent e espere incluída no conector Microsoft Copilot Studio.

Caminho da API:/proactivecopilot/executeAsyncV2

Importar o serviço gerado

Depois de adicionar a fonte de dados, importe o serviço TypeScript gerado:

import { CopilotStudioService } from './generated/services/CopilotStudioService';

Enviar uma mensagem para o agente

Use o ExecuteCopilotAsyncV2 método para enviar uma mensagem e aguardar a resposta do agente:

const response = await CopilotStudioService.ExecuteCopilotAsyncV2({
  message: "What is the status of my order?",
  notificationUrl: "https://notificationurlplaceholder",
  agentName: "cr3e1_customerSupportAgent"
});

Parâmetros de solicitação

O ExecuteCopilotAsyncV2 método aceita os seguintes parâmetros:

Parâmetro	Obrigatório	Tipo	DESCRIÇÃO
message	Yes	cadeia	O prompt ou os dados a serem enviados ao agente. Pode ser uma cadeia de caracteres JSON para dados estruturados.
notificationUrl	Yes	cadeia	URL do marcador de posição (use "https://notificationurlplaceholder"). A API requer essa URL, mas não a usa no modo síncrono.
agentName	Yes	cadeia	O nome do agente do Copilot Studio publicado.

Estrutura de resposta

A resposta contém as seguintes propriedades:

Propriedade	Tipo	DESCRIÇÃO
responses	string[]	Matriz de cadeias de caracteres de resposta do agente
conversationId	string	A ID da conversa para acompanhamento
lastResponse	string	A resposta mais recente do agente
completed	boolean	Se o agente terminou o processamento

Exemplo: Obter resposta do agente

const response = await CopilotStudioService.ExecuteCopilotAsyncV2({
  message: "Summarize the latest product trends",
  notificationUrl: "https://notificationurlplaceholder",
  agentName: "cr3e1_trendAnalyzer"
});

if (response.data.completed) {
  const agentResponse = response.data.lastResponse;
  console.log("Agent response:", agentResponse);
}

Exemplo: analisar respostas JSON

Os agentes geralmente retornam respostas como cadeias de caracteres JSON. Analise as respostas para extrair dados específicos:

const response = await CopilotStudioService.ExecuteCopilotAsyncV2({
  message: JSON.stringify({ query: "monthly sales" }),
  notificationUrl: "https://notificationurlplaceholder",
  agentName: "cr3e1_dataAnalyzer"
});

if (response.data.responses && response.data.responses.length > 0) {
  // Parse the JSON response
  const parsedData = JSON.parse(response.data.responses[0]);
  const summary = parsedData.summary;
  const metrics = parsedData.metrics;

  console.log("Summary:", summary);
  console.log("Metrics:", metrics);
}

Resolução de problemas

Se você encontrar problemas de conexão ou invocação de um agente do Copilot Studio, as soluções a seguir resolverão os problemas mais comuns.

O agente não retorna uma resposta

Solução: Verifique se você está usando a ExecuteCopilotAsyncV2 operação (/proactivecopilot/executeAsyncV2). Outros pontos de extremidade têm limitações conhecidas:

• ExecuteCopilot (/execute) - Retorna apenas ConversationId, não a resposta (executar e esquecer).
• ExecuteCopilotAsync (/executeAsync) - Pode retornar 502 erros de "Não é possível ler resposta do servidor".

Erros de uso de maiúsculas da propriedade na resposta

Solução: O uso de maiúsculas nas propriedades de resposta pode variar entre implementações. Verifique todas as variações:

• conversationId
• ConversationId
• conversationID

Use o encadeamento opcional ou verifique se há várias variações de maiúsculas.

const convId = response.data.conversationId ??
               response.data.ConversationId ??
               response.data.conversationID;

O agente retorna respostas vazias ou inesperadas

Solução: Verifique se:

1. Você publicou seu agente no Copilot Studio.
2. O nome do agente está correto e corresponde ao agente publicado.
3. O formato da mensagem corresponde ao que seu agente espera.
4. Seu agente tem tópicos configurados para lidar com a entrada.

Consulte também

• Conectar seu aplicativo de código aos dados
• Microsoft Copilot Studio documentação
• Referência de conectores do Power Platform