Grundlegendes zu Agent-Konzepten

Die Interaktionen eines Agents können Text, Sprache, Bilder oder Videos verwenden. Es verarbeitet die Eingaben des Benutzers, um seine Anforderung zu verstehen, und wertet die Eingabe aus, um relevante Aufgaben auszuführen. Ein Agent kann Informationen anfordern oder den Zugriff auf Dienste aktivieren und dem Benutzer antworten.

Agentbereiche

Agents in Microsoft Teams können Teil einer 1:1-Unterhaltung, eines Gruppenchats oder eines Kanals in einem Team sein. Jeder Bereich bietet einzigartige Chancen und Herausforderungen für Ihren Konversations-Agent.

In einem Kanal	In einem Gruppenchat	In einem 1:1-Chat.
Massive Reichweite	Weniger Mitglieder	Traditionelle Art und Weise
Präzise individuelle Interaktionen	@mention zum Agent	Q&A-Agents
@mention zum Agent	Ähnlich wie Kanal	Agenten, die Witze erzählen und Notizen machen

In einem Kanal

Kanäle enthalten Threadunterhaltungen zwischen mehreren Personen, sogar bis zu 2000. Dies bietet Ihrem Agent möglicherweise eine große Reichweite, aber einzelne Interaktionen müssen präzise sein. Herkömmliche Multi-Turn-Interaktionen funktionieren nicht. Stattdessen müssen Sie interaktive Karten oder Dialoge (in TeamsJS v1.x als Aufgabenmodule bezeichnet) verwenden oder die Unterhaltung in eine 1:1-Unterhaltung verschieben, um viele Informationen zu sammeln. Ihr Agent hat nur Zugriff auf Nachrichten, bei denen es sich um handelt @mentioned. Mithilfe von Microsoft Graph und Berechtigungen auf Organisationsebene können Sie zusätzliche Nachrichten aus der Unterhaltung abrufen.

Agents funktionieren in den folgenden Fällen besser in einem Kanal:

• Benachrichtigungen, wenn Sie eine interaktive Karte für die Benutzer bereitstellen, die weitere Informationen aufnimmt.
• Feedbackszenarien wie Abstimmungen und Umfragen.
• Ein einzelner Anforderungs- oder Antwortzyklus löst Interaktionen auf, und die Ergebnisse sind für mehrere Mitglieder der Unterhaltung nützlich.
• Soziale oder lustige Agenten, bei denen Sie ein tolles Katzenbild erhalten, zufällig einen Gewinner auswählen und so weiter.

In einem Gruppenchat

Gruppenchats sind Unterhaltungen ohne Threading zwischen drei oder mehr Personen. Sie weisen tendenziell weniger Mitglieder auf als ein Kanal und sind kurzlebiger. Ähnlich wie bei einem Kanal hat Ihr Agent nur Zugriff auf Nachrichten, bei denen er sich direkt befindet @mentioned .

Agents, die in einem Kanal besser funktionieren, funktionieren auch in einem Gruppenchat besser.

In einem 1:1-Chat.

1:1-Chat ist eine herkömmliche Möglichkeit für einen Konversations-Agent, mit einem Benutzer zu interagieren. Einige Beispiele für 1:1-Konversations-Agents sind:

• Q&A-Agents
• Agents, die Workflows in anderen Systemen initiieren.
• Agenten, die Witze erzählen.
• Agents, die Notizen erstellen. Überlegen Sie vor dem Erstellen von 1:1-Agents, ob eine konversationsbasierte Schnittstelle die beste Möglichkeit ist, Ihre Funktionalität darzustellen.

Aktivitätshandler und Agent-Logik

Um eine Agent-App zu erstellen, die Ihren Anforderungen entspricht, ist es wichtig, den Microsoft Teams-Aktivitätshandler und die Agent-Logik zu verstehen. Diese beiden Schlüsselkomponenten arbeiten zusammen, um die Konversationslogik zu organisieren.

• Teams-Aktivitätshandler: Verarbeitet Teams-spezifische Ereignisse und Interaktionen wie Kanalerstellung, Ergänzungen von Teammitgliedern und andere Aktionen, die nur für die Teams-Umgebung gelten. Im Teams SDK v2 werden Handler direkt auf einem App instance registriert und nicht über die Klassenvererbung.

• Agentlogik: Das App -Objekt enthält die Konversationslogik des Agents und ist für die Entscheidungsfindung basierend auf Benutzereingaben verantwortlich. Eingehende Aktivitäten werden basierend auf dem Aktivitätstyp und dem optionalen Musterabgleich an den entsprechenden Handler weitergeleitet.

Teams-Aktivitätshandler

Der Aktivitätshandler ist der Kern der Funktionalität eines Agents, der Benutzerinteraktionen verwaltet und verarbeitet. Im Teams SDK v2:

• Sie instanziieren ein App Objekt und registrieren Handler dafür.
• Handler empfangen ein typisiertes Kontextobjekt (IActivityContext in TypeScript, IContext<TActivity> in C#, ActivityContext[TActivity] in Python).
• Antworten und proaktive Nachrichten werden über ctx.reply() oder ctx.send()gesendet.

Wenn ein Teams-Agent eine Aktivität empfängt, leitet das SDK diese über den registrierten Handler weiter. Teams-spezifische Ereignisse (Kanallebenszyklus, Mitgliedsänderungen usw.) werden als eindeutige benannte Ereignisse angezeigt, sodass Sie keine manuelle Überprüfung durchführen channelData.eventType müssen.

Hinweis

Wenn die Verarbeitung einer Agent-Aktivität mehr als 15 Sekunden dauert, sendet Teams eine Wiederholungsanforderung an den Agent-Endpunkt, sodass möglicherweise doppelte Anforderungen angezeigt werden.

Codeausschnitte für Aktivitätshandler

Die folgenden Codeausschnitte zeigen Teams-Aktivitätshandler für Kanal- und Teamlebenszyklusereignisse.

TypeScript

Agents werden mithilfe des @microsoft/teams.apps -Pakets erstellt. Sie instanziieren und App registrieren Handler mit app.on(eventName, handler). Das SDK leitet Aktivitäten basierend auf der Ereignisnamenzeichenfolge an den richtigen Handler weiter.

channelCreated

import { App } from '@microsoft/teams.apps';

const app = new App();

app.on('channelCreated', async ({ activity }) => {
  const channel = activity.channelData.channel; // { id, name }
  const team    = activity.channelData.team;    // { id, name }
  // Code logic here
});

channelDeleted

app.on('channelDeleted', async ({ activity }) => {
  // Code logic here
});

channelRenamed

app.on('channelRenamed', async ({ activity }) => {
  // Code logic here
});

teamRenamed

app.on('teamRenamed', async ({ activity }) => {
  // Code logic here
});

membersAdded / membersRemoved

app.on('membersAdded', async ({ activity, send }) => {
  for (const member of activity.membersAdded) {
    await send(`Welcome, ${member.name}!`);
  }
});

app.on('membersRemoved', async ({ activity }) => {
  // Code logic here
});

messageUpdate / messageDelete

Nachrichtenbearbeitungen werden als messageUpdateangezeigt. Vorläufige Löschvorgänge werden als messageDelete angezeigt. Die activity.channelData.eventType ist 'softDeleteMessage'.

app.on('messageUpdate', async ({ activity }) => {
  // Code logic here
});

app.on('messageDelete', async ({ activity }) => {
  // activity.channelData.eventType === 'softDeleteMessage' for soft deletes
  // Code logic here
});

C#

Agents werden mithilfe des Microsoft.Teams.Apps -Pakets erstellt. Sie instanziieren Registrierungen von App - und -Kettenhandlern mithilfe von Erweiterungsmethoden wie OnMessage(), OnChannelCreated()usw. Alle Handler empfangen ein IContext<TActivity> -Objekt.

OnChannelCreated

using Microsoft.Teams.Apps;

var app = new App();

app.OnChannelCreated(async context => {
    var channel = context.Activity.ChannelData.Channel;
    var team    = context.Activity.ChannelData.Team;
    // Code logic here
});

OnChannelDeleted

app.OnChannelDeleted(async context => {
    // Code logic here
});

OnChannelRenamed

app.OnChannelRenamed(async context => {
    // Code logic here
});

OnTeamRenamed

app.OnTeamRenamed(async context => {
    // Code logic here
});

OnMembersAdded

app.OnMembersAdded(async context => {
    foreach (var member in context.Activity.MembersAdded) {
        // Code logic here
    }
});

OnMembersRemoved

app.OnMembersRemoved(async context => {
    foreach (var member in context.Activity.MembersRemoved) {
        // Code logic here
    }
});

OnMessageUpdate / OnMessageDelete

Nachrichtenbearbeitungen werden über OnMessageUpdateverarbeitet. Vorläufige Löschungen werden über OnMessageDeleteverarbeitet.

app.OnMessageUpdate(async context => {
    // Code logic here
});

app.OnMessageDelete(async context => {
    // Code logic here
});

Python

Agents werden mithilfe des microsoft-teams-apps -Pakets erstellt. Handler werden mithilfe von Decorators auf einem App instance registriert. Jeder Handler ist eine async Funktion, die ein ActivityContext[TActivity] -Objekt empfängt.

on_channel_created

from microsoft_teams.apps import App, ActivityContext
from microsoft_teams.api.activities import ConversationUpdateActivity

app = App()

@app.on_channel_created
async def handle_channel_created(ctx: ActivityContext[ConversationUpdateActivity]):
    channel = ctx.activity.channel_data.channel
    team    = ctx.activity.channel_data.team
    # Code logic here

on_channel_deleted

@app.on_channel_deleted
async def handle_channel_deleted(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_channel_renamed

@app.on_channel_renamed
async def handle_channel_renamed(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_team_renamed

@app.on_team_renamed
async def handle_team_renamed(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_conversation_update (Mitglieder hinzugefügt/entfernt)

Hinzugefügte und entfernte Member werden über on_conversation_updatebehandelt. Überprüfen sie ctx.activity.members_added und ctx.activity.members_removed:

@app.on_conversation_update
async def handle_conversation_update(ctx: ActivityContext[ConversationUpdateActivity]):
    if ctx.activity.members_added:
        for member in ctx.activity.members_added:
            await ctx.send(f"Welcome, {member.name}!")
    if ctx.activity.members_removed:
        # Code logic here

on_edit_message / on_soft_delete_message / on_undelete_message

@app.on_edit_message
async def handle_edit_message(ctx: ActivityContext):
    # Code logic here

@app.on_soft_delete_message
async def handle_soft_delete_message(ctx: ActivityContext):
    # Code logic here

@app.on_undelete_message
async def handle_undelete_message(ctx: ActivityContext):
    # Code logic here

Beispiel für einen Agent-Aktivitätshandler

Der folgende Code enthält ein Beispiel für eine Agent-Aktivität:

TypeScript

import { App } from '@microsoft/teams.apps';

const app = new App();

app.on('message', async ({ activity, reply }) => {
  const senderName = activity.from.name;
  await send(`Hello <at>${senderName}</at>.`);
});

app.start().catch(console.error);

C#

using Microsoft.Teams.Apps.Activities;
using Microsoft.Teams.Apps.Extensions;
using Microsoft.Teams.Plugins.AspNetCore.DevTools.Extensions;
using Microsoft.Teams.Plugins.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.AddTeams().AddTeamsDevTools();
var app = builder.Build();
var teams = app.UseTeams();

teams.OnMessage(async (context, cancellationToken) =>
{
    var senderName = context.Activity.From.Name;
    await context.Send($"Hello <at>{senderName}</at>.", cancellationToken);
});

app.Run();

Python

import asyncio
from microsoft_teams.apps import App, ActivityContext
from microsoft_teams.api import MessageActivity

app = App()

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    sender_name = ctx.activity.from_property.name
    await ctx.send(f"Hello <at>{sender_name}</at>.")

if __name__ == "__main__":
    asyncio.run(app.start())

Agent-Logik

Die Agentlogik umfasst die grundlegenden Regeln und Entscheidungsframeworks, die die Aktionen und Interaktionen eines Agents diktieren. Es wird beschrieben, wie der Agent Benutzereingaben interpretiert, Antworten formuliert und an Unterhaltungen teilnimmt.

Im Teams SDK v2 verarbeitet die Agent-Logik eingehende Aktivitäten von einem oder mehreren Agent-Kanälen und generiert ausgehende Aktivitäten. Das gesamte Aktivitätsrouting wird vom App instance behandelt. Sie registrieren die Handler, und das SDK verteilt Aktivitäten automatisch an sie.

TypeScript

Kernaktivitätshandler

Die Liste der von app.on() unterstützten Ereignisnamen enthält Folgendes:

Ereignis	Ereignisnamenszeichenfolge	Beschreibung
Jeder empfangene Aktivitätstyp	'activity'	Catch-All-Handler, der für jede Aktivität aufgerufen wird.
Nachrichtenaktivität empfangen	'message'	Verarbeiten eingehender TEXTnachrichten. Verwenden Sie app.message(pattern, handler) für den RegEx-Abgleich.
Unterhaltungsupdate empfangen	'conversationUpdate'	Unformatierte Konversationsaktualisierungsaktivität.
Installation hinzugefügt	'install.add'	Der Agent wurde installiert.
Installation entfernt	'install.remove'	Der Agent wurde deinstalliert.
Mitglieder hinzugefügt	'membersAdded'	Mindestens ein Mitglied hat sich der Unterhaltung angeschlossen.
Mitglieder entfernt	'membersRemoved'	Mindestens ein Mitglied hat die Unterhaltung verlassen.
Nachricht bearbeitet	'messageUpdate'	Eine Nachricht in der Unterhaltung wurde bearbeitet.
Nachricht vorläufig gelöscht	'messageDelete'	Eine Nachricht wurde vorläufig gelöscht (activity.channelData.eventType === 'softDeleteMessage').
Lesebestätigung empfangen	'readReceipt'	Eine Lesebestätigung wurde empfangen.

Teams-spezifische Ereignishandler

app.on() unterstützt die folgenden Teams-spezifischen Ereignisnamenszeichenfolgen:

Ereignis	Ereignisnamenszeichenfolge	Beschreibung
channelCreated	'channelCreated'	Ein Teams-Kanal wurde erstellt.
channelDeleted	'channelDeleted'	Ein Teams-Kanal wurde gelöscht.
channelRenamed	'channelRenamed'	Ein Teams-Kanal wurde umbenannt.
channelRestored	'channelRestored'	Ein Teams-Kanal wurde wiederhergestellt.
channelMemberAdded	'channelMemberAdded'	Einem Kanal wurde ein Mitglied hinzugefügt.
channelMemberRemoved	'channelMemberRemoved'	Ein Mitglied wurde aus einem Kanal entfernt.
teamRenamed	'teamRenamed'	Das Team wurde umbenannt.
teamArchived	'teamArchived'	Das Team wurde archiviert.
teamDeleted	'teamDeleted'	Das Team wurde gelöscht.
teamRestored	'teamRestored'	Das Team wurde wiederhergestellt.
Besprechung gestartet	'meetingStart'	Eine Besprechung wurde gestartet.
Besprechung beendet	'meetingEnd'	Eine Besprechung wurde beendet.
Mitglied des Teilnehmers	'meetingParticipantJoin'	Ein Teilnehmer ist einer Besprechung beigetreten.
Teilnehmer verlassen	'meetingParticipantLeave'	Ein Teilnehmer hat eine Besprechung verlassen.

Aufrufaktivitäten in Teams

In der folgenden Tabelle sind Aufrufaktivitätshandler aufgeführt, die über verfügbar sind app.on():

Aufruftyp	Ereignisnamenszeichenfolge	Beschreibung
CardAction.Invoke	'card.action'	Eine Karte Aktionsaufrufaktivität () empfangenadaptiveCard/action wurde.
signin/verifyState	Automatische Verarbeitung durch das SDK (OAuth-Fluss)	Aktivität zum Überprüfen des Anmeldezustands.
task/fetch	'dialog.open'	Ein Dialogfeld (Aufgabenmodul) wurde abgerufen.
task/submit	'dialog.submit'	Ein Dialogfeld (Aufgabenmodul) wurde übermittelt.

C#

Kernaktivitätshandler

Die App -Klasse macht Erweiterungsmethoden zum Registrieren von Handlern verfügbar. Methoden geben für Fluent-Verkettung zurück App .

Ereignis	Erweiterungsmethode	Beschreibung
Jeder empfangene Aktivitätstyp	OnActivity(handler)	Catch-All-Handler, der für jede Aktivität aufgerufen wird.
Nachrichtenaktivität empfangen	OnMessage(handler)	Verarbeiten eingehender TEXTnachrichten. Übergeben Sie eine regex-Zeichenfolge als erstes Argument für den Musterabgleich.
Unterhaltungsupdate empfangen	OnConversationUpdate(handler)	Unformatierte Konversationsaktualisierungsaktivität.
Mitglieder ohne Agent	OnMembersAdded(handler)	Wird ausgelöst, wenn MembersAdded.Length > 0.
Nicht-Agent-Mitglieder verlassen	OnMembersRemoved(handler)	Wird ausgelöst, wenn MembersRemoved.Length > 0.
Installation hinzugefügt	OnInstall(handler)	Der Agent wurde installiert.

Teams-spezifische Aktivitätshandler

Ereignis	Erweiterungsmethode	Beschreibung
Kanal erstellt	OnChannelCreated(handler)	Ein Teams-Kanal wurde erstellt.
Kanal gelöscht	OnChannelDeleted(handler)	Ein Teams-Kanal wurde gelöscht.
Kanal umbenannt	OnChannelRenamed(handler)	Ein Teams-Kanal wurde umbenannt.
Team umbenannt	OnTeamRenamed(handler)	Das Team wurde umbenannt.
Nachricht bearbeitet	OnMessageUpdate(handler)	Eine Nachricht wurde bearbeitet.
Nachricht vorläufig gelöscht	OnMessageDelete(handler)	Eine Nachricht wurde vorläufig gelöscht.

Aufrufaktivitäten in Teams

Aufruftyp	Erweiterungsmethode	Beschreibung
CardAction.Invoke	OnExecuteAction(handler)	Eine Karte Aktionsaufrufaktivität wurde empfangen.
task/fetch	OnTaskFetch(handler)	Ein Dialogfeld (Aufgabenmodul) wurde abgerufen.
task/submit	OnTaskSubmit(handler)	Ein Dialogfeld (Aufgabenmodul) wurde übermittelt.
fileConsent/invoke	OnFileConsent(handler)	Eine Dateigenehmigung Karte Aktivität empfangen wurde.
signin/verifyState	Automatische Verarbeitung durch das SDK (OAuth-Fluss)	Aktivität zum Überprüfen des Anmeldezustands.

Python

Kernaktivitätshandler

Die App -Klasse macht die Handlerregistrierung im Decorator-Stil verfügbar.

Ereignis	Dekorateur	Beschreibung
Jede empfangene Aktivität	@app.on_activity	Catch-All-Handler für jede Aktivität.
Empfangene Nachricht	@app.on_message	Verarbeiten eingehender TEXTnachrichten.
Nachricht mit Muster	@app.on_message_pattern(re.compile(...))	Verarbeiten von Nachrichten, die einem RegEx-Muster entsprechen.
Unterhaltungsupdate	@app.on_conversation_update	Unformatierte Konversationsaktualisierung; Aktivieren Sie members_added / members_removed.
Installation hinzugefügt	@app.on_install_add	Der Agent wurde installiert.
Installation entfernt	@app.on_install_remove	Der Agent wurde deinstalliert.

Teams-spezifische Aktivitätshandler

Ereignis	Dekorateur	Beschreibung
Kanal erstellt	@app.on_channel_created	Ein Teams-Kanal wurde erstellt.
Kanal gelöscht	@app.on_channel_deleted	Ein Teams-Kanal wurde gelöscht.
Kanal umbenannt	@app.on_channel_renamed	Ein Teams-Kanal wurde umbenannt.
Team umbenannt	@app.on_team_renamed	Das Team wurde umbenannt.
Nachricht bearbeitet	@app.on_edit_message	Eine Nachricht wurde bearbeitet.
Nachricht vorläufig gelöscht	@app.on_soft_delete_message	Eine Nachricht wurde vorläufig gelöscht.
Nachricht wurde nicht gelöscht	@app.on_undelete_message	Eine gelöschte Nachricht wurde wiederhergestellt.
Besprechung gestartet	@app.on_meeting_start	Eine Besprechung wurde gestartet.
Besprechung beendet	@app.on_meeting_end	Eine Besprechung wurde beendet.
Mitglied des Teilnehmers	@app.on_meeting_participant_join	Ein Teilnehmer ist einer Besprechung beigetreten.
Teilnehmer verlassen	@app.on_meeting_participant_leave	Ein Teilnehmer hat eine Besprechung verlassen.

Aufrufaktivitäten in Teams

Aufruftyp	Dekorateur	Beschreibung
CardAction.Invoke	@app.on_card_action	Eine Karte Aktionsaufrufaktivität wurde empfangen.
task/fetch	@app.on_dialog_open	Ein Dialogfeld (Aufgabenmodul) wurde abgerufen.
task/submit	@app.on_dialog_submit	Ein Dialogfeld (Aufgabenmodul) wurde übermittelt.
fileConsent/invoke	@app.on_file_consent	Eine Dateigenehmigung Karte Aktivität empfangen wurde.
signin/verifyState	Automatische Verarbeitung durch das SDK (OAuth-Fluss)	Aktivität zum Überprüfen des Anmeldezustands.

Nachdem Sie sich nun mit Agent-Aktivitätshandlern vertraut gemacht haben, lassen Sie uns sehen, wie sich Agents je nach Konversation und den Nachrichten, die sie empfängt oder sendet, unterschiedlich verhalten.

Empfehlungen

Ein umfangreicher Dialog zwischen Ihrem Agent und dem Benutzer ist eine langsame und komplexe Möglichkeit, eine Aufgabe zu erledigen. Ein Agent, der übermäßige Befehle unterstützt, insbesondere eine breite Palette von Befehlen, wird von Benutzern nicht erfolgreich oder positiv angesehen.

• Vermeiden von Multi-Turn-Erfahrungen im Chat Für einen umfangreichen Dialog muss der Entwickler den Zustand beibehalten. Um diesen Zustand zu beenden, muss ein Benutzer entweder ein Timeout ausführen oder Abbrechen auswählen. Auch der Prozess ist mühsam. Sehen Sie sich beispielsweise das folgende Unterhaltungsszenario an:

  BENUTZER: Plane eine Besprechung mit Marie.

  AGENT: Ich habe 200 Ergebnisse gefunden, einschließlich eines Vor- und Nachnamens.

  BENUTZER: Plane eine Besprechung mit Marie Krause.

  AGENT: OK, wann möchten Sie Megan Bowen treffen?

  BENUTZER: um 13:00 Uhr.

  AGENT: An welchem Tag?

• Unterstützung von sechs oder weniger häufigen Befehlen Da im aktuellen Agent-Menü nur sechs Befehle angezeigt werden, wird wahrscheinlich kein weiterer Befehl in irgendeiner Häufigkeit verwendet. Agenten, die tief in einen bestimmten Bereich gehen, anstatt zu versuchen, ein breiter Assistent arbeiten und besser abschneiden.

• Optimieren der Größe von Wissensdatenbank für eine schnellere Interaktion Einer der Nachteile von Agents besteht darin, dass es schwierig ist, einen großen Abruf Wissensdatenbank mit antworten ohne Rangfolge aufrechtzuerhalten. Agents eignen sich am besten für kurze, schnelle Interaktionen und nicht für lange Listen, um nach einer Antwort zu suchen.

Hinweis

Die Teams-Plattform unterstützt nur TLS-Version 1.2 (Transport Layer Security). Stellen Sie sicher, dass Sie Ihre Agent-Umgebung entsprechend konfigurieren.

Erkunden anderer Agent-Features

Zusätzlich zu den herkömmlichen Agent-Features können Sie auch erweiterte Features erkunden, die in einer Teams-Agent-App verfügbar sind:

• Rufen Sie Teams-spezifischen Kontext für Ihren Agent ab.
• Agents für Anrufe und Onlinebesprechungen.
• Aktivieren Sie SSO für Ihre App.

Codebeispiel

Beispielname	Beschreibung	TypeScript	C#	Python
Teams-Konversations-Agent	Diese App veranschaulicht grundlegende Agent-Ereignisse.	View	View	View