Step by step guide to integrate Microsoft 365 Copilot declarative agents with Azure AI Search
Introduction
In this post, I’ll walk you through how to call Azure AI Search APIs from a M365 Copilot declarative agent without writing any code by using Microsoft 365 Agents Toolkit. Leveraging OpenAPI specifications, Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) enables seamless integration with Azure AI Search, streamlining the development process for Copilot extensibility.
Waldek Mastykarz wrote an insightful post on when Azure AI Search can be used, highlighting its ability to provide a more controlled approach to indexing and relevance without the complexity of building a custom engine agent. You can read more here: Integrate Microsoft 365 Copilot Declarative Agents with Azure AI Search.
Image courtesy of Waldek’s post mentioned above:
Step 1: Create and Import an OpenAPI Specification
To generate an OpenAPI spec for Azure AI Search, I used Copilot to create a starter OpenAPI spec by providing the endpoint URL and a sample request body as a prompt. This trimmed version was then imported into Microsoft 365 Agents Toolkit as a declarative action.
Sample Endpoint and Request Body
Endpoint URL:https://aivolunteeringsearch.search.windows.net/indexes/vol/docs/search
Request Body Example:
{
"count": true,
"vectorQueries": [
{
"kind": "text",
"text": "SearchText",
"fields": "contentVector"
}
]
}
Save the generated OpenAPI spec to a local file.
Importing the Azure AI Search OpenAPI Spec
You can import the spec directly into Microsoft 365 Agents Toolkit when creating a declarative agent with an action. Follow the steps shown in the animated image below (note: the example refers to Azure OpenAI, but the process is the same for Azure AI Search):
Call the API from the agent
Once imported, you can invoke the Azure AI Search API after provisioning the solution.
Step 2: Sample OpenAPI Specification
Here’s a trimmed-down OpenAPI spec that targets the indexes/vol/docs/search endpoint. It uses the parameter ${{api-version}} to dynamically pull values from your .env file:
Note Any parameters passed within the path (e.g., /indexes/vol/docs/search?api-version=2025-03-01-preview) are removed unless explicitly specified.
Sample OpenAPI Spec
openapi: 3.0.0
info:
title: AI Volunteering Search API
description: An API for searching volunteer opportunities using vector queries.
version: 1.0.0
servers:
- url: https://aivolunteeringsearch.search.windows.net
description: Azure AI Volunteering Search Service
paths:
/indexes/vol/docs/search:
post:
summary: Search volunteer opportunities
description: Retrieves volunteer opportunities using vector-based queries.
operationId: searchVolunteerOpportunities
tags:
- Volunteer Opportunities
parameters:
- name: api-version
in: query
required: true
schema:
type: string
default: 2025-03-01-preview
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
count:
type: boolean
example: true
vectorQueries:
type: array
items:
type: object
properties:
kind:
type: string
example: text
text:
type: string
example: Azure API Management
fields:
type: string
example: body_vector
responses:
"200":
description: Successful response
content:
application/json:
schema:
type: object
properties:
value:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
description:
type: string
location:
type: string
date:
type: string
format: date-time
"400":
description: Bad Request
"500":
description: Internal Server Error
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api-key
Caveats
I attempted to template the path to avoid hardcoding values and instead use variables defined in the .env file. Unfortunately, this approach did not work as expected.
This issue is surprising since API server templating is supported, as outlined in API Server and Base Path and Path Templating.
The workaround is to hard code the Server Url property for now until it’s supported or I get it to work.
Step 3: Set Up Azure AI Search
To use the Azure AI Search spec, follow these steps:
- Create an Azure AI Search Resource
Set up an Azure AI Search in Azure portal.
- Create an index uploading files
Upload files to create an index.
- Copy the Endpoint and Key
Retrieve the endpoint URL and API key from your Azure AI Search resource.
Step 4: Register the API Key in Teams Developer tools
- Go to Teams developer portal
- Navigate to Tools > API Key registration with the following information:
- Register your API:
- API key: Add a secret with the Azure AI Services Key you copied in step 4
- API key name: e.g., Azure AI Services Key Name
- Base URL: The Azure AI Services Endpoint URL you copied in step 4
- Target tenant: Home tenant
- Restrict usage by app: Any Teams app (when agent is deployed, use the Teams app ID)
Save the information. A new API key registration ID will be generated. Copy the key.
Step 5: Configure .env File
Define the following variables in your .env file and set the APIKEYAUTH_REGISTRATION_ID_FOR_AISEARCH to the key copied in previous step :
RESOURCE_NAME=aivolunteeringsearch #attempt to refer to the resource name within the openapi spec in vain
APIKEYAUTH_REGISTRATION_ID_FOR_AISEARCH= xxxxxxx
Step 6: Configure ai-plugin.json
Update the reference_id to the key copied in the step ‘Register the API Key in Teams Developer tools’ to reference the API key registration.
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "ApiKeyPluginVault",
"reference_id": "${{APIKEYAUTH_REGISTRATION_ID_FOR_AISEARCH}}"
},
"spec": {
"url": "apiSpecificationFile/openapi.yaml"
},
"run_for_functions": [
"getVolunteeringOpportunities"
]
}
]
Step 8: Update OpenAI Spec Server API URL
To ensure the OpenAPI specification correctly references your Azure AI Search resource, update the server URL in the OpenAPI spec. This step is crucial for aligning the API calls with your deployed model and endpoint configuration.
Replace the placeholder server URL with the actual endpoint URL of your Azure AI Search resource. For example:
servers:
- url: https://<your-resource-name>.openai.azure.com
description: Azure AI Search service endpoint
Solution Download
📦 You can download the solution from !Declarative Agent - Volunteering App I built with Lee Ford Azure AI Search
Azure AI Search Advantages over current solutions:
As mentioned in Waldek’s post Integrate Microsoft 365 Copilot declarative agents with Azure AI Search the advantages are:
Provides full control over indexing and allows defining custom ranking models.
Supports lexical, semantic, vector, and hybrid search strategies to fit different business needs.
Adds extra knowledge to Copilot
Conclusion
Using Microsoft 365 Agents Toolkit and OpenAPI specifications, you can easily integrate Azure AI Search services as plugin/action into your Copilot agent authenticated with API Key.
References
- Copilot
- Declarative Agent
- Azure AI Search
- Teams Toolkit
- M365 Copilot Extensibility
- OpenAPI
- Authentication
- ttk
- atk
- Microsoft 365 Agents Toolkit