Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Importante
Os plug-ins MCP e API fornecem ações dentro de agentes declarativos. Eles não são pacotes de plug-in instaláveis autônomos: apenas o agente de contenção pode acessar suas funções e ferramentas. Para obter informações sobre a relação de manifesto de pacote e ação, consulte Plug-ins e ações de agente declarativo.
Dica
Recomendado: Comece com o Work IQ Dev Tools para cenários de agente declarativo e plug-in pro-código suportados. Consulte o guia de início rápido do WIQD. As instruções baseadas em toolkits permanecem disponíveis para projetos e fluxos de trabalho existentes que o exigem. Verifique o suporte à capacidade e à experiência de destino antes de escolher uma ferramenta: o WIQD não tem como alvo agentes de mecanismo personalizados.
Os plug-ins de API são ações personalizadas para agentes declarativos que conectam uma API REST com uma especificação OpenAPI para Microsoft 365 Copilot. Este guia demonstra como adicionar um plug-in de API a um agente declarativo usando o TypeSpec e o Microsoft 365 Agents Toolkit.
Pré-requisitos
- Requisitos especificados em Requisitos para opções de extensibilidade do Copilot
- Uma API REST existente (esta explicação passo a passo usa a API de Marcador de Posição JSON)
- Visual Studio Code
- Kit de Ferramentas de Agentes do Microsoft 365
- Um agente criado com o Microsoft 365 Agents Toolkit e o TypeSpec para Microsoft 365 Copilot
Dica
Para obter os melhores resultados, certifique-se de que a API que está a gerar segue as diretrizes detalhadas em Como tornar um documento OpenAPI eficaz na extensão do Copilot.
Configurar o projeto de plug-in da API no VS Code
Este artigo pressupõe que você já tenha um projeto de agente declarativo que foi criado com o Microsoft 365 Agents Toolkit e TypeSpec. Você adiciona um plug-in de API a esse projeto definindo suas operações de API REST em TypeSpec e, em seguida, provisionando o agente. As secções seguintes explicam cada operação.
- Se você ainda não tiver um projeto de agente, crie um seguindo Criar um agente declarativo. Quando solicitado, selecione Iniciar com TypeSpec para Microsoft 365 Copilot.
- Abra seu projeto de agente no Visual Studio Code e abra o
main.tsparquivo na raiz do projeto. - Defina seu plug-in de API adicionando operações, conforme
main.tspmostrado nas seções a seguir. Quando terminar, provisione o agente conforme descrito em Provisionar e teste as ações personalizadas.
Adicionar uma GET operação
Para começar, adicione uma GET operação para listar todos os itens de lançamento. Abra o main.tsp arquivo e adicione um novo namespace PostsAPI no MyAgent namespace com o seguinte conteúdo.
// 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
}
Este código define o PostItem modelo e a API GET /postsREST.
Adicionar uma GET operação com um parâmetro de consulta
A GET operação no exemplo anterior não precisa de parâmetros. Para ativar a filtragem por ID de utilizador, atualize a GET operação com um parâmetro de consulta opcional para filtrar os resultados por ID de utilizador.
Abra o main.tsp ficheiro e substitua a operação existente listPosts pelo seguinte conteúdo.
/**
* 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[];
O @query userId? parâmetro adicionado à listPosts atualização da API REST para GET /posts?userId={userId}.
Adicionar um card adaptável a uma GET operação
Adicionar um Cartão Adaptável à listPosts operação altera a forma como as citações na resposta gerada são processadas.
Crie um novo arquivo chamado post-card.json no diretório appPackage e adicione o seguinte conteúdo.
{
"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}"
}
]
}
Abra o main.tsp arquivo e adicione o @card decorador à listPosts operação, conforme mostrado no trecho de código a seguir.
/**
* 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[];
Adicionar uma POST operação
Abra o main.tsp ficheiro e no espaço de PostsAPI nomes, adicione o seguinte conteúdo.
/**
* Create a new blog post item.
* @param post The post item to create.
*/
@route("/posts")
@post op createPost(@body post: PostItem): PostItem;
Esse código define a API POST /postsREST, que cria uma nova postagem no blog.
Adicionar uma PATCH operação
Abra o main.tsp ficheiro e no espaço de PostsAPI nomes, adicione o seguinte conteúdo.
/**
* 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;
Esse código define a API PATCH /posts/{id}REST, que atualiza uma postagem de blog existente.
Adicionar uma DELETE operação
Abra o main.tsp ficheiro e no espaço de PostsAPI nomes, adicione o seguinte conteúdo.
/**
* Deletes a blog post item.
* @param id The ID of the post to delete.
*/
@route("/posts/{id}")
@delete op deletePost(@path id: integer): void;
Esse código define a API DELETE /posts/{id}REST, que exclui uma postagem de blog existente.
Aprovisionar e testar as ações personalizadas
Utilize o painel Ciclo de Vida no Microsoft 365 Agents Toolkit para aprovisionar o seu agente e o plug-in de API e, em seguida, teste as ações personalizadas no Microsoft 365 Copilot.
- Selecione o ícone do Microsoft 365 Agents Toolkit na barra de atividade do lado esquerdo.
- No painel Ciclo de Vida , selecione Provisão.
- Aguarde a conclusão do aprovisionamento e, em seguida, abra-o https://m365.cloud.microsoft/ no seu browser.
- Selecione o seu agente na lista de agentes.
- Teste o agente com os seguintes pedidos ou tente o seu próprio.
Testar a operação GET
Prompt: "Liste todas as mensagens do blogue e transforme-as numa tabela."
Prompt: "Liste todas as postagens do blog do usuário com ID 1 e as renderize como uma tabela."
Testar a operação POST
Prompt: "Crie uma nova postagem no blog com ID de usuário 1, título 'Nova postagem' e corpo 'Esta é uma nova postagem'."
Testar a operação PATCH
Prompt: "Atualize a postagem do blog com ID 30 e atualize o título para 'Título atualizado' e o corpo para 'Corpo atualizado'."
Testar a operação DELETE
Prompt: "Elimina a publicação de blogue com ID 50."
Exemplo de um ficheiro completo main.tsp
Segue-se um exemplo de um ficheiro completo main.tsp com as GEToperações , POST, PATCHe DELETE adicionadas.
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;
}
}
}