Extend your agent with actions from a REST API (preview)

You can use REST APIs (including OpenAI API) to connect an agent you create with external systems and access available data for use within your agent. You can connect your agent to a REST API by providing Copilot Studio with three things:

• An OpenAPI specification defining the API’s functions and available actions
• Details on the type of authentication needed and the authentication details for users to connect to the API to access the external system
• Descriptions to help the language model determine when to invoke the API to utilize the data

REST APIs can be added to Copilot agents and custom agents through Copilot Studio.

Copilot agents allow a maker to combine multiple data sources like connectors, APIs, prompts, and knowledge sources into a single agent. You can use this agent to extend Microsoft-branded agent experiences like Microsoft 365 Copilot.

Custom agents are standalone agents that contain connectors, APIs, prompts, and knowledge sources. You can use custom agents directly by integrating them into websites or other channels.

Prerequisites

A few prerequisites are needed to extend Microsoft-branded agent experiences with connector actions.

For all agent experience types, you must have maker-level credentials, and a Copilot Studio license.

You also need a copy of the OpenAPI specification, knowledge of the type of authentication needed, and the authentication details.

Add a REST API action to an agent

Adding a REST API to your agent involves a few steps. The following sections walk you through the process.

The process to add a REST API is identical for both custom and Copilot agents.

There are a few steps in the process.

Add an action to the agent

1. Start at the Overview page of your agent.

   

2. In the Actions section, select Add Action. You can also go to the Actions tab and select Add Action.

   

   The action creation wizard is launched with the Choose an action page displayed.

Provide API specification, description, and solution

1. At the bottom of the page select Add an API for a Custom Connector.

   

2. Upload an OpenAPI specification file for the REST API you want to connect to. You can either drag and drop the specification file into the Upload a REST API screen or browse your system to locate the file you wish to use.

   

   Note

   The OpenAPI specification must be a JSON file in v2 format. If a v3 specification is submitted, it's automatically translated to a v2 specification during the creation process.

   After you upload the specification, the screen updates to indicate the specification file name and the details.

   

   In the steps that follow, we ground the procedure in a specific example of SunnyADO, an ADO ticket management system. In the example, the intention is to allow the users to retrieve and update their tickets via the agent.

3. Verify the details, then select Next.

   You're presented with an API plugin details page where you can provide additional information about the API.

   

   The description field is initially be populated based on the description in the API specification you uploaded. Provide a detailed description, because your agent orchestration uses the description to determine when to use the particular action. Provide details, including synonyms, to help your agent with the selection process.

   For example, the initial description provided is: "A simple service to manage tickets."

   A better description is: "A system used to get, retrieve, find, and display existing tickets from SunnyADO. It allows users to update, change, and manage tickets to provide more data to improve the records."

4. Enter an improved description under the Description field.

5. Under Solution, a dropdown lists all solutions available within the current environment. Select the solution you want to use. For more information on what solutions are, see Solution concepts.

   

   If you have a preferred solution, or your selected connector is already in the solution, that solution is automatically selected.

   You can either select a solution or leave it blank. If you leave the solution blank, a solution is created for you with the action name and default publisher. Storing your action in a solution lets you move it easily across environments.

   Note

   If you don't see the default solution or the CDS default solution as an option in this case as we recommend having a custom solution for easy management. For more information, see: Default solution vs. custom solution.

6. With a solution selected, select Next to proceed.

Provide authentication details

The Authentication page is displayed, to select which type of authentication to use for the API.

1. Select an authentication method from the list.

2. Fill in the required fields for the authentication method. The fields vary based on the authentication method.

   • None: No other fields are required.
   • API key:
     • Parameter Label: A text label for the API parameter.
     • Parameter Name: A text name for the API parameter.
     • Parameter Location: The position where the parameter can be found.
   • Auth 2.0:
     • Client ID: Client GUID for the target service.
     • Client Secret – Secret value for the client. The secret isn't displayed when the user opens up the edit panel afterwards. However, store the secret, because you'll need it if you choose to make further edits.
     • Authorization URL: URL used to authorize the source system.
     • Token URL: URL where the token can be retrieved.
     • Refresh URL: What URL you're redirected to in a refresh scenario.
     • Scope: The Scope URL assigned to the API for Microsoft Entra apps.
     • Which Microsoft 365 organization accesses the endpoints: This limits access to the source to either the organization of the maker, or all organizations.
     • Which app (Client) can use the endpoints: GUID that defines the client system that can be used to access this data. Apps could include Microsoft 365, Power Automate, and other options.

3. Once all fields are completed, select Next.

   You're presented with a Select and configure your plugin action page where you can select actions to enable for the API.

   

Select actions for the API

Choose the API-supported actions to enable. Generally, a REST API offers a range of actions through the various combinations of endpoint and HTTP method (get, put, post, delete, and so on) defined in the API specification. In some cases, you might not want the agent's users to have the ability to execute every action the API generally offers. For example, your API specification might include actions to update and delete but you only want users of your agent to be able to create records.

1. Select an action from the list to configure.

   The Configure your plugin action page is displayed.

   

2. Configure the selected action. As with the overall API, you're asked to provide an Action name and Action description. Descriptions are initially prepopulated from the descriptions in the API specification. The name doesn't need to be unique but it should represent the action itself. The description, as with the overall API description, should be specific enough to provide the language model with details to better identify that your query aligns with this specific action.

3. Once the fields are completed, select Next.

   The Review your action's parameters page is displayed.

   

   This page shows the values provided as part of the possible input and output values. These values can't be changed, however, the descriptions of the inputs and outputs can be updated. All content in this page is pulled directly from the uploaded API specification.

4. Fill in values as needed for the descriptions. The descriptions provide a definition of what the values are used for. If any of the descriptions are blank, they must be completed before you can move forward. You can paste in the name if you don’t have a better description.

5. After completing the descriptions, select Next.

   The first action is now configured and appears in the list of Selected actions on the Select and configure your plugin action page.

   

6. Add in any other actions you wish to include at this time. Once you're done adding actions you want your agent to support, select Next.

   The Review your action page is displayed. The page provides the details of the configured REST API action.

   

Review and publish

1. If you need to make any updates, you can select Back and make your changes. Otherwise, select Next.

   A screen is presented indicating that your action is being published while the process is being completed. You're informed once the publish is complete.

2. After publishing completes, you're returned to the Choose an Action screen. Here you can add the newly configured REST API into your Copilot agent or custom agent and complete the configuration of the component.

   

The REST API action is now available for use in your agent.