Define message extension search commands

Note

Agents provide a more flexible, intelligent, and future‑ready experience that enables richer reasoning, simpler development, and better alignment with the evolving Teams and Microsoft 365 platform. We recommend that you explore and build agents.

For more information, see build declarative agents and build agents in Teams.

If you have an existing bot-based message extension, you can extend it as an agent as well.

The search command is invoked from any one or both of the following locations:

Compose message area: The buttons at the bottom of the compose message area.
Command box: By using / in the command box. For example, /your-app-name. If you're using the classic Teams, search command is invoked by @mentioning in the command box. For example, @your-app-name.

When a search command is invoked from the compose message area, the user sends the results to the conversation. When a search command is invoked from the command box, the user interacts with the resulting card or copies it for use elsewhere.

The following image displays the invoke locations of the search command:

Add the search command to your app manifest

To add the search command to your app manifest (previously called Teams app manifest), you must add a new composeExtensions object to the top level of your app manifest JSON. You can add the search command by using Teams Developer CLI or by updating the manifest manually.

Create search message extension using Teams SDK

You can create a search message extension using Teams Developer CLI | Teams SDK and Agent Skills | Teams SDK.

Prerequisites

Before you get started, ensure that you meet the following requirements:

Node.js 20 or later.
A Microsoft 365 account for development.
A dev environment set up for extending Teams apps across Microsoft 365. After you've enrolled your developer tenant in Office 365 Targeted Release, it might take a couple of days for the enrollment to take effect.
Teams Developer CLI | Teams SDK.
(Optional) Agent Skills | Teams SDK to let your AI assistant orchestrate Teams Developer CLI workflows through natural language.

To create a search-based message extension with Teams Developer CLI, follow these steps:

Install Teams Developer CLI.

npm install -g @microsoft/teams.cli

If you're using an AI coding assistant, install the teams-dev agent skill from Agent Skills | Teams SDK. The skill helps your assistant orchestrate Teams Developer CLI workflows and related app management tasks through natural language.

Sign in to your Microsoft 365 tenant.
Create or open your Teams app project and configure bot-based message extension capability.
Using the CLI or manually, update your app manifest to add the composeExtensions definition for a search command.
Configure the command details in your manifest, including command ID, command title, command description, context in which the command works, parameter name, parameter title, parameter description, and input type.
Package and preview your app in Teams using Teams Developer CLI.
In Teams, go to a chat message and select the Actions and apps icon. Search for your app.
Select your message extension from the list and enter a search command in the search box.
Select an item from the list. The item unfurls into an Adaptive Card in the message compose area.
Select Send. Teams sends the search result as an Adaptive Card in the chat message.

Extend bot-based message extension as agent

Important

Agents for Microsoft 365 Copilot are in preview and only work in Microsoft 365 Copilot in Teams.

Microsoft 365 agents provide integration with various Microsoft 365 products, such as Teams and Outlook. The integration helps users to search or create content in external systems. Message extension agents allow Microsoft 365 Copilot to interact with APIs from other software and services through a bot. We recommend that you build or upgrade your existing message extensions to maximize their usefulness and usability in Microsoft 365 Copilot. For more information, see extend bot-based message extension as agent for Microsoft 365 Copilot.

Code snippets

The following code provides an example of search-based for message extensions:

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

Sample code reference

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

@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"&lt;[^&gt;]+&gt;", "", 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,
        )
    )

Code sample

Sample name	Description	.NET	Node.js	Python
Bot Message Extensions	This sample demonstrates a search-based messaging extension in Microsoft Teams that allows users to search for Wikipedia articles. The extension supports search commands, item selection, and link unfurling.	View	View	View

Next step

Respond to search commands.

Feedback

Was this page helpful?

Last updated on 2026-07-20