Definieren von Suchbefehlen für die Nachrichtenerweiterung

Hinweis

Agents bieten eine flexiblere, intelligentere und zukunftsfähigere Erfahrung, die umfangreichere Denkprozesse, eine einfachere Entwicklung und eine bessere Abstimmung mit den sich entwickelnden Teams und der Microsoft 365-Plattform ermöglicht. Es wird empfohlen, Agents zu untersuchen und zu erstellen.

Weitere Informationen finden Sie unter Erstellen deklarativer Agents und Build-Agents in Teams.

Wenn Sie über eine Bot-basierte Nachrichtenerweiterung verfügen, können Sie diese auch als Agent erweitern .

Der Suchbefehl wird von einem oder beiden der folgenden Speicherorte aufgerufen:

• Bereich zum Verfassen von Nachrichten: die Schaltflächen am unteren Rand des Bereichs zum Verfassen von Nachrichten.
• Befehlsfeld: Durch Verwendung von / im Befehlsfeld. Beispiel: /your-app-name. Wenn Sie das klassische Teams verwenden, wird der Suchbefehl im Befehlsfeld aufgerufen @mentioning . Beispiel: @your-app-name.

Wenn ein Suchbefehl aus dem Bereich zum Verfassen von Nachrichten aufgerufen wird, sendet der Benutzer die Ergebnisse an die Unterhaltung. Wenn ein Suchbefehl über das Befehlsfeld aufgerufen wird, interagiert der Benutzer mit der resultierenden Karte oder kopiert sie zur Verwendung an anderer Stelle.

Die folgende Abbildung zeigt die Speicherorte für die Aufrufe des Suchbefehls:

Hinzufügen des Suchbefehls zu Ihrem App-Manifest

Um den Suchbefehl zu Ihrem App-Manifest (zuvor als Teams-App-Manifest bezeichnet) hinzuzufügen, müssen Sie der obersten Ebene Ihres App-Manifest-JSON ein neues composeExtensions Objekt hinzufügen. Sie können den Suchbefehl mithilfe der Teams Developer CLI oder durch manuelles Aktualisieren des Manifests hinzufügen.

Erstellen einer Suchnachrichtenerweiterung mithilfe des Teams SDK

Sie können eine Suchnachrichtenerweiterung mit Teams erstellen Developer CLI | Teams-SDK und Agent-Fähigkeiten | Teams-SDK.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie die folgenden Anforderungen erfüllen:

• Node.js 20 oder höher.
• Ein Microsoft 365-Konto für die Entwicklung.
• Eine Entwicklungsumgebung, die zum Erweitern von Teams-Apps in Microsoft 365 eingerichtet wurde. Nachdem Sie Ihren Entwicklermandanten für das gezielte Office 365-Release registriert haben, kann es einige Tage dauern, bis die Registrierung wirksam wird.
• Teams Developer CLI | Teams-SDK.
• (Optional) Agent-Fähigkeiten | Teams SDK verwenden, damit Ihr KI-Assistent Teams Developer CLI-Workflows in natürlicher Sprache orchestrieren kann.

Führen Sie die folgenden Schritte aus, um eine suchbasierte Nachrichtenerweiterung mit Teams Developer CLI zu erstellen:

1. Teams Developer CLI installieren.

npm install -g @microsoft/teams.cli

Wenn Sie einen KI-Coding-Assistenten verwenden, installieren Sie den teams-devAgent-Skill über Agent-Fähigkeiten | Teams-SDK. Der Skill hilft Ihrem Assistenten, Teams-Developer CLI-Workflows und verwandte App-Verwaltungsaufgaben in natürlicher Sprache zu orchestrieren.

2. Melden Sie sich beim Microsoft 365-Mandanten an.
3. Erstellen oder öffnen Sie Ihr Teams-App-Projekt und konfigurieren Sie die botbasierte Nachrichtenerweiterungsfunktion.
4. Aktualisieren Sie Ihr App-Manifest über die Befehlszeilenschnittstelle oder manuell, um die composeExtensions Definition für einen Suchbefehl hinzuzufügen.
5. Konfigurieren Sie die Befehlsdetails in Ihrem Manifest, einschließlich Befehls-ID, Befehlstitel, Befehlsbeschreibung, Kontext, in dem der Befehl funktioniert, Parametername, Parametertitel, Parameterbeschreibung und Eingabetyp.
6. Packen Sie Ihre App und zeigen Sie eine Vorschau in Teams mithilfe der Teams Developer CLI an.
7. Wechseln Sie in Teams zu einer Chatnachricht, und wählen Sie das Symbol "Aktionen und Apps " aus. Suchen Sie nach Ihrer App.
8. Wählen Sie Ihre Nachrichtenerweiterung aus der Liste aus, und geben Sie einen Suchbefehl in das Suchfeld ein.
9. Wählen Sie einen Eintrag aus der Liste aus. Das Element wird im Bereich zum Verfassen von Nachrichten als adaptive Karte entfaltet.
10. Wählen Sie Senden aus. Teams sendet das Suchergebnis als adaptive Karte in der Chatnachricht.

---

Botbasierte Nachrichtenerweiterung als Agent erweitern

Wichtig

Agents für Microsoft 365 Copilot befinden sich in der Vorschauphase und funktionieren nur in Microsoft 365 Copilot in Teams.

Microsoft 365-Agents ermöglichen die Integration mit verschiedenen Microsoft 365-Produkten wie Teams und Outlook. Die Integration hilft Benutzern beim Suchen oder Erstellen von Inhalten in externen Systemen. Nachrichtenerweiterungs-Agenten ermöglichen es Microsoft 365 Copilot, über einen Bot mit APIs aus anderer Software und Diensten zu interagieren. Wir empfehlen, dass Sie Ihre vorhandenen Nachrichtenerweiterungen erstellen oder aktualisieren, um deren Nützlichkeit und Benutzerfreundlichkeit in Microsoft 365 Copilot zu maximieren. Weitere Informationen finden Sie unter Erweiterung der botbasierten Nachrichtenerweiterung als Agent für Microsoft 365 Copilot.

Codeausschnitte

Der folgende Code enthält ein Beispiel für die suchbasierte Suche nach Nachrichtenerweiterungen:

C# SDK v2.1

• Beispielcodereferenz

teams.OnQuery(async (context, cancellationToken) =>
{ 
  MessageExtensionQuery? value = context.Activity.Value;
  var commandId = value?.CommandId;
  var parameters = value?.Parameters;
    var query = parameters?.FirstOrDefault()?.Value?.ToString() ?? ""; 
 
    Console.WriteLine($"Query: command={commandId}, query={query}"); 
 
    var attachments = new List<TeamsAttachment>(); 
 
    // Route to appropriate search 
    if (commandId == "wikipediaSearch") 
    { 
        var results = await SearchWikipedia(query); 
        attachments = results.Select(r => 
        { 
            var title = r["title"]?.ToString() ?? "No Title"; 
            var snippet = Regex.Replace(r["snippet"]?.ToString() ?? "", "<[^>]+>", ""); 
            return CreateAttachment(CreateWikipediaCard(r), title, snippet); 
        }).ToList(); 
    } 
 
    if (attachments.Count == 0) 
    { 
        return new MsgExt.Response 
        { 
            ComposeExtension = new MsgExt.Result 
            { 
                Type = MsgExt.ResultType.Message, 
                Text = $"No results found for '{query}'" 
            } 
        }; 
    } 
 
    return new MsgExt.Response 
    { 
        ComposeExtension = new MsgExt.Result 
        { 
            Type = MsgExt.ResultType.Result, 
            AttachmentLayout = Attachment.Layout.List, 
            Attachments = attachments 
        } 
    }; 
});

C# SDK<2.1(Vorgänger)

teams.OnQuery(async (ctx) => 
{ 
    var commandId = ctx.Activity.Value.CommandId; 
    var parameters = ctx.Activity.Value.Parameters; 
    var query = parameters?.FirstOrDefault()?.Value?.ToString() ?? ""; 
 
    Console.WriteLine($"Query: command={commandId}, query={query}"); 
 
    var attachments = new List<MsgExt.Attachment>(); 
 
    // Route to appropriate search 
    if (commandId == "wikipediaSearch") 
    { 
        var results = await SearchWikipedia(query); 
        attachments = results.Select(r => 
        { 
            var title = r["title"]?.ToString() ?? "No Title"; 
            var snippet = Regex.Replace(r["snippet"]?.ToString() ?? "", "<[^>]+>", ""); 
            return CreateAttachment(CreateWikipediaCard(r), title, snippet); 
        }).ToList(); 
    } 
 
    if (attachments.Count == 0) 
    { 
        return new MsgExt.Response 
        { 
            ComposeExtension = new MsgExt.Result 
            { 
                Type = MsgExt.ResultType.Message, 
                Text = $"No results found for '{query}'" 
            } 
        }; 
    } 
 
    return new MsgExt.Response 
    { 
        ComposeExtension = new MsgExt.Result 
        { 
            Type = MsgExt.ResultType.Result, 
            AttachmentLayout = Attachment.Layout.List, 
            Attachments = attachments 
        } 
    }; 
});

TypeScript

• Beispielcodereferenz

app.on('message.ext.query', async ({ activity }) => { 
  const commandId = activity.value?.commandId 
  const params = activity.value?.parameters || [] 
  const query = params[0]?.value || '' 
  console.log(`Query: command=${commandId}, query=${query}`) 
  let attachments: MessagingExtensionAttachment[] = [] 
 
  if (commandId === 'wikipediaSearch') { 
    const results = await searchWikipedia(query) 
    attachments = results.map((r: any) => 
      createAttachment( 
        createWikipediaCard(r), 
        r.title, 
        (r.snippet || '').replace(/<[^>]+>/g, '') 
      ) 
    ) 
  } 
 
  if (!attachments.length) { 
    return { 
      composeExtension: { 
        type: 'message', 
        text: `No results found for '${query}'`, 
      }, 
    } 
  } 
 
  return { 
    composeExtension: { 
      type: 'result', 
      attachmentLayout: 'list', 
      attachments, 
    }, 
  } 
})

Python

• SDK-Referenz
• Beispielcodereferenz

@app.on_message_ext_query
async def handle_query(ctx: ActivityContext[MessageExtensionQueryInvokeActivity]):
    command_id = ctx.activity.value.command_id
    params = ctx.activity.value.parameters or []
    query = params[0].value if params else ""

    print(f"Query: command={command_id}, query={query}")

    # Route to appropriate search
    if command_id == "wikipediaSearch":
        results = await search_wikipedia(query)
        attachments = [
            create_attachment(
                create_wikipedia_card(r),
                r["title"],
                re.sub(r"<[^>]+>", "", r.get("snippet", "")),
            )
            for r in results
        ]

    if not attachments:
        return MessagingExtensionResponse(
            compose_extension=MessagingExtensionResult(
                type=MessagingExtensionResultType.MESSAGE,
                text=f"No results found for '{query}'",
            )
        )

    return MessagingExtensionResponse(
        compose_extension=MessagingExtensionResult(
            type=MessagingExtensionResultType.RESULT,
            attachment_layout=MessagingExtensionAttachmentLayout.LIST,
            attachments=attachments,
        )
    )

Codebeispiel

Beispielname	Beschreibung	.NET	Node.js	Python
Bot-Nachrichtenerweiterungen	Dieses Beispiel zeigt eine suchbasierte Messaging-Erweiterung in Microsoft Teams, mit der Benutzer nach Wikipedia-Artikeln suchen können. Die Erweiterung unterstützt Suchbefehle, Elementauswahl und Linkentfaltung.	View	View	View

Nächster Schritt

Reagieren Sie auf Suchbefehle.

Siehe auch

• Teams Developer CLI | Teams-SDK
• Agent-Fähigkeiten | Teams-SDK
• Nachrichtenerweiterungen