Schreiben effektiver Anweisungen für deklarative Agents mit API-Plug-Ins

Deklarative Agents passen Microsoft 365 Copilot an die spezifischen Anforderungen einer Organization an. Wenn Sie deklarative Agents mit dem Microsoft 365 Agents Toolkit erstellen, können Sie Ihrem Agent über API-Plug-Ins Skills hinzufügen. API-Plug-Ins ermöglichen es Ihrem Agenten, die Daten einer organization über APIs abzufragen und mit ihnen zu interagieren.

Dieser Artikel beschreibt die Agent-Architektur und enthält bewährte Methoden zum Schreiben von Anweisungen für deklarative Agents, die API-Plug-Ins enthalten.

Hauptkomponenten deklarativer Agents mit API-Plugins

Deklarative Agents, die API-Plug-Ins aufrufen, enthalten mehrere Komponenten, die eine effektive Integration und Funktionalität gewährleisten. Wenn Sie diese Architektur verstehen, können Sie Ihren Agent effektiv entwerfen. Die Architektur umfasst die folgenden Komponenten:

• Anwendungsmanifest : Beschreibt, wie Ihre App konfiguriert ist, und verweist auf das deklarative Agentmanifest.
• Deklaratives Agentmanifest – Definiert die Konfiguration des Agents, einschließlich Anweisungen, Funktionen, Gesprächsstarter und Aktionen. Verweist auf das Plug-In-Manifest.
• Plug-in-Manifest - Beschreibt die Plugin-Konfiguration, einschließlich verfügbarer Funktionen und eines Verweises auf die OpenAPI-Spezifikation.
• OpenAPI-Spezifikation – Bietet detaillierte Definitionen von API-Endpunkten, einschließlich Pfaden, Parametern, Anforderungs- und Antwortformaten und Authentifizierung.

Zusammen definieren diese Dateien das Verhalten des Agents und seine Interaktion mit der zugrunde liegenden API.

Weitere Informationen zu API-Plug-Ins finden Sie unter:

• Plugins für Microsoft 365 Copilot
• So machen Sie ein OpenAPI-Dokument effektiv zur Erweiterung der Copilot-Funktionen

Funktionszuordnung im Plug-In-Manifest

Im Plug-In-Manifest muss jede Funktion einer entsprechenden operationId in der OpenAPI-Spezifikation zugeordnet werden. Dadurch wird sichergestellt, dass der Agent beim Aufrufen einer Funktion (z. B. createTask) weiß, welcher API-Endpunkt aufgerufen werden muss.

Die folgenden Beispiele zeigen die Zuordnung im Plug-In-Manifest und die zugeordnete Funktion in der OpenAPI-Spezifikation.

"functions": [
  {
    "name": "createTask",
    "description": "Creates a new task in the specified task list."
  }
]

paths:
  /me/todo/lists/{listId}/tasks:
    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task in the specified task list.
      parameters:

Bewährte Methoden für Agent-Anweisungen

Das Schreiben effektiver Anweisungen ist unerlässlich, um sicherzustellen, dass deklarative Agents mit API-Plugins erfolgreich sind. Wenden Sie zum Optimieren Ihres Agents die richtige Funktionszuordnung an, verwenden Sie die Verkettung, um umfangreichere Interaktionen zu ermöglichen, und testen und verfeinern Sie iterativ das Verhalten Ihres Agents.

Wenden Sie die folgenden bewährten Methoden an, wenn Sie Anweisungen für deklarative Agents mit API-Plug-Ins schreiben:

• Vermeiden Sie mehrdeutige oder negative Anweisungen. Kontrastierende oder negative Anweisungen können zu Mehrdeutigkeit führen und das Modell verwirren. Konzentrieren Sie sich auf die Definition valider Anwendungsfälle mit positiven Beispielen. Wenn es wichtig ist, zwischen gültigen und ungültigen Abfragen zu unterscheiden, geben Sie klare Kriterien und Beispiele an, die die erwartete Agent-Antwort für jede Abfrage definieren.
• Anwendungsbeispiele Geben Sie klare Beispiele für das Verhalten des Agents. Zum Beispiel:

Benutzereingabe: Wie ist das Wetter in Prag? Agent-Anruf: getWeather(location="Prague") Benutzereingabe: "Brauche ich morgen einen Regenschirm?" Agentaufruf: getWeather(location=user_location, forecast="tomorrow")

• Überprüfen und testen Sie die Anweisungen. Testen Sie Anweisungen in verschiedenen Szenarien, um sicherzustellen, dass der Agent die richtigen Funktionsaufrufe ausführt. Wenn Sie beim Testen feststellen, dass der Agent unerwartete Funktionen aufruft, überarbeiten Sie die Funktionsbeschreibung in der OpenAPI-Spezifikation und erläutern Sie die Agentanweisungen, um die Absichtszuordnung zu verbessern.

• Entwurfsanweisungen für mehrteilige Unterhaltungen. Wenn Sie API-Plug-Ins integrieren, entwerfen Sie Ihre Anweisungen für den Agenten, um mehrteilige Konversationen zu verarbeiten.

Wenn die Funktion beispielsweise mehrere Parameter erfordert, weisen Sie den Agent zusätzlich zur Definition der erforderlichen Parameter in der OpenAPI-Spezifikation an, alle Parameter zu erfassen, bevor Sie den API-Aufruf durchführen. Dadurch wird sichergestellt, dass der Agent alle erforderlichen Informationen in einer logischen Reihenfolge sammelt.

Das folgende Beispiel zeigt, wie Sie einen Wetteragenten für mehrteilige Unterhaltungen und den daraus resultierenden Agentenablauf anweisen.

Anweisungen für Agent

Agent-Fluss

Wenn der Benutzer nach dem Wetter fragt: - Fragen Sie den Benutzer nach dem Standort. - Fragen Sie den Benutzer nach dem prognostizierten Tag. - Fragen Sie den Benutzer nach dem Einheitensystem. - Rufen Sie getWeather nur auf, wenn Sie alle Werte gesammelt haben.

Benutzer: "Wie ist das Wetter?" Agent: "Wo ist Ihr Standort?" Benutzer: "London" Agent: "Bevorzugen Sie die Wetterinformationen in metrischen oder imperialen Einheiten?" User: "Metric" Agent: "Benötigen Sie das Wetter für heute oder die Vorhersage für morgen?" Benutzer: "Heute" Agent: "Ich werde das Wetter für London für heute überprüfen" Agent ruft: getWeather(location="London", forecast="today", system="Metric")

Allgemeine Best Practices für Agent-Anweisungen finden Sie unter Schreiben effektiver Anweisungen.

Verketten von Funktionsaufrufen in API-Plug-Ins

Das Verketten von Funktionsaufrufen ermöglicht es deklarativen Agents, mehrere API-Aktionen in einem nahtlosen Fluss zu kombinieren. In den folgenden Abschnitten werden allgemeine Muster und das Schreiben von Anweisungen für die einzelnen Muster beschrieben.

Verketten von Funktionsaufrufen mit Ausgabe als Eingabeparameter

Verwenden Sie das Ergebnis eines API-Aufrufs als Eingabe für einen anderen. Dies ist nützlich, wenn das Ergebnis der ersten Funktion benötigt wird, um die zweite Funktion auszuführen. Dies kann pluginübergreifend funktionieren.

Im folgenden Beispiel erstellt ein deklarativer Agent mit der Wetter-API und der To-do-API eine To-do-Aufgabe mit Daten aus der Wettervorhersage.

Anweisungen für Agent	Agent-Fluss
Um das Wetter zu erhalten, verwenden Sie immer die getWeather-Aktion , erstellen Sie dann eine Aufgabe mit dem Titel "Temperatur rein", und fügen Sie den Ort und die Temperatur, die im Wetter erwähnt werden, zum Aufgabentitel hinzu.	Benutzer: "Holen Sie sich das Wetter in Prag" Agent: Ruft getWeather (location="Prague", forecast="today") Agent: Verwendet die Daten aus dem ersten Aufruf, um eine Aufgabenaufgabe zu erstellen. createTask (title ="{weather output}")

Verkettung basierend auf dem Konversationsverlauf innerhalb eines Agenten

Wenn Sie die Verkettung basierend auf dem Unterhaltungsverlauf verwenden, verwendet der Agent frühere Antworten, um Folgeaktionen durchzuführen. Bei diesem Ansatz wird der Unterhaltungsverlauf verwendet, um den Kontext beizubehalten.

Im folgenden Beispiel löscht ein Agent eine Aufgabe anhand des Namens.

Anweisungen für Agent	Agent-Fluss
1. Wenn der Benutzer auffordert, alle Aufgaben aufzulisten, rufen Sie getTasks auf, um die Liste der Aufgaben mit Titel und ID abzurufen. 2. Wenn der Benutzer nach dem Auflisten der Aufgaben darum bittet, eine Aufgabe zu löschen, verwenden Sie die ID aus der Antwort, um deleteTask aufzurufen.	Benutzer: "Alle Aufgaben im Ordner "Aufgaben" anzeigen?" Agent: alls getTasks (folderId="Tasks") und zeigt alle To-Dos mit IDs an. Benutzer: "TaskMaster Pro To-Do löschen"-Agent: Verwendet die Informationen aus dem Konversationsverlauf, um die ID für die Aufgabe zu finden, und löscht die Aufgabe durch Aufrufen von deleteTask.

Verketten mit SharePoint-Wissen

Durch das Verketten von API-Aufrufen kann ein Agent Wissensquellen und Aktionen kombinieren, um komplexere Workflows zu entwerfen.

Im folgenden Beispiel ruft ein Agent Projektdaten status SharePoint ab und erstellt entsprechende Aufgaben in Microsoft To-Do zur Nachverfolgung.

Anweisungen für Agent	Agent-Fluss
- Um den Projektstatus zu erhalten, verwenden Sie Sharepoint Knowledge ProjectDeadlines. - Erstellen Sie immer eine Aufgabe für jedes Projekt mit der Aktualisierung des Status für den Titel.	Benutzer: "Können Sie ein Update zum Status aller Projekte bereitstellen?" Agent: Ruft Daten zum Status eines Projekts aus SharePoint ab und generiert dann mithilfe von CreateTask eine Aufgabenaufgabe für jedes Projekt.

Verkettung mit Codeinterpreter

Es ist auch möglich, API-Aufrufe zu verketten und zusätzliche Funktionen wie einen Code-Interpreter zu integrieren. Dadurch kann ein Agent API-Ausgaben dynamisch verarbeiten, um erweiterte Workflows zu ermöglichen.

Im folgenden Beispiel erstellt ein Agent ein Diagramm basierend auf den Daten in Aufgaben.

Anweisungen für Agent	Agent-Fluss
Wenn der Benutzer alle To-Dos auflisten möchte, rufen Sie getTasks auf, um die Liste der To-Dos mit Titel und ID abzurufen, und zeichnen Sie auch das Diagramm für die Ausgabe.	Benutzer: "Retrieve all tasks in Tasks" Agent: Ruft getTasks (folderId="Tasks") auf und zeigt alle To-Dos mit IDs an. Agent: Ruft den Codeinterpreter auf, um die Diagrammgenerierung basierend auf der Ausgabe des ersten Aufrufs zu initiieren.

Auch in diesem Beispiel werden mehrere Aktionen gleichzeitig ausgeführt. Dies ist nützlich, um eine Reihe verwandter Aktionen zu initiieren, die nicht mehrere Benutzereingaben erfordern.

Wenn der Codeinterpreter eine Datei (z. B. ein Diagrammbild oder eine Tabelle) generiert, zeigt Copilot automatisch einen Downloadlink in der Antwort an, sodass Benutzer die Datei lokal speichern können. Weitere Informationen finden Sie unter Generieren herunterladbarer Dateien.

Verwandte Inhalte

• Erstellen eines deklarativen Agents mit Visual Studio Code
• Plugins für Microsoft 365 Copilot