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.
Um agente declarativo fornece uma experiência de conversação orientada por objetivos com a tecnologia Microsoft 365 Copilot. Você define seu propósito, instruções, conhecimento e ações. Este guia mostra como criar um agente declarativo usando o TypeSpec e o Microsoft 365 Agents Toolkit.
Observação
O agente criado 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, consulte Microsoft 365 Copilot licenças de desenvolvedor.
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.
Observação
Os agentes declarativos baseados em Microsoft 365 Copilot são agora suportados no Word e PowerPoint.
Pré-requisitos
- Um inquilino do Microsoft 365 onde pode carregar aplicações personalizadas. O aprovisionamento falha se o carregamento da aplicação personalizada não estiver ativado. Para ativar o carregamento personalizado da aplicação, consulte os requisitos do Microsoft 365 Agents Toolkit. Para obter informações sobre o ambiente de desenvolvimento e as opções de licenciamento, consulte Ambiente de desenvolvimento do Copilot.
Para concluir os passos descritos neste artigo, necessita dos seguintes recursos:
Observação
As capturas de ecrã e referências de interface de utilizador neste artigo utilizam uma versão de lançamento do Microsoft 365 Agents Toolkit. As versões de pré-lançamento poderão ser diferentes da interface de utilizador apresentada.
Familiarize-se com os seguintes padrões e diretrizes para agentes declarativos para Microsoft 365 Copilot:
- Padrões de conformidade, desempenho, segurança e experiência do usuário descritos nas diretrizes de validação da Loja Teams.
Criar um agente declarativo
Comece criando um agente declarativo básico.
Abra Visual Studio Code.
Selecione Microsoft 365 Agents Toolkit > Criar um novo agente/aplicativo.
Selecione Agente declarativo.
Selecione Iniciar com TypeSpec para Microsoft 365 Copilot para criar um agente declarativo básico.
Selecione Pasta padrão para armazenar a pasta raiz do projeto no local padrão.
Digite
My Agentcomo o Nome do Aplicativo e pressione Enter.Na nova janela de Visual Studio Code que é aberta, selecione Microsoft 365 Agents Toolkit. No painel Ciclo de Vida , selecione Provisão.
Testar o agente
Aceda à aplicação Copilot em https://m365.cloud.microsoft/chat.
Junto ao botão Novo Chat, selecione o ícone de gaveta de conversas.
Selecione o agente declarativo My Agent.
Introduza uma pergunta para o seu agente declarativo para vê-la em ação.
Adicionar instruções
As instruções mudam a forma como um agente se comporta.
Abra o
main.tspficheiro e substitua o@instructionsdecorador pelo seguinte código.@instructions(""" 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. """)O processo de provisionamento insere o conteúdo desse decorador na
instructionspropriedade no manifesto do agente. Para obter mais informações, consulte Objeto de manifesto do agente declarativo.Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.
O agente declarativo usa suas instruções atualizadas depois que você recarrega a página.
Adicionar iniciadores de conversação
Os iniciadores de conversação são sugestões que o Copilot apresenta aos utilizadores para mostrar como podem começar a utilizar o agente declarativo.
Abra o
main.tsparquivo e substitua o decorador comentado@conversationStarterpelo seguinte conteúdo:@conversationStarter(#{ title: "Getting started", text: "How can I get started with Agents Toolkit?" }) @conversationStarter(#{ title: "Getting Help", text: "How can I get help with Agents Toolkit?" })Para obter mais informações, consulte Objeto de iniciadores de conversação.
Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.
Os iniciadores de conversação atualizados estão disponíveis no seu agente declarativo depois de atualizar a página.
Adicionar conteúdo da Web
A capacidade de pesquisa na Web permite que os agentes utilizem o índice de pesquisa no Bing para responder aos pedidos do utilizador.
Abra o
main.tsparquivo e adicione oWebSearchrecurso noMyAgentnamespace com o conteúdo a seguir.namespace MyAgent { op webSearch is AgentCapabilities.WebSearch<Sites = [ { url: "https://learn.microsoft.com", }, ]>; }Para obter mais informações, consulte Objeto de pesquisa na Web.
Observação
Se você não especificar a
Sitesmatriz, o agente poderá acessar todo o conteúdo da Web.Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.
O agente declarativo pode acessar o conteúdo da Web para gerar suas respostas depois que você recarregar a página.
Adicionar conteúdo do OneDrive e SharePoint
A funcionalidade do SharePoint permite que o agente utilize o OneDrive e o conteúdo do SharePoint como conhecimento.
Abra o
main.tspficheiro e adicione aOneDriveAndSharePointfuncionalidade noMyAgentespaço de nomes com o seguinte valor, substituindo-ahttps://contoso.sharepoint.com/sites/ProductSupportpelo URL de um site do SharePoint na sua organização do Microsoft 365.namespace MyAgent { // Omitted for brevity op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [ { url: "https://contoso.sharepoint.com/sites/ProductSupport" } ]>; // Omitted for brevity }Para obter mais informações, consulte OneDrive e objeto do SharePoint.
Observação
- Os URLs devem ser o caminho completo para os 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. Clique com o botão direito do rato no ficheiro ou pasta e selecione Detalhes. Navegue até Caminho e selecione o ícone de cópia.
- Se não especificar a
ItemsByUrlmatriz (ou a matriz alternativaItemsBySharePointIds), o agente pode aceder a todos os conteúdos do OneDrive e do SharePoint na sua organização do Microsoft 365 aos quais o utilizador com sessão iniciada pode aceder.
Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.
O agente declarativo tem acesso aos conteúdos do OneDrive e SharePoint para gerar as respetivas respostas após recarregar a página.
Adicionar mensagens do Teams
A funcionalidade de mensagens do Teams permite ao agente utilizar os canais do Teams, a equipa e o chat de reunião como conhecimento.
Abra o
main.tspficheiro e adicione aTeamsMessagesfuncionalidade noMyAgentespaço de nomes com o seguinte valor, substituindohttps://teams.microsoft.com/l/team/...por um canal do Teams ou URL de equipa da sua organização.namespace MyAgent { // Omitted for brevity op teamsMessages is AgentCapabilities.TeamsMessages<TeamsMessagesByUrl = [ { url: "https://teams.microsoft.com/l/team/...", } ]>; // Omitted for brevity }Para obter mais informações, consulte Objeto de mensagens do Microsoft Teams.
Observação
- O URL na
urlpropriedade tem de ser uma ligação bem formada para uma conversa do Teams, conversa de equipa ou conversa de reunião. - Se não especificar a
TeamsMessagesByUrlmatriz, o agente pode aceder a todos os canais do Teams, equipas, reuniões, conversas individuais e conversas de grupo na sua organização do Microsoft 365 aos quais o utilizador autenticado pode aceder.
- O URL na
Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.
O agente declarativo pode aceder aos dados do Teams para gerar as suas respostas após recarregar a página.
Acrescente conhecimentos às pessoas
A capacidade de pessoas permite-lhe definir o seu agente no sentido de responder a perguntas sobre indivíduos numa organização.
Abra o
main.tsparquivo e adicione oPeoplerecurso noMyAgentnamespace com o conteúdo a seguir.namespace MyAgent { // Omitted for brevity op people is AgentCapabilities.People; // Omitted for brevity }Para obter mais informações, consulte People objeto.
Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.
O agente declarativo tem acesso ao conhecimento das pessoas depois que você recarrega a página.
Adicionar conhecimento de email
O recurso de email permite que você defina o escopo do seu agente para usar o email da caixa de correio do usuário ou de uma caixa de correio compartilhada como uma fonte de conhecimento.
Abra o
main.tsparquivo e adicione oEmailrecurso noMyAgentnamespace com o conteúdo a seguir.namespace MyAgent { // Omitted for brevity op email is AgentCapabilities.Email<Folders = [ { folder_id: "Inbox", } ]>; // Omitted for brevity }Para obter mais informações, consulte Objeto de Email.
Observação
- Este exemplo acessa o usuário da caixa de correio do agente. Para acessar uma caixa de correio compartilhada, adicione a propriedade opcional
shared_mailboxdefinida ao endereço de email da caixa de correio compartilhada. - A
Foldersmatriz limita o acesso da caixa de correio a pastas específicas. Para acessar a caixa de correio inteira, omita afoldersmatriz.
- Este exemplo acessa o usuário da caixa de correio do agente. Para acessar uma caixa de correio compartilhada, adicione a propriedade opcional
Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.
O agente declarativo tem acesso ao conhecimento de email depois que você recarrega a página.
Adicionar gerador de imagens
O recurso de gerador de imagens permite que os agentes gerem imagens com base em solicitações do usuário.
Abra o
main.tsparquivo e adicione oGraphicArtrecurso noMyAgentnamespace com o conteúdo a seguir.namespace MyAgent { // Omitted for brevity op graphicArt is AgentCapabilities.GraphicArt; // Omitted for brevity }Para obter mais informações, consulte Objeto de arte gráfica.
Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.
O agente declarativo pode gerar imagens depois que você recarregar a página.
Adicionar interpretador de código
O recurso interpretador de código é uma ferramenta avançada projetada para resolver tarefas complexas por meio do código Python.
Abra o
main.tsparquivo e adicione oCodeInterpreterrecurso noMyAgentnamespace com o conteúdo a seguir.namespace MyAgent { // Omitted for brevity op codeInterpreter is AgentCapabilities.CodeInterpreter; // Omitted for brevity }Para obter mais informações, consulte Objeto interpretador de código.
Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.
O agente declarativo tem o recurso interpretador de código depois que você recarrega a página.
Adicionar conteúdo de conectores do Copilot
Adicione itens ingeridos por um conector do Copilot ao conhecimento disponível para o agente.
Abra o
main.tsparquivo e adicione aGraphConnectorsfuncionalidade noMyAgentnamespace com o valor a seguir, substituindopolicieslocalpor uma ID válida do conector do Copilot em sua organização do Microsoft 365. Para obter mais informações sobre como encontrar IDs de conector do Copilot, consulte Recuperar IDs de funcionalidade para o manifesto do agente declarativo.namespace MyAgent { // Omitted for brevity op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [ { connectionId: "policieslocal", } ]>; // Omitted for brevity }Para obter mais informações, consulte Objeto de conectores do Copilot.
Observação
Se você não especificar a
Connectionsmatriz, o agente obterá conteúdo de todos os conectores do Copilot em sua organização do Microsoft 365 que o usuário conectado pode acessar.Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.
O agente declarativo pode acessar o conteúdo dos conectores do Copilot para gerar suas respostas depois que você recarregar a página.
Concluído
Você concluiu o guia do agente declarativo para o Microsoft 365 Copilot. Agora que você já está familiarizado com o uso do TypeSpec para criar um agente declarativo, saiba mais nos artigos a seguir.
- Saiba como escrever instruções eficazes para seu agente.
- Teste seu agente com o modo de desenvolvedor para verificar se e como o orquestrador do Copilot seleciona suas fontes de conhecimento para uso em resposta a prompts fornecidos. Para obter mais informações, consulte Testar e depurar agentes no Microsoft 365 Agents Toolkit usando o modo de desenvolvedor.
- Obtenha respostas para perguntas frequentes.
- Saiba mais sobre outras maneiras de criar agentes declarativos: sem código no Construtor de Agentes ou com pouco código no Copilot Studio.