Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Важно
Плагины MCP и API обеспечивают действия внутри декларативных агентов. Они не являются отдельными устанавливаемыми пакетами плагинов: только агент, содержащий их, может получить доступ к их функциям и инструментам. Сведения об отношении манифеста пакета и действия см. в разделе Подключаемые модули и декларативные действия агента.
Совет
Рекомендуется: Начните с Work IQ Dev Tools для поддерживаемых сценариев декларативного агента и плагинов для кода. См. краткое руководство по WIQD. Инструкции на основе набора средств остаются доступными для существующих проектов и рабочих процессов, для которых они требуются. Перед выбором инструмента проверьте поддержку возможностей и целевого интерфейса : WIQD не нацелен на агентов пользовательской подсистемы.
Подключаемые модули API — это пользовательские действия для декларативных агентов, которые подключают REST API со спецификацией OpenAPI к Microsoft 365 Copilot. В этом руководстве показано, как добавить подключаемый модуль API в декларативный агент с помощью TypeSpec и набора инструментов агентов Microsoft 365.
Необходимые условия
- Требования, указанные в разделе Требования к параметрам расширяемости Copilot
- Существующий REST API (в этом пошаговом руководстве используется API-интерфейс заполнителя JSON)
- Visual Studio Code
- Набор средств для агентов Microsoft 365
- Агент, созданный с помощью набора инструментов агентов Microsoft 365 и TypeSpec для Microsoft 365 Copilot
Совет
Для достижения наилучших результатов убедитесь, что создаваемый API соответствует рекомендациям, описанным в статье "Как сделать документ OpenAPI эффективным при расширении Copilot".
Настройка проекта подключаемого модуля API в VS Code
В этой статье предполагается, что у вас уже есть проект декларативного агента, созданный с помощью набора средств агентов Microsoft 365 и TypeSpec. Вы добавляете подключаемый модуль API в этот проект, определяя его операции REST API в TypeSpec, а затем подготавливая агент. В следующих разделах описывается каждая операция.
- Если у вас еще нет проекта агента, создайте его, следуя инструкциям Создание декларативного агента. При появлении запроса выберите "Начать с TypeSpec" для Microsoft 365 Copilot.
- Откройте проект агента
main.tspв Visual Studio Code и откройте файл в корневой папке проекта. - Определите подключаемый модуль API, добавив операции
main.tsp, как показано в следующих разделах. По завершении подготовьте агент, как описано в статье Подготовка и тестирование пользовательских действий.
Добавление GET операции
Для начала добавьте операцию GET для вывода списка всех элементов записи.
main.tsp Откройте файл и добавьте новое пространство PostsAPI имен в MyAgent пространство имен со следующим содержимым.
// Omitted for brevity
namespace MyAgent {
// Omitted for brevity
@service
@server("https://jsonplaceholder.typicode.com")
@actions(#{
nameForHuman: "Posts APIs",
descriptionForHuman: "Manage blog post items with the JSON Placeholder API.",
descriptionForModel: "Read, create, update and delete blog post items with the JSON Placeholder API."
})
namespace PostsAPI {
/**
* List all blog post items.
*/
@route("/posts")
@get op listPosts(): PostItem[];
/**
* Structure of a blog post item.
*/
model PostItem {
/**
* The ID of the user who created the post.
*/
userId: integer;
/**
* The ID of the post.
*/
@visibility(Lifecycle.Read)
id: integer;
/**
* The title of the post.
*/
title: string;
/**
* The body of the post.
*/
body: string;
}
}
// Omitted for brevity
}
Этот код определяет PostItem модель и REST API GET /posts.
Добавление GET операции с параметром запроса
Операция GET в предыдущем примере не принимает параметров. Чтобы включить фильтрацию по идентификатору пользователя, обновите GET операцию с помощью необязательного параметра запроса, чтобы отфильтровать результаты по идентификатору пользователя.
main.tsp Откройте файл и замените существующую listPosts операцию следующим содержимым.
/**
* List all blog post items.
* @param userId The ID of the user who created the post. If not provided, all posts will be returned.
*/
@route("/posts")
@get op listPosts(@query userId?: integer): PostItem[];
Добавленный @query userId?listPosts параметр обновляет API REST до GET /posts?userId={userId}.
Добавление адаптивной карты в GET операцию
Добавление адаптивной карточки в операцию listPosts изменяет способ отображения цитат в сгенерированном ответе.
Создайте новый файл с именем post-карта.json в каталоге appPackage и добавьте следующее содержимое.
{
"type": "AdaptiveCard",
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
{
"type": "Container",
"$data": "${$root}",
"items": [
{
"type": "TextBlock",
"text": "**${if(title, title, 'N/A')}**",
"wrap": true
},
{
"type": "TextBlock",
"text": "${if(body, body, 'N/A')}",
"wrap": true
}
]
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Read More",
"url": "https://www.bing.com/search?q=https://jsonplaceholder.typicode.com/posts/${id}"
}
]
}
main.tsp Откройте файл и добавьте @card декоратор в listPosts операцию, как показано в следующем фрагменте кода.
/**
* List all blog post items.
* @param userId The ID of the user who created the post. If not provided, all posts will be returned.
*/
@route("/posts")
@card(#{ dataPath: "$", file: "post-card.json", properties: #{ title: "$.title" } })
@get op listPosts(@query userId?: integer): PostItem[];
Добавление POST операции
main.tsp Откройте файл и добавьте PostsAPI в пространство имен следующее содержимое.
/**
* Create a new blog post item.
* @param post The post item to create.
*/
@route("/posts")
@post op createPost(@body post: PostItem): PostItem;
Этот код определяет REST API POST /posts, который создает новую запись блога.
Добавление PATCH операции
main.tsp Откройте файл и добавьте PostsAPI в пространство имен следующее содержимое.
/**
* Updates a blog post item.
* @param id The ID of the post to update.
* @param post The updated post item.
*/
@route("/posts/{id}")
@patch op updatePost(@path id: integer, @body post: PostItem): PostItem;
Этот код определяет REST API PATCH /posts/{id}, который обновляет существующую запись блога.
Добавление DELETE операции
main.tsp Откройте файл и добавьте PostsAPI в пространство имен следующее содержимое.
/**
* Deletes a blog post item.
* @param id The ID of the post to delete.
*/
@route("/posts/{id}")
@delete op deletePost(@path id: integer): void;
Этот код определяет REST API DELETE /posts/{id}, который удаляет существующую запись блога.
Подготовка и тестирование настраиваемых действий
Используйте панель жизненного цикла в наборе инструментов агентов Microsoft 365 для подготовки агента и его подключаемого модуля API, а затем протестируйте настраиваемые действия в Microsoft 365 Copilot.
- Выберите значок набора средств агентов Microsoft 365 на панели действий слева.
- На панели "Жизненный цикл " выберите "Подготовка".
- Дождитесь завершения подготовки, а затем откройте https://m365.cloud.microsoft/ браузер.
- Выберите своего агента в списке агентов.
- Протестируйте агент с помощью следующих запросов или попробуйте использовать собственные.
Тестирование операции GET
Запрос: "Перечисли все записи блога и отобрази их в виде таблицы".
Запрос: "Перечислить все записи блога для пользователя с идентификатором 1 и отобразить их в виде таблицы".
Проверка операции POST
Запрос: "Создай новую запись блога с идентификатором пользователя 1, заголовком "Новая запись" и текстом "Это новая запись"".
Тестирование операции PATCH
Запрос: "Обновите запись блога с помощью идентификатора 30 и измените заголовок на "Обновленный заголовок", а текст на "Обновленный текст"".
Проверка операции DELETE
Запрос: "Удалить запись блога с идентификатором 50".
Пример полного main.tsp файла
Ниже приведен пример полного main.tsp файла с добавлением GET, POST, PATCHи DELETE операций.
import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
using TypeSpec.Http;
using TypeSpec.M365.Copilot.Actions;
using TypeSpec.M365.Copilot.Agents;
@agent(
"My Posts Agent",
"Declarative agent focusing on blog posts management."
)
@instructions("""
You should help users with blog posts management.
You can read, create, update and delete blog post items.
You can also search for blog posts by user ID.
""")
@conversationStarter(#{
title: "List Blog Posts",
text: "List all blog posts and render them as a table."
})
@conversationStarter(#{
title: "Lists a user's blog posts",
text: "List all blog posts for the user with ID 1 and render them as a table."
})
@conversationStarter(#{
title: "Delete a blog post",
text: "Delete the blog post with ID 50."
})
@conversationStarter(#{
title: "Update a blog post",
text: "Update the blog post with ID 30 and update the title to 'Updated Title' and body to 'Updated Body'."
})
@conversationStarter(#{
title: "Create a blog post",
text: "Create a new blog post with user ID 1, title 'New Post' and body 'This is a new post'."
})
@conversationStarter(#{
title: "Get a blog post",
text: "Get all the details about the blog post with ID 10."
})
namespace MyAgent {
@service
@server("https://jsonplaceholder.typicode.com")
@actions(#{
nameForHuman: "Posts APIs",
descriptionForHuman: "Manage blog post items on JSON Placeholder APIs.",
descriptionForModel: "Read, create, update and delete blog post items on the JSON Placeholder APIs."
})
namespace PostsAPI {
/**
* List all blog post items.
* @param userId The ID of the user who created the post. If not provided, all posts will be returned.
*/
@route("/posts")
@card(#{ dataPath: "$", file: "post-card.json", properties: #{ title: "$.title" } })
@get op listPosts(@query userId?: integer): PostItem[];
/**
* Get a blog post item by ID.
*/
@route("/posts/{id}")
@card(#{ dataPath: "$", file: "post-card.json", properties: #{ title: "$.title" } })
@get op getPost(@path id: integer): PostItem;
/**
* Create a new blog post item.
* @param post The post item to create.
*/
@route("/posts")
@post op createPost(@body post: PostItem): PostItem;
/**
* Updates a blog post item.
* @param id The ID of the post to update.
* @param post The updated post item.
*/
@route("/posts/{id}")
@patch op updatePost(@path id: integer, @body post: PostItem): PostItem;
/**
* Deletes a blog post item.
* @param id The ID of the post to delete.
*/
@route("/posts/{id}")
@delete op deletePost(@path id: integer): void;
model PostItem {
/**
* The ID of the user who created the post.
*/
userId: integer;
/**
* The ID of the post.
*/
@visibility(Lifecycle.Read)
id: integer;
/**
* The title of the post.
*/
title: string;
/**
* The body of the post.
*/
body: string;
}
}
}