Challenge project - Build a declarative agent to chat with your data

challenge.md

Introduction

Using agents you create AI-powered assistants optimized for specific scenarios in Microsoft 365 Copilot. With instructions, you define the context for the agent and specify settings such as tone of voice or how it should respond. By configuring the agent's skills, you give it the ability to interact with external systems, trigger certain behavior under system conditions, or use custom workflow logic. One type of skill is actions that allow a declarative agent to communicate with APIs both for retrieving and modifying data.

Example scenario

Suppose you work in the sales department for Northwind Traders. You regularly need to check the status of orders and customers. You want to be able to quickly see what orders are pending, but also consider customer details in case you have questions. The Northwind Traders API exposes their data via an API. Rather than building a separate app, you want to build an agent for Microsoft 365 Copilot so that you can easily find the available orders and customer details. You want to use natural language to browse through the data and get answers.

What will we be doing?

Here, you create a declarative agent with an API plugin. The action allows the agent to interact with an external system using its anonymous API.

What is the main goal?

By the end of this module, you'll demonstrate your ability to create a declarative agent for Microsoft 365 Copilot that access data from an external API.

Prepare

You'll be building a declarative agent for Microsoft 365 Copilot that's answers a user's questions using your data. Here, we discuss the project business logic and target behavior. We also cover the accounts and software you'll need.

Project specification

You have an OpenAPI specification for your API.

The API specification:

• only contains the relevant operations
• includes relevant descriptions to explain the purpose of each operation, parameter and property

The declarative agent:

• is available within Microsoft 365 Copilot
• provides examples of how users can ask it questions
• answers a user's questions using the information from the referenced API
• displays the data from the API using an Adaptive Card
• displays relevant information in citations
• politely refuses answering questions not related to its function
• admits when it doesn't have relevant information to answer a user's question

Setup

To complete this challenge, you need a Microsoft 365 tenant with Microsoft 365 Copilot, Visual Studio Code and the Teams Toolkit extension.

Get a Microsoft 365 tenant with Microsoft 365 Copilot

To complete this exercise, you need a Microsoft 365 tenant with Microsoft 365 Copilot.

Northwind Traders API

Here we provide a sample API for you to use in the challenge. The Northwind Traders API is a sample OData service that provides access to data about products, customers, and orders. You can use this API to test your declarative agent.

The following is an example of how to call the Northwind Traders API to get a list of customers in JSON format:

GET https://services.odata.org/northwind/northwind.svc/Customers
accept: application/json

Tip

Use Dev Proxy to easily generate an OpenAPI spec for your API

Install Visual Studio Code

You'll build the agent using Visual Studio Code. Visual Studio Code is an IDE that provides you with tooling to build agents for Microsoft 365 Copilot. To install Visual Studio Code for your operating system, visit https://code.visualstudio.com/.

Install Teams Toolkit extension for Visual Studio Code

Teams Toolkit is a Visual Studio Code extension that helps developers build agents for Microsoft 365 Copilot. It provides you with the project boilerplate and tasks to automate building and deploying agents. To install the Teams Toolkit extension for Visual Studio Code visit https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension.

Exercise - Create OpenAPI document

The sales department needs an agent that answers their questions using information from your data. Here, you build an API specification which you need to integrate the agent with the API action. You'll validate how it's working against requirements to check your work.

Specification

You have an OpenAPI specification for your API.

The API specification:

• only contains the relevant operations
• includes relevant descriptions to explain the purpose of each operation and parameter

Check your work

At this point, you have an OpenAPI specification for your API. The API contains the necessary information so that it can be used by the declarative agent.

1. You have a valid Open API specification in JSON or YAML.
2. The API specification only contains the relevant operations.
3. Each operation in the API specification includes a meaningful summary and description.
4. Each parameter includes a meaningful description.
5. In each response, each property includes a meaningful description.

Exercise - Start building your declarative agent

The sales department needs an agent that answers their questions using information from your data. Here, you start building a declarative agent. You'll validate how it's working against requirements to check your work.

Specification

The declarative agent:

• is available within Microsoft 365 Copilot
• provides examples of how users can ask it questions
• politely refuses answering questions not related to its function

Check your work

At this point, you have a declarative agent with custom instructions and examples of questions that the users might ask. The agent is visible in Microsoft 365 Copilot chat.

1. Navigate to Microsoft 365 Copilot chat. Is your agent visible?
2. In Microsoft 365 Copilot chat, navigate to the agent. Does it show examples of the questions that a user might ask?
3. Ask a question not related to Northwind Traders. Does the agent politely refuse to answer it?

Exercise - Create an action

The sales department needs an agent that answers their questions using information from your data. Here, you start building an action to access data from an external API. You'll validate how it's working against requirements to check your work.

Specification

The declarative agent:

• answers a user's questions using the information from the referenced API
• displays relevant information in citations

Check your work

At this point, you have a declarative agent with custom instructions and examples of questions that the users might ask, and an action that can access data from an external API.

1. Ask a question related to Northwind Traders customers. Does the agent return the relevant information from the API?
2. Ask a question related to Northwind Traders orders. Does the agent return the relevant information from the API?
3. When the agent returns the relevant information, does it display relevant information on the citation?

Exercise - Enhance action responses with Adaptive Cards

The sales department needs an agent that answers their questions using information from your data. Here, you enhance the responses returned by the API with Adaptive Cards. You'll validate how it's working against requirements to check your work.

Specification

The declarative agent:

• displays the data from the API using an Adaptive Card

Check your work

At this point, you have a declarative agent with custom instructions and examples of questions that the users might ask, and an action that can access data from an external API that uses Adaptive Cards in its responses.

1. Ask a question related to Northwind Traders about a specific customer. Does the agent return the relevant about the customer in a single Adaptive Card?
2. Ask a question related to Northwind Traders about recent orders. Does the agent return a response about several orders, and when you hover over a citation marker, does it show the relevant order information in an Adaptive Card?