Guide pratique pour connecter votre application de code aux agents Microsoft Copilot Studio

Les agents Microsoft Copilot Studio apportent des fonctionnalités basées sur l’IA à vos applications de code. Cet article explique comment ajouter le connecteur Microsoft Copilot Studio à votre application de code et appeler des agents pour traiter les entrées utilisateur et retourner des réponses intelligentes.

Prerequisites

• Un projet d’application de code initialisé
• Un agent Microsoft Copilot Studio publié dans votre environnement
• Compréhension de base de la connexion d’applications de code à des données

Vérifiez que vous disposez d’une connexion Microsoft Copilot Studio

Pour connecter votre application de code à un agent Copilot Studio, vous avez besoin d’une connexion Microsoft Copilot Studio dans votre environnement. Vérifiez s’il en existe déjà un ou créez-en un.

Rechercher les connexions existantes

Pour voir si vous disposez déjà d’une connexion Microsoft Copilot Studio à l’aide de la pac connection list commande :

pac connection list

Recherchez une connexion avec l’ID d’API /providers/Microsoft.PowerApps/apis/shared_microsoftcopilotstudioet copiez la connectionId valeur.

Créer une connexion

Si vous n’avez pas de connexion existante, vous devez en créer une via l’interface utilisateur du portail Power Apps Maker. Suivez les instructions dans comment connecter des applications de code aux données et veuillez copier le connectionId.

Ajouter le connecteur Microsoft Copilot Studio

Après avoir créé une connexion Microsoft Copilot Studio, utilisez la commande PAC CLI pac code add-data-source pour l’ajouter à votre application de code :

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

Cette commande effectue automatiquement :

• Met à jour votre power.config.json fichier avec la source de données Copilot Studio
• Génère le modèle TypeScript et les fichiers de service dans le src/generated dossier

Publier et obtenir le nom de votre agent

Avant de pouvoir appeler un agent à partir de votre application de code, vous devez le publier et obtenir son nom.

Publier votre agent

1. Ouvrir votre agent dans Copilot Studio
2. Sélectionnez Publier pour publier votre agent

Obtenir le nom de votre agent

1. Dans Copilot Studio, accédez à Canaux.
2. Sélectionnez l’application web.
3. Affichez la chaîne de connexion pour trouver le nom de votre agent.

Le format de l’URL est :

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

Exemple de nom d’agent :cr3e1_customerSupportAgent

Conseil / Astuce

Copiez le nom de l’agent exactement tel qu’il apparaît dans l’URL. Les noms d’agents respectent la casse et incluent généralement un préfixe d’éditeur.

Appeler un agent Copilot Studio

Avec le connecteur ajouté, vous pouvez appeler un agent Copilot Studio à partir de votre application de code. Les étapes suivantes vous montrent comment importer le service généré, envoyer un message à l’agent et gérer sa réponse.

Utiliser l’action ExecuteCopilotAsyncV2

Utilisez l’action ExecuteCopilotAsyncV2 pour appeler des agents à partir d’applications de code. Cette action retourne les réponses de l’agent de façon synchrone. Il s’agit de l’action Exécuter l'Agent et attendre incluse dans le connecteur Microsoft Copilot Studio.

Chemin d’accès de l’API :/proactivecopilot/executeAsyncV2

Importer le service généré

Après avoir ajouté la source de données, importez le service TypeScript généré :

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

Envoyer un message à l’agent

Utilisez la ExecuteCopilotAsyncV2 méthode pour envoyer un message et attendre la réponse de l’agent :

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

Paramètres de la demande

La ExecuteCopilotAsyncV2 méthode accepte les paramètres suivants :

Paramètre	Obligatoire	Type	Descriptif
message	Oui	ficelle	La demande ou les données à envoyer à l’agent. Il peut s’agir d’une chaîne JSON pour les données structurées.
notificationUrl	Oui	ficelle	Utiliser l'URL d'espace réservé ("https://notificationurlplaceholder"). L’API nécessite cette URL, mais ne l’utilise pas en mode synchrone.
agentName	Oui	ficelle	Nom de votre agent Copilot Studio publié.

Structure de réponse

La réponse contient les propriétés suivantes :

Propriété	Type	Descriptif
responses	string[]	Tableau de chaînes de réponse de l’agent
conversationId	string	L'identifiant de conversation pour le suivi
lastResponse	string	Réponse la plus récente de l’agent
completed	boolean	Indique si l’agent a terminé le traitement

Exemple : Obtenir la réponse de l’agent

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);
}

Exemple : Analyser les réponses JSON

Les agents retournent souvent des réponses sous forme de chaînes JSON. Analysez les réponses pour extraire des données spécifiques :

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);
}

Résolution des problèmes

Si vous rencontrez des problèmes de connexion ou d’appel d’un agent Copilot Studio, les solutions suivantes résolvent les problèmes les plus courants.

L’agent ne retourne pas de réponse

Solution: Vérifiez que vous utilisez l’opération ExecuteCopilotAsyncV2 (/proactivecopilot/executeAsyncV2). D’autres points de terminaison présentent des limitations connues :

• ExecuteCopilot (/execute) - Retourne uniquement ConversationId, pas la réponse (fire-and-forget).
• ExecuteCopilotAsync (/executeAsync) : peut renvoyer les erreurs 502 « Impossible de lire la réponse du serveur ».

Erreurs de casse de propriété en réponse

Solution : La casse des propriétés de la réponse peut varier entre les implémentations. Recherchez toutes les variantes :

• conversationId
• ConversationId
• conversationID

Utilisez un chaînage facultatif ou recherchez plusieurs variantes de casse.

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

L’agent retourne des réponses vides ou inattendues

Solution: Vérifiez que :

1. Vous avez publié votre agent dans Copilot Studio.
2. Le nom de l’agent est correct et correspond à l’agent publié.
3. Le format de message correspond à ce que votre agent attend.
4. Votre agent a configuré des rubriques pour gérer l’entrée.

Voir aussi

• Connecter votre application de code aux données
• Documentation Microsoft Copilot Studio
• Informations de référence sur les connecteurs Power Platform