Práticas recomendadas para a criação de agentes declarativos

Os agentes declarativos são assistentes de IA que personalizam o Microsoft 365 Copilot para cenários de negócios específicos por meio de instruções personalizadas, fontes de conhecimento e ações. Este artigo resume as práticas recomendadas para a criação de agentes declarativos adaptados às suas necessidades comerciais exclusivas.

Componentes do agente declarativo

Um agente declarativo consiste em vários componentes. É importante aplicar as melhores práticas ao seu design para cada componente do seu agente. A tabela a seguir fornece as práticas recomendadas para cada componente do agente.

Componente Descrição Prática recomendada
Nome O nome de exibição do agente. Certifique-se de que seu nome de exibição transmita a finalidade do seu agente para a descoberta do usuário no Agent Store. O nome deve atender aos limites de caracteres com base na ferramenta de desenvolvimento:
  • Microsoft 365 Copilot – 30 caracteres
  • Microsoft 365 Agents Toolkit - 100 caracteres
Para obter informações sobre os requisitos de nome do aplicativo, consulte os requisitos de validação da Loja do Teams.
Descrição Um breve resumo do que o agente faz. Indique claramente a finalidade e o domínio do agente. Por exemplo: "Use o Agente de Projeto no Microsoft 365 Copilot para pesquisar e resumir seus documentos de projeto". Mencione que o agente funciona no Microsoft 365 Copilot. Mantenha-o conciso (algumas frases ≤1.000 caracteres) e limite as instruções ao que o agente deve fazer, e não ao que não deve fazer.
Instruções As principais diretrizes comportamentais para o agente. As instruções são o principal prompt que orienta as respostas do agente. Forneça até 8.000 caracteres de orientação detalhada sobre como o agente deve se comportar, quais tarefas ele pode realizar e regras ou estilos que deve seguir. Para obter mais informações, consulte Escrever instruções efetivas.
Fontes de conhecimento Conteúdo corporativo ou dados externos que o agente pode usar para fundamentar suas respostas. Configurado na seção Conhecimento no Microsoft 365 Copilot ou no manifesto. Adicione apenas o conhecimento relevante de que o agente precisa. Você pode adicionar sites, pastas ou arquivos do SharePoint; chats específicos do Teams; Email do Outlook; e URLs da Web pública como fontes.

Ao adicionar arquivos, menos é mais: o Copilot tem melhor desempenho quando os documentos são razoavelmente dimensionados e focados. Certifique-se também de que o conteúdo esteja atualizado e preciso, pois o agente usa o conteúdo em suas fontes de conhecimento em suas respostas.
Recursos Recursos opcionais de IA integrados (como o Interpretador de Código e o Gerador de Imagens). Os recursos dão ao seu agente habilidades extras, como executar código Python ou gerar imagens de prompts. Adicione apenas recursos que se alinhem aos objetivos do seu agente. Por exemplo, o interpretador de código pode ser ótimo para um agente de análise de dados.
Ações (APIs/plug-ins) Ações externas que o agente pode executar por meio de plug-ins de API (conectores do Copilot, APIs da Web personalizadas e conectores do Power Platform), definidos no manifesto do agente. Se o seu agente precisar consultar sistemas externos ou realizar transações, você poderá integrar plug-ins baseados em API. Cada ação corresponde a uma operação de API.

Projete ações com cuidado: forneça um documento OpenAPI com descrições claras da operação e adicione essas ações no manifesto do agente.

Para cada ação, observe se ela é consequente (ou seja, grava ou altera dados externos). Qualquer ação do tipo criar/atualizar/excluir deve ter isConsequential: true. As consultas somente leitura podem ser marcadas como não consequentes.
Inícios de conversa (prompts de exemplo) Exemplos de consultas que um usuário pode fazer ao agente, mostrados como sugestões ou dicas de ajuda. Inclua um mínimo de três prompts de amostra que reflitam os principais recursos do seu agente. Isso ajuda os usuários a entender como usar o agente. Por exemplo:
  • Rascunhe um e-mail para a pessoa sobre o assunto.
  • Compare e contraste as propostas em arquivo e arquivo.
  • Crie um gráfico de linhas para mostrar as tendências de vendas nos últimos seis meses.

Práticas recomendadas para instruções de agente

As instruções fornecidas determinam o comportamento do agente e o ajudam a fornecer respostas precisas e úteis. Instruções mal elaboradas podem levar a ambiguidade, resultados inconsistentes ou ações não intencionais. Em geral, aplique as práticas recomendadas definidas no artigo Escreva instruções efetivas para agentes declarativos ao desenvolver seu agente.

A tabela a seguir fornece informações sobre como você pode planejar, testar e iterar para aprimorar o comportamento do seu agente.

Área de foco Orientação Objetivo
Estratégia de instrução Defina claramente a função e os objetivos do agente. Planeje cenários comuns e extremos. Dê ao agente flexibilidade suficiente para agir, mas defina limites para orientar o comportamento Ajuda os agentes a responder de forma adequada e consistente em diferentes situações.
Inteligência contextual Ajuste as instruções com base em onde e como o agente será usado, como no Word, Teams ou Outlook. Considere as funções do usuário e as necessidades urgentes. Garante que as instruções permaneçam relevantes e eficazes nos aplicativos em que são usadas.
Iteração colaborativa Trabalhe com colegas de equipe multifuncionais, como gerentes de produto, redatores e engenheiros, para revisar e melhorar as instruções. Teste como as instruções se comportam em aplicativos diferentes e mantenha um registro das alterações. Melhora a qualidade da instrução por meio do trabalho em equipe e ajuda a manter a consistência ao longo do tempo.
Diagnóstico de instrução Para entender como as instruções são executadas, use ferramentas como logs e comentários do usuário. Procure padrões em que as respostas do agente não sejam úteis e revise as instruções para melhorar as respostas. Ajuda a melhorar as instruções com base no uso real e na experiência do usuário.
Arquitetura de instrução Divida as instruções em partes menores e reutilizáveis. Use tags e modelos para se manter organizado e aplicar padrões consistentes entre os agentes. Facilita o gerenciamento de instruções e a reutilização delas em vários agentes e cenários.

Para obter mais informações e orientações específicas para criar instruções de agente, consulte Escrever instruções efetivas para agentes declarativos.

Escolha as fontes de conhecimento certas

Você pode fundamentar seus agentes declarativos em conhecimento público e organizacional – como conteúdo do SharePoint, dados de usuários como emails e chats e sites públicos.

Lembre-se das seguintes considerações principais ao escolher fontes de conhecimento para seu agente:

  • Relevância sobre quantidade: Seja seletivo sobre o conhecimento que você adiciona. Considere se a fonte ajudará o agente a responder os tipos de perguntas que você espera que os usuários façam.

  • Use o SharePoint e conectores para dados estruturados: Para um conhecimento mais estático ou estruturado, o SharePoint é ideal. Se você tiver uma base de dados de conhecimento em PDF ou documentos do Office, hospede-os em um site do SharePoint e adicione esse site como fonte. Se você precisar de outros sistemas (como registros de banco de dados ou dados de CRM), veja se existe um conector Copilot para eles ou adicione um plug-in de API.

  • Considerações sobre licenciamento e acesso: Alguns recursos de conhecimento exigem que o usuário tenha uma licença do Microsoft 365 Copilot. Lembre-se disso se você planeja compartilhar o agente. Se alguém sem uma licença do Copilot tentar usá-lo, essas fontes de conhecimento pessoais não funcionarão para eles. Além disso, as permissões são importantes: o agente só pode recuperar o conteúdo ao qual o usuário tem acesso.

  • Atualização e manutenção de dados: O conhecimento do agente sobre fontes adicionadas é atualizado ao longo do tempo. Revise e atualize periodicamente as fontes de conhecimento.

  • Escopo dos chats da equipe: Se adicionar conversas de equipes, você terá duas opções: todos os chats/reuniões de equipes ou opções específicas. Geralmente, adicionar tópicos de chat específicos produz resultados mais direcionados e menos ruído. Por exemplo, fundamentar um agente no histórico de um canal de projeto específico, em vez de vasculhar todos os chats que você já teve, o ajudará a responder a perguntas específicas do projeto com mais precisão.

  • Use o SharePoint e conectores para dados estruturados: Para um conhecimento mais estático ou estruturado, o SharePoint é ideal. Se você tiver uma base de dados de conhecimento em PDF ou documentos do Office, hospede-os em um site do SharePoint e adicione esse site como fonte. Se você precisar de outros sistemas, como registros de banco de dados ou dados de CRM, veja se existe um conector Copilot para eles ou adicione um plug-in de API.

  • Desencorajar o conhecimento do modelo: A adição de fontes de conhecimento por si só não impede que o modelo se baseie em seu conhecimento de treinamento interno. Para garantir que o agente dependa apenas de suas fontes configuradas, defina a discourage_model_knowledge propriedade como true no objeto do manifesto special_instructions do agente. Quando habilitado, o agente faz o possível para evitar usar o conhecimento do modelo em suas respostas. Para obter mais informações, consulte Objeto de instruções especiais. Você também pode reforçar isso em suas instruções; para obter mais informações, consulte Respostas de solo para fontes de conhecimento configuradas.

  • Testar respostas com e sem conhecimento: Teste algumas consultas antes e depois de adicionar fontes de conhecimento. Por exemplo, fazer uma pergunta que deva ser respondida em um documento específico. Sem o documento, o agente luta ou gera informações falsas? Depois de adicionar o documento, o agente encontra a resposta? Se perceber que o agente ainda não está usando as informações, talvez seja necessário ajustar suas instruções. Ou, se o agente estiver usando demais uma fonte de conhecimento, considere remover essa fonte ou refinar as instruções para usá-la apenas no contexto.

Fundamentar agentes de mecanismo personalizados com a API de recuperação

Se você criar um agente de mecanismo personalizado ou um aplicativo de conhecimento personalizado que baseie as respostas em dados do Microsoft 365, a API de recuperação do Microsoft 365 Copilot fornecerá RAN (Geração Aumentada de Recuperação) em conectores do SharePoint, OneDrive e Copilot sem copiar ou reindexar seu conteúdo. Aplique as seguintes práticas recomendadas ao aterrar um agente com a API de recuperação:

  • Evite a saída de dados recuperando no local: A API de recuperação retorna partes de texto relevantes do índice híbrido que alimenta o Microsoft 365 Copilot, para que você não precise exportar, duplicar ou reindexar seus dados organizacionais em um armazenamento separado. A recuperação de dados no local preserva os controles de segurança e conformidade existentes. Para obter mais informações, consulte Gerenciar riscos de conformidade e segurança.

  • Recuperação de escopo com QL por palavra-chave (KQL): use o parâmetro para recuperar o filterExpression escopo antes da execução da consulta, por exemplo, filtrar por caminho do site, tipo de arquivo, autor ou intervalo de datas, para que o agente se baseie apenas em fontes aprovadas. Por padrão, nenhum escopo é aplicado. Valide seu KQL antes de chamar a API: se o filterExpression tiver sintaxe incorreta, a consulta será executada sem escopo em vez de falhar. Para obter mais informações, consulte Práticas recomendadas e a referência filterExpression.

  • Conte com o modelo de permissão do Microsoft 365 e conceda acesso com privilégios mínimos: A API de recuperação respeita as permissões do Microsoft 365, portanto, um usuário só recebe resultados do conteúdo que já tem permissão para acessar. Conceda ao seu aplicativo apenas as permissões necessárias: Files. Read.All e Sites.Read.All para SharePoint e OneDrive e ExternalItem.Read.All para conectores do Copilot. Para obter mais informações, consulte Limitações conhecidas.

Testar e iterar

Mesmo depois de seguir todas as práticas recomendadas e diretrizes de design, teste minuciosamente seu agente para verificar se ele funciona conforme o esperado. Aplique as seguintes práticas recomendadas para testar e iterar em seu agente:

  • Use o chat de teste interno: No painel direito do Construtor de Agentes no Microsoft 365 Copilot, você pode conversar com uma visualização ao vivo do seu agente enquanto o cria. Faça isso com frequência. Experimente todos os seus iniciadores de conversa e prompts de exemplo. Além disso, teste perguntas de ponta, perguntas longas, perguntas irrelevantes e assim por diante, para ver como o agente responde. Se algo estranho acontecer, refine suas instruções ou fontes de conhecimento e teste novamente.

  • Teste em vários aplicativos: Se você tiver acesso à experiência do Microsoft 365 Copilot em aplicativos do Microsoft 365, como Word, Excel, Teams e Outlook, adicione seu agente em cada um desses locais para ver como ele se comporta fora do ambiente de criação. Você pode notar que no Word, por exemplo, certas respostas, como ações sugeridas, se comportam de forma diferente do que no Teams. Detecte essas discrepâncias antecipadamente. Seu agente deve estar funcional em todos os aplicativos do Microsoft 365.

  • Verifique os fluxos de confirmação: Se o seu agente usa funções acionáveis que exigem confirmações, teste totalmente esses loops. Por exemplo, digite uma consulta que dispara a ação, verifique se o texto do prompt de confirmação está claro, selecione Permitir (ou o que quer que o botão diga) e marque o resultado. Além disso, teste a escolha de Cancelar/Negar para ver como o agente reage.

  • Teste de carga (se possível): Como desenvolvedor, você pode não simular facilmente uma carga pesada; No entanto, considere o que acontece se o agente receber várias perguntas rapidamente ou se vários usuários o usarem ao mesmo tempo. Se você tiver um componente de API, use a criação de perfil ou os logs para garantir que seu agente responda sem demora.

  • Teste de par ou usuário: Se puder, peça a um colega para testar o agente. Eles podem perguntar coisas que você não esperava e encontrar lacunas nas instruções ou no conhecimento. Um novo usuário pode usar palavras diferentes às quais o agente também não responde. Também é uma boa maneira de detectar problemas de usabilidade. Por exemplo, se um testador não souber o que perguntar ao seu agente, talvez seja necessário adicionar mais iniciadores de conversa.

  • Valide as saídas para precisão: Como os agentes declarativos geralmente respondem com base em fontes de conhecimento, marque as respostas que ele dá com relação ao material de origem. Se o agente resumir um documento, verifique se o resumo está correto. Se ele citar uma política, verifique se ele citou o detalhe correto. Certifique-se de que, para qualquer consulta factual, o agente prefira as fontes de conhecimento fornecidas.

Conteúdo relacionado

  • Last updated on