So geht's: Verbinden Sie Ihre Codeanwendung mit Microsoft Copilot Studio Agents

Microsoft Copilot Studio-Agents bringen KI-gestützte Funktionen zu Ihren Code-Apps. In diesem Artikel erfahren Sie, wie Sie Den Microsoft Copilot Studio-Connector zu Ihrer Code-App hinzufügen und Agents aufrufen, um Benutzereingaben zu verarbeiten und intelligente Antworten zurückzugeben.

Voraussetzungen

• Ein initialisiertes Code-Anwendungsprojekt
• Ein veröffentlichter Microsoft Copilot Studio-Agent in Ihrer Umgebung
• Grundlegendes Verständnis der Verbindung von Code-Apps mit Daten

Stellen Sie sicher, dass Sie über eine Microsoft Copilot Studio-Verbindung verfügen

Um Ihre Code-App mit einem Copilot Studio-Agent zu verbinden, benötigen Sie eine Microsoft Copilot Studio-Verbindung in Ihrer Umgebung. Überprüfen Sie, ob bereits eins vorhanden ist, oder erstellen Sie eine neue.

Überprüfen Sie vorhandene Verbindungen

So überprüfen Sie, ob Sie bereits über eine Microsoft Copilot Studio-Verbindung mit dem pac connection list Befehl verfügen:

pac connection list

Suchen Sie nach einer Verbindung mit der API-ID /providers/Microsoft.PowerApps/apis/shared_microsoftcopilotstudio, und kopieren Sie den connectionId Wert.

Eine neue Verbindung erstellen

Wenn Sie nicht über eine vorhandene Verbindung verfügen, müssen Sie eine über die Power Apps Maker-Portal-Benutzeroberfläche erstellen. Befolgen Sie die Anweisungen zum Verbinden von Code-Apps mit Daten und stellen Sie sicher, dass Sie die connectionIdDatei kopieren.

Hinzufügen des Microsoft Copilot Studio-Connectors

Verwenden Sie nach dem Erstellen einer Microsoft Copilot Studio-Verbindung den PAC CLI-Befehl pac code add-data-source , um sie Ihrer Code-App hinzuzufügen:

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

Dieser Befehl führt automatisch folgendes aus:

• Aktualisiert Ihre power.config.json Datei mit der Copilot Studio-Datenquelle.
• Generiert TypeScript-Modell- und Dienstdateien im src/generated Ordner

Veröffentlichen und erhalten Ihres Agentnamens

Bevor Sie einen Agent aus Ihrer Code-App aufrufen können, müssen Sie ihn veröffentlichen und seinen Namen abrufen.

Agent veröffentlichen

1. Öffnen Sie Ihren Agenten in Copilot Studio
2. Wählen Sie "Veröffentlichen" aus, um Ihren Agent zu veröffentlichen.

Erhalte deinen Agentnamen

1. Wechseln Sie in Copilot Studio zu "Kanäle".
2. Wählen Sie "Web App" aus.
3. Zeigen Sie die Verbindungszeichenfolge an, um Ihren Agentnamen zu ermitteln.

Das URL-Format lautet:

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

Beispiel-Agentname:cr3e1_customerSupportAgent

Tipp

Kopieren Sie den Agentnamen genau so, wie er in der URL angezeigt wird. Agentennamen sind groß- und kleinschreibungssensitiv und enthalten typischerweise ein Herausgeberpräfix.

Einen Copilot Studio-Agenten aufrufen

Nachdem der Connector hinzugefügt wurde, können Sie einen Copilot Studio-Agent aus Ihrer Code-App aufrufen. Die folgenden Schritte zeigen, wie Sie den generierten Dienst importieren, eine Nachricht an den Agent senden und dessen Antwort behandeln.

Verwenden Sie die ExecuteCopilotAsyncV2-Aktion

Verwenden Sie die ExecuteCopilotAsyncV2 Aktion, um Agents aus Code-Apps aufzurufen. Diese Aktion gibt Agentantworten synchron zurück. Es handelt sich um die Aktion "Execute Agent and Wait", die im Microsoft Copilot Studio-Connector enthalten ist.

API-Pfad:/proactivecopilot/executeAsyncV2

Importieren des generierten Diensts

Importieren Sie nach dem Hinzufügen der Datenquelle den generierten TypeScript-Dienst:

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

Senden einer Nachricht an den Agent

Verwenden Sie die ExecuteCopilotAsyncV2 Methode, um eine Nachricht zu senden und auf die Antwort des Agents zu warten:

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

Anforderungsparameter

Die ExecuteCopilotAsyncV2 Methode akzeptiert die folgenden Parameter:

Parameter	Erforderlich	Typ	Description
message	Ja	Schnur	Die Aufforderung oder Daten, die an den Agent gesendet werden sollen. Dies kann eine JSON-Zeichenfolge für strukturierte Daten sein.
notificationUrl	Ja	Schnur	Platzhalter-URL (verwenden "https://notificationurlplaceholder"). Die API erfordert diese URL, verwendet sie aber nicht im synchronen Modus.
agentName	Ja	Schnur	Der Name Ihres veröffentlichten Copilot Studio-Agents.

Antwortstruktur

Die Antwort enthält die folgenden Eigenschaften:

Eigentum	Typ	Description
responses	string[]	Array von Antwortzeichenketten des Agenten
conversationId	string	Die Gesprächs-ID für die Nachverfolgung
lastResponse	string	Die letzte Antwort des Agents
completed	boolean	Gibt an, ob der Agent die Verarbeitung abgeschlossen hat.

Beispiel: Agentenantwort erhalten

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

Beispiel: Analysieren von JSON-Antworten

Agents geben häufig Antworten als JSON-Zeichenfolgen zurück. Analysieren Sie die Antworten, um bestimmte Daten zu extrahieren:

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

Problembehandlung

Wenn Sie Probleme beim Herstellen einer Verbindung oder beim Aufrufen eines Copilot Studio Agent haben, können Ihnen die folgenden Lösungen bei den am häufigsten auftretenden Problemen helfen.

Agent gibt keine Antwort zurück.

Lösung: Stellen Sie sicher, dass Sie den ExecuteCopilotAsyncV2 Vorgang (/proactivecopilot/executeAsyncV2) verwenden. Andere Endpunkte haben bekannte Einschränkungen:

• ExecuteCopilot (/execute) - Gibt nur zurück ConversationId, nicht die Antwort (Feuer und Vergessen).
• ExecuteCopilotAsync () -/executeAsync Gibt möglicherweise 502 "Serverantwortfehler können nicht gelesen werden" zurück.

Fehler bei der Groß-/Kleinschreibung von Eigenschaften in Antworten

Lösung: Die Groß-/Kleinschreibung von Antwortattributen kann zwischen Implementierungen variieren. Überprüfen Sie auf alle Variationen:

• conversationId
• ConversationId
• conversationID

Verwenden Sie entweder die optionale Verkettungs-Syntax oder überprüfen Sie auf mehrere Groß-/Kleinschreibungsvariationen.

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

Agent gibt leere oder unerwartete Antworten zurück.

Lösung: Stellen Sie sicher, dass:

1. Sie haben Ihren Agenten in Copilot Studio veröffentlicht.
2. Der Agentname ist korrekt und entspricht dem veröffentlichten Agent.
3. Das Nachrichtenformat stimmt mit den Erwartungen Ihres Agenten überein.
4. Ihr Agent verfügt über Themen, die für die Verarbeitung der Eingabe konfiguriert sind.

Siehe auch

• Verbinden Ihrer Code-App mit Daten
• Microsoft Copilot Studio-Dokumentation
• Referenz zu Power Platform-Connectors