Cómo conectar tu aplicación de código con agentes de Microsoft Copilot Studio

Agentes de Microsoft Copilot Studio llevan capacidades impulsadas por inteligencia artificial a tus aplicaciones de código. En este artículo se muestra cómo agregar el conector Microsoft Copilot Studio a la aplicación de código e invocar agentes para procesar la entrada del usuario y devolver respuestas inteligentes.

Prerrequisitos

• Un proyecto de aplicación de código inicializado
• Un agente de Microsoft Copilot Studio publicado en tu entorno
• Conocimientos básicos sobre cómo conectar aplicaciones de código a datos

Asegúrese de que tiene una conexión de Microsoft Copilot Studio

Para conectar su aplicación de código a un agente de Copilot Studio, necesita una conexión de Microsoft Copilot Studio dentro de su entorno. Compruebe si ya existe o cree uno nuevo.

Comprobación de las conexiones existentes

Para ver si ya tiene una conexión de Microsoft Copilot Studio mediante el comando pac connection list :

pac connection list

Busque una conexión con el identificador de API y copie el valor.

Crear una nueva conexión

Si no tiene una conexión existente, debe crear una a través de la interfaz de usuario del portal de Power Apps maker. Siga las instrucciones de cómo conectar aplicaciones de código a datos y asegúrese de copiar el .

Adición del conector de Microsoft Copilot Studio

Después de crear una conexión de Microsoft Copilot Studio, use el comando PAC CLI pac code add-data-source para agregar a su aplicación de código:

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

Este comando se ejecuta automáticamente.

• Actualiza tu archivo power.config.json con el origen de datos de Copilot Studio
• Genera archivos de servicio y modelo de TypeScript en la carpeta

Publicar y obtener el nombre del agente

Para poder invocar un agente desde la aplicación de código, debe publicarlo y obtener su nombre.

Publicar su agente

1. Abra el agente en Copilot Studio
2. Seleccione Publicar para publicar el agente.

Consigue el nombre de tu agente

1. En Copilot Studio, vaya a Channels.
2. Seleccione Aplicación web.
3. Vea la cadena de conexión para obtener el nombre del agente.

El formato de URL es:

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

Nombre del agente de ejemplo:

Invocación de un agente de Copilot Studio

Con el conector agregado, puede llamar a un agente de Copilot Studio desde su aplicación de desarrollo. Los pasos siguientes muestran cómo importar el servicio generado, enviar un mensaje al agente y controlar su respuesta.

Uso de la acción

Use la acción para invocar agentes desde aplicaciones de código. Esta acción devuelve las respuestas del agente de forma sincrónica. Es la acción Ejecutar Agente y esperar incluida con el conector Microsoft Copilot Studio.

Ruta de acceso de API:

Importación del servicio generado

Después de agregar el origen de datos, importe el servicio TypeScript generado:

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

Enviar un mensaje al agente

Use el método para enviar un mensaje y esperar la respuesta del agente:

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

Parámetros de solicitud

El método acepta los parámetros siguientes:

Estructura de la respuesta

La respuesta contiene las siguientes propiedades:

Ejemplo: Obtención de la respuesta del 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);
}

Ejemplo: Análisis de respuestas JSON

Los agentes suelen devolver respuestas como cadenas JSON. Analice las respuestas para extraer datos 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);
}

Solución de problemas

Si tiene problemas para conectarse o invocar un agente de Copilot Studio, las siguientes soluciones abordan los problemas más comunes.

El agente no devuelve una respuesta

Solución: Asegúrese de que usa la operación (). Otros puntos de conexión tienen limitaciones conocidas:

• () - Solo devuelve , no la respuesta (fire-and-forget).
• () - Podría devolver errores 502 "No se puede leer la respuesta del servidor".

Errores de mayúsculas y minúsculas en las propiedades de la respuesta

Solución: La capitalización de las propiedades de respuesta puede variar entre implementaciones. Busque todas las variaciones:

• conversationId
• ConversationId
• conversationID

Utilice el encadenamiento opcional o compruebe si hay varias variaciones de mayúsculas.

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

El agente devuelve respuestas vacías o inesperadas

Solución: Compruebe que:

1. Ha publicado su agente en Copilot Studio.
2. El nombre del agente es correcto y coincide con el agente publicado.
3. El formato del mensaje coincide con lo que espera el agente.
4. El agente tiene temas configurados para gestionar la entrada.

Consulte también

• Conecta tu aplicación de código a los datos
• documentación de Microsoft Copilot Studio
• Referencia de conectores de Power Platform