Compartir a través de

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

Los agentes de Microsoft Copilot Studio aportan funcionalidades con tecnología de inteligencia artificial a las aplicaciones de código. En este artículo se muestra cómo agregar el conector de Microsoft Copilot Studio a la aplicación de código e invocar agentes para procesar la entrada del usuario y devolver respuestas inteligentes.

Prerrequisitos

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

Para conectar la aplicación de código a un agente de Copilot Studio, necesita una conexión de Microsoft Copilot Studio en 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 pac connection list comando :

pac connection list

Busque una conexión con el identificador /providers/Microsoft.PowerApps/apis/shared_microsoftcopilotstudiode API y copie el connectionId 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 connectionId.

Adición del conector de Microsoft Copilot Studio

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

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

Este comando se ejecuta automáticamente.

  • Actualiza el power.config.json archivo con el origen de datos de Copilot Studio
  • Genera archivos de servicio y modelo de TypeScript en la src/generated 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. Abre tu agente en Copilot Studio
  2. Seleccione Publicar para publicar el agente.

Consigue el nombre de tu agente

  1. En Copilot Studio, vaya a Canales.
  2. Seleccione Aplicación web.
  3. Vea la cadena de conexión para encontrar 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:cr3e1_customerSupportAgent

Sugerencia

Copie el nombre del agente exactamente como aparece en la dirección URL. Los nombres de agente distinguen mayúsculas de minúsculas y normalmente incluyen un prefijo de publicador.

Invocación de un agente de Copilot Studio

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

Uso de la ExecuteCopilotAsyncV2 acción

Use la ExecuteCopilotAsyncV2 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 de Microsoft Copilot Studio.

Ruta de acceso de API:/proactivecopilot/executeAsyncV2

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 ExecuteCopilotAsyncV2 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 ExecuteCopilotAsyncV2 método acepta los parámetros siguientes:

Parámetro Obligatorio Tipo Description
message Sí cuerda / cadena El aviso o datos que se van a enviar al agente. Puede ser una cadena JSON para datos estructurados.
notificationUrl Sí cuerda / cadena URL del marcador de posición (use "https://notificationurlplaceholder"). La API requiere esta dirección URL, pero no la usa en modo sincrónico.
agentName Sí cuerda / cadena Nombre del agente de Copilot Studio publicado.

Estructura de la respuesta

La respuesta contiene las siguientes propiedades:

Propiedad Tipo Description
responses string[] Matriz de cadenas de respuesta del agente
conversationId string Identificador de conversación para el seguimiento
lastResponse string La respuesta más reciente del agente
completed boolean Si el agente finalizó el procesamiento

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 a un agente de Copilot Studio o invocarlo, las siguientes soluciones abordan los problemas más comunes.

El agente no devuelve una respuesta

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

  • ExecuteCopilot (/execute) - Solo devuelve ConversationId, no la respuesta (fire-and-forget).
  • ExecuteCopilotAsync (/executeAsync) - 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. Publicó 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

  • Last updated on