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 des Hinzufügens von Datenquellen zu Ihrer Code-App

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

Um festzustellen, ob Sie bereits über eine Microsoft Copilot Studio Verbindung verfügen, verwenden Sie Folgendespa connection list:

pa 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 über keine vorhandene Verbindung verfügen, befolgen Sie Erstellen und Verwalten von Verbindungen mit der Power Apps CLI und verwenden Sie shared_microsoftcopilotstudio als Konnektorbezeichner. Speichern Sie die vom Befehl zurückgegebene Verbindungs-ID.

Fügen Sie den Microsoft Copilot Studio Connector hinzu

Nachdem Sie eine Microsoft Copilot Studio-Verbindung erstellt haben, verwenden Sie pa app add data-source, um sie Ihrer Code-App hinzuzufügen:

pa app add data-source --connector "shared_microsoftcopilotstudio" --connection-id <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

Agent-Name veröffentlichen und abrufen

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

Ihren Agenten veröffentlichen

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

Erhalte deinen Agentnamen

Wechseln Sie in Copilot Studio zu "Kanäle".
Wählen Sie "Web App" aus.
Zeigen Sie die Connection String an, um Ihren Agentnamen zu finden.

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

Antwortstruktur

Die Antwort enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
`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 ConversationId zurück, nicht die Antwort („fire-and-forget“).
ExecuteCopilotAsync (/executeAsync) – Gibt möglicherweise „Serverantwort kann nicht gelesen werden“-502-Fehler zurück.

Fehler bei Groß-/Kleinschreibung von Eigenschaften in Antworten

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

conversationId
ConversationId
conversationID

Verwenden Sie entweder die optionale Verkettung, oder überprüfen Sie auf mehrere Groß-/Kleinschreibungsvarianten.

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:

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

Siehe auch

Feedback

War diese Seite hilfreich?

Last updated on 2026-08-19