Add a REST API as a tool (Customer Conversation) (preview)

[This article is prerelease documentation and is subject to change.]

If the tool you need isn't available as a prebuilt, connector, or workflow tool, you can add a custom tool by importing a REST API from an OpenAPI specification.

Adding a REST API as a tool to an agent powered by the Customer Conversation harness is similar to adding one to an agent powered by the standard harness. To learn more, see Extend your agent with tools from a REST API (preview).

Prerequisites

  • A copy of the OpenAPI specification for the REST API you want to connect to.
  • Knowledge of the type of authentication needed to connect to the API, and the authentication details.

Add a REST API tool

  1. On the Build tab, select the primary agent's card to open its configuration panel. If you've added any sub-agents, select a sub-agent's card instead to configure that sub-agent.

  2. In the Tools section, select Add tool.

  3. In the Add a tool dialog, select the REST API tab (or select Add > REST API).

  4. In the New REST API dialog, complete the following wizard steps:

    1. Upload specification: Import your OpenAPI (Swagger 2.0) or OpenAPI 3.0 specification. Drag and drop a JSON or YAML file (up to 5 MB), or select browse to pick one.

    2. API plugin details: Give your tool a name and description the agent can use to decide when to call it. Review and, if needed, edit the following fields before continuing:

      • Tool name: Initially populated from the title in the API specification you uploaded.
      • Description: Initially populated from the description in the API specification you uploaded. Provide a detailed description, because your agent's orchestration uses it to determine when to use this tool.
      • Solution: Select the Power Platform solution to store this tool in, or leave it blank to let the system create one for you automatically.

    3. Authentication: Choose how the agent authenticates with this API:

      • None: No authentication is required to access the API.
      • API key: Your agent prompts the user to provide an API key at runtime, then connects to the API using that key. You provide a Label (the name shown when connecting), a Parameter name (for example, X-API-Key), and a Location (Header or Query).
      • OAuth 2.0: Users authenticate to the API through an identity provider without sharing their credentials with the agent. You provide values such as Client ID, Client secret, Authorization URL, Token URL, and Refresh URL.

    4. Select tools: Under Available tools, select the plus icon next to each API-supported tool (endpoint and HTTP method combination, such as get, put, post, or delete) that you want to expose to your agent. Use the search box to find a specific operation.

    5. Configure tool: For each tool you select, configure a Tool name and Description. Descriptions are initially populated from the API specification. Provide a detailed description, because your agent's orchestration uses it to determine when to use this specific tool.

    6. Select tool parameters: Review your input and output values and update descriptions as needed. You can update parameter descriptions, but not the parameter values themselves. If any description is blank, complete it before continuing. Repeat the Select tools through Select tool parameters steps for each tool you want to add from the API.

    7. Review: Review the tool name, description, authentication type, and number of tools selected before publishing.

    8. Publish: Select Publish to create the tool and make it available to your agent.

Connect the tool after publishing

Before your agent can use the published tool, you need to create or select a connection for it, regardless of the authentication type you chose, including None.

  1. Select the published tool to add it to your agent.
  2. In the Connect to tool name dialog, select Select a connection, then choose an existing connection, or create a new one:
    1. Select + New connection.
    2. In the Connect to tool name dialog, optionally enter a Display name for the connection. This name appears in the connection list.
    3. Select Create.
  3. Select Add and configure to finish adding the tool to your agent.
  • Last updated on