Criar agentes declarativos com o Teams Toolkit
Um agente declarativo é uma versão personalizada do Microsoft 365 Copilot que permite aos utilizadores criar experiências personalizadas ao declarar instruções, ações e conhecimentos específicos. Este guia fornece informações sobre como criar um agente declarativo com o Teams Toolkit.
O agente que criar neste tutorial destina-se a utilizadores licenciados Microsoft 365 Copilot. Também pode criar agentes para Microsoft 365 Copilot Chat utilizadores, com capacidades limitadas. Para obter detalhes, veja Capacidades do agente para utilizadores do Microsoft 365.
Para obter informações gerais, veja Agentes declarativos para Microsoft 365 Copilot.
Observação
Os agentes declarativos baseados em Microsoft 365 Copilot são agora suportados no Word e no PowerPoint.
Pré-requisitos
Antes de começar, certifique-se de que Microsoft 365 Copilot está disponível para a sua organização.
As seguintes opções estão disponíveis para o seu ambiente de desenvolvimento:
- Uma organização do Microsoft 365 de sandbox com o Copilot (disponível em pré-visualização limitada através da associação tap).
- Um ambiente de produção do Microsoft 365 ou Office 365 elegível com uma licença de Microsoft 365 Copilot.
São necessários os seguintes recursos para concluir os passos descritos neste artigo:
- Teams Toolkit Visual Studio Code versão 5.10.0 ou posterior
- Kiota Visual Studio Code versão 1.19.1000000002 ou posterior
Deve estar familiarizado com as seguintes normas e diretrizes para agentes declarativos para Microsoft 365 Copilot:
- Normas de conformidade, desempenho, segurança e experiência de utilizador descritas nas diretrizes de validação da Loja Teams.
Criar um agente declarativo
Comece por criar um agente declarativo básico.
Abra o Visual Studio Code.
Selecione Teams Toolkit > Criar uma Nova Aplicação.
Selecione Agente.
Selecione Agente Declarativo.
Selecione Sem plug-in para criar um agente declarativo básico.
Selecione Pasta predefinida para armazenar a pasta raiz do projeto na localização predefinida.
Introduza
My Agentcomo o Nome da Aplicação e prima Enter.Na nova janela Visual Studio Code que é aberta, selecione Teams Toolkit e, em seguida, selecione Aprovisionar no painel Ciclo de Vida.
Testar o agente
Navegue para a aplicação Copilot com o URL https://m365.cloud.microsoft/chat.
Junto ao botão Novo Chat , selecione o ícone da gaveta de conversação.
Selecione o agente declarativo O Meu Agente.
Introduza uma pergunta para o seu agente declarativo e certifique-se de que responde com "Obrigado por utilizar o Teams Toolkit para criar o seu agente declarativo!"
Adicionar instruções
Nesta secção, vai adicionar instruções ao agente para alterar o seu comportamento.
Abra o
appPackage/instructions.txtficheiro e substitua o respetivo conteúdo pelo seguinte texto.You are a declarative agent and were created with Team Toolkit. You are an expert at creating poems. Every time a user asks a question, you **must** turn the answer into a poem. The poem **must** not use the quote markdown and use regular text.Os conteúdos deste ficheiro são inseridos na
instructionspropriedade no manifesto do agente durante o aprovisionamento. Para obter mais informações, veja Objeto de manifesto do agente declarativo.Selecione Aprovisionar no painel Ciclo de Vida do Teams Toolkit.
O agente declarativo utilizará as instruções atualizadas depois de recarregar a página.
Adicionar iniciadores de conversação
Nesta secção, vai adicionar iniciadores de conversação ao seu agente. Os iniciadores de conversação são sugestões que são apresentadas ao utilizador para demonstrar como podem começar a utilizar o agente declarativo.
Abra o
appPackage/declarativeAgent.jsonficheiro e adicione aconversation_startersmatriz com o seguinte conteúdo:"conversation_starters": [ { "title": "Getting Started", "text": "How can I get started with Teams Toolkit?" }, { "title": "Getting Help", "text": "How can I get help with Teams Toolkit?" } ]Para obter mais informações, veja Objeto Iniciadores de conversação.
Selecione Aprovisionar no painel Ciclo de Vida do Teams Toolkit.
Os iniciadores de conversação atualizados estarão disponíveis no seu agente declarativo depois de atualizar a página.
Adicionar conteúdo Web
Nesta secção, vai adicionar a capacidade de pesquisar na Web ao agente.
Abra o
appPackage/declarativeAgent.jsonficheiro e adicione acapabilitiesmatriz com o seguinte conteúdo."capabilities": [ { "name": "WebSearch" } ]Para obter mais informações, veja Objeto de pesquisa na Web.
Selecione Aprovisionar no painel Ciclo de Vida do Teams Toolkit.
O agente declarativo terá acesso ao conteúdo Web para gerar as respetivas respostas depois de recarregar a página.
Adicionar conteúdo do OneDrive e do SharePoint
Nesta secção, vai adicionar os conteúdos de um site do SharePoint aos conhecimentos disponíveis para o agente.
Abra o
appPackage/declarativeAgent.jsonficheiro e atualize acapabilitiesmatriz para o seguinte valor, substituindohttps://contoso.sharepoint.com/sites/ProductSupportpor um URL de site do SharePoint na sua organização do Microsoft 365."capabilities": [ { "name": "WebSearch" }, { "name": "OneDriveAndSharePoint", "items_by_url": [ { "url": "https://contoso.sharepoint.com/sites/ProductSupport" } ] } ]Para obter mais informações, consulte OneDrive e objeto do SharePoint.
Observação
- Os URLs devem ser o caminho completo para itens do SharePoint (site, biblioteca de documentos, pasta ou ficheiro). Pode utilizar a opção "Copiar ligação direta" no SharePoint para obter o caminho completo ou ficheiros e pastas. Para tal, clique com o botão direito do rato no ficheiro ou pasta e selecione Detalhes. Navegue para Caminho e clique no ícone de cópia.
- Não especificar a
items_by_urlmatriz (ou a matriz alternativaitems_by_sharepoint_ids) faz com que todos os conteúdos do OneDrive e do SharePoint na sua organização do Microsoft 365 que estejam disponíveis para o utilizador com sessão iniciada estejam disponíveis para o agente.
Selecione Aprovisionar no painel Ciclo de Vida do Teams Toolkit.
O agente declarativo terá acesso aos conteúdos do OneDrive e do SharePoint para gerar as respetivas respostas depois de recarregar a página.
Adicionar conteúdo dos conectores do Microsoft Graph
Nesta secção, vai adicionar itens ingeridos por um conector do Microsoft Graph aos conhecimentos disponíveis para o agente.
Abra o
appPackage/declarativeAgent.jsonficheiro e atualize acapabilitiesmatriz para o seguinte valor, substituindopolicieslocalpor um ID de conector do Microsoft Graph válido na sua organização do Microsoft 365. Para obter mais informações sobre como localizar IDs de conectores do Microsoft Graph, veja Obter IDs de capacidades para o manifesto declarativo do agente."capabilities": [ { "name": "WebSearch" }, { "name": "OneDriveAndSharePoint", "items_by_url": [ { "url": "https://contoso.sharepoint.com/sites/ProductSupport" } ] }, { "name": "GraphConnectors", "connections": [ { "connection_id": "policieslocal" } ] } ]Para obter mais informações, veja Objeto de conectores do Microsoft Graph.
Observação
- Não especificar a
connectionsmatriz fará com que todos os conteúdos dos conectores do Microsoft Graph na sua organização do Microsoft 365 que estejam disponíveis para o utilizador com sessão iniciada estejam disponíveis para o agente.
- Não especificar a
Selecione Aprovisionar no painel Ciclo de Vida do Teams Toolkit.
O agente declarativo terá acesso ao conteúdo dos conectores do Microsoft Graph para gerar as respetivas respostas depois de recarregar a página.
Adicionar plug-ins de API
Nesta secção, vai adicionar um plug-in de API ao agente. Os plug-ins adicionam novas capacidades ao agente ao permitir que o agente interaja com uma API REST.
Pode adicionar um plug-in ao seu agente com o Teams Toolkit ou a extensão Visual Studio Code Kiota.
Antes de começar, crie um ficheiro com o nome posts-api.yml e adicione o código a partir do documento Descrição openAPI da API de Publicações.
Selecione Adicionar Plug-in no painel Desenvolvimento do Teams Toolkit.
Selecione Iniciar com um Documento de Descrição de OpenAPI.
Selecione Procurar e navegue para o
posts-api.ymlficheiro.Selecione todas as APIs disponíveis e, em seguida, selecione OK.
Selecione manifest.json.
Reveja o aviso na caixa de diálogo. Quando estiver pronto para continuar, selecione Adicionar.
Selecione Aprovisionar no painel Ciclo de Vida do Teams Toolkit.
O agente declarativo terá acesso ao conteúdo do plug-in para gerar as respetivas respostas depois de recarregar a página.
Documento de descrição openAPI da API de publicações
A seguinte descrição do OpenAPI destina-se à API JSONPlaceHolder, uma API REST online gratuita que pode utilizar sempre que precisar de alguns dados falsos.
openapi: '3.0.2'
info:
title: Posts API
version: '1.0'
servers:
- url: https://jsonplaceholder.typicode.com/
components:
schemas:
post:
type: object
properties:
userId:
type: integer
description: The ID of the user that authored the post.
id:
type: integer
title:
type: string
body:
type: string
user:
type: object
properties:
id:
type: integer
name:
type: string
username:
type: string
email:
type: string
phone:
type: string
website:
type: string
address:
$ref: '#/components/schemas/address'
company:
$ref: '#/components/schemas/company'
address:
type: object
properties:
street:
type: string
suite:
type: string
city:
type: string
zipcode:
type: string
geo:
$ref: '#/components/schemas/coordinates'
coordinates:
type: object
properties:
lat:
type: string
description: The latitude of the location
lng:
type: string
description: The longitude of the location
company:
type: object
properties:
name:
type: string
catchPhrase:
type: string
bs:
type: string
parameters:
post-id:
name: post-id
in: path
description: 'key: id of post'
required: true
style: simple
schema:
type: integer
user-id:
name: user-id
in: path
description: 'key: id of user'
required: true
style: simple
schema:
type: integer
paths:
/posts:
get:
description: Get posts
operationId: GetPosts
parameters:
- name: userId
in: query
description: Filter results by user ID
required: false
style: form
schema:
type: integer
maxItems: 1
- name: title
in: query
description: Filter results by title
required: false
style: form
schema:
type: string
maxItems: 1
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/post'
post:
description: 'Create post'
operationId: CreatePost
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/post'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/post'
/posts/{post-id}:
get:
description: 'Get post by ID'
operationId: GetPostById
parameters:
- $ref: '#/components/parameters/post-id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/post'
patch:
description: 'Update post'
operationId: UpdatePost
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/post'
parameters:
- $ref: '#/components/parameters/post-id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/post'
delete:
description: 'Delete post'
operationId: DeletePost
parameters:
- $ref: '#/components/parameters/post-id'
responses:
'200':
description: OK
/users:
get:
summary: Get users
description: Returns details about users
operationId: GetUsers
parameters:
- name: name
in: query
description: The user's real name
schema:
type: string
- name: username
in: query
description: The user's login name
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/user'
/users/{user-id}:
get:
description: 'Get user by ID'
operationId: GetUserById
parameters:
- $ref: '#/components/parameters/post-id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/user'
Parabéns!
Concluiu o guia do agente declarativo para Microsoft 365 Copilot. Agora que está familiarizado com as capacidades de um agente declarativo, pode saber mais sobre agentes declarativos nos seguintes artigos.
- Saiba como escrever instruções eficazes para o seu agente.
- Obtenha respostas às perguntas mais frequentes.
- Saiba mais sobre um método alternativo de criação de agentes declarativos com Copilot Studio construtor de agentes.
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.