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.

Para obter informações gerais, veja Agentes declarativos para Microsoft 365 Copilot.

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

• 0 minutos restantes

Comece por criar um agente declarativo básico.

1. Abra o Visual Studio Code.

2. Selecione Teams Toolkit > Criar uma Nova Aplicação.

   

3. Selecione Agente.

   

4. Selecione Agente Declarativo.

5. Selecione Sem plug-in para criar um agente declarativo básico.

6. Selecione Pasta predefinida para armazenar a pasta raiz do projeto na localização predefinida.

7. Introduza My Agent como o Nome da Aplicação e prima Enter.

8. Na nova janela Visual Studio Code que é aberta, selecione Teams Toolkit e, em seguida, selecione Aprovisionar no painel Ciclo de Vida.

   

Testar o agente

1. Navegue para a aplicação Copilot com o URL https://www.microsoft365.com/chat.

2. Junto ao botão Novo Chat , selecione o ícone da gaveta de conversação.

3. Selecione o agente declarativo O Meu Agente.

   

4. 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

• 0 minutos restantes

Nesta secção, vai adicionar instruções ao agente para alterar o seu comportamento.

1. Abra o appPackage/instructions.txt ficheiro 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 instructions propriedade no manifesto do agente durante o aprovisionamento. Para obter mais informações, veja Objeto de manifesto do agente declarativo.

2. 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

• 0 minutos restantes

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.

1. Abra o appPackage/declarativeAgent.json ficheiro e adicione a conversation_starters matriz 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.

2. 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

• 0 minutos restantes

Nesta secção, vai adicionar a capacidade de pesquisar na Web ao agente.

1. Abra o appPackage/declarativeAgent.json ficheiro e adicione a capabilities matriz com o seguinte conteúdo.

   "capabilities": [
       {
           "name": "WebSearch"
       }
   ]
   

   Para obter mais informações, veja Objeto de pesquisa na Web.

2. 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

• 0 minutos restantes

Nesta secção, vai adicionar os conteúdos de um site do SharePoint aos conhecimentos disponíveis para o agente.

1. Abra o appPackage/declarativeAgent.json ficheiro e atualize a capabilities matriz para o seguinte valor, substituindo https://contoso.sharepoint.com/sites/ProductSupport por 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_url matriz (ou a matriz alternativa items_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.

2. 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

• 0 minutos restantes

Nesta secção, vai adicionar itens ingeridos por um conector do Microsoft Graph aos conhecimentos disponíveis para o agente.

1. Abra o appPackage/declarativeAgent.json ficheiro e atualize a capabilities matriz para o seguinte valor, substituindo policieslocal por 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 connections matriz 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.

2. 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

• 0 minutos restantes

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.

"actions": [
    {
        "id": "postsPlugin",
        "file": "postsapi-apiplugin.json"
    }
]

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!

• 100% concluído!

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.