Práticas recomendadas para criar agentes declarativos

Os agentes declarativos personalizam Microsoft 365 Copilot para cenários de negócios específicos por meio de instruções, fontes de conhecimento e recursos com suporte. Use essas práticas para manter um agente focado, configurar suas ações com segurança e avaliar seu comportamento à medida que evolui.

Comece com uma audiência definida, tarefa do usuário e resultado esperado. Para obter o limite entre o tempo de execução gerenciado e os serviços que você opera, consulte Arquitetura do agente declarativo.

Observação

Este artigo abrange os agentes declarativos, que utilizam o tempo de execução gerido do Copilot. Se estiver a criar um agente de motor personalizado que obtém dados de base do Microsoft 365, siga as melhores práticas, permissões e limitações daAPI de Recuperação. Essa orientação é separada da configuração das fontes de conhecimento de um agente declarativo.

Componentes do agente declarativo

Escolha cada componente para dar suporte às tarefas pretendidas do agente. Siga os limites da ferramenta de criação e do esquema de manifesto selecionados.

Componente Práticas recomendadas
Nome Use um nome distinto que transmita o propósito do agente. O Agent Builder permite até 30 caracteres; O manifesto do agente declarativo permite até 100.
Descrição Resumir as tarefas e o domínio em algumas frases precisas, dentro do limite de 1000 carateres. Mantenha instruções comportamentais detalhadas no campo de instruções.
Instruções Defina o objetivo do agente, as tarefas suportadas, a origem e o uso da ferramenta, o formato de saída e o comportamento de falha dentro do limite de 8.000 caracteres.
Fontes de conhecimento Adicione fontes relevantes para as perguntas pretendidas. Confirme o âmbito, a atualização, as permissões e o licenciamento suportados.
Capacidades incorporadas Ative capacidades como intérprete de código ou gerador de imagens apenas quando suportarem as tarefas pretendidas.
Competências personalizadas (pré-visualização) Utilizar competências para instruções de tarefas modulares, recursos ou scripts. Referenciar habilidades configuradas em um alto nível, em vez de duplicar suas instruções detalhadas.
Ações Use plug-ins MCP ou API para interações suportadas com serviços externos. Descreva o objetivo de cada ferramenta, entradas, saídas e condições de falha.
Sugestões para iniciar conversação Forneça pedidos representativos que demonstrem tarefas suportadas. Não é necessário um número mínimo. Teste cada pedido e siga os limites da ferramenta selecionada.

Melhores práticas para instruções do agente

Use instruções para definir como o agente deve abordar as tarefas pretendidas:

  • Indique o resultado e os limites. Descreva o que o agente ajuda os usuários a realizar, quais informações ele precisa e como ele deve responder a solicitações sem suporte.
  • Torne explícito o uso da fonte e da ferramenta. Identifique que origem, capacidade ou ação configurada se aplica a cada tarefa. Peça entradas em falta em vez de adivinhar.
  • Passos separados da apresentação. Utilize passos de tarefa claros em que a ordem é importante e especifique o tom, a estrutura e o nível de detalhe esperados para as respostas.
  • Planeie informações em falta e falhas. Descreva como lidar com fontes indisponíveis, resultados incompletos, acesso negado e ações malsucedidas sem reivindicar o êxito.
  • Mantenha as instruções separadas do conhecimento. Não coloque instruções comportamentais em documentos do SharePoint ou outras fontes de conhecimento para contornar os limites de instruções. O conteúdo recuperado não é conteúdo de instruções criado pelo fabricante de confiança.

Para obter padrões detalhados, exemplos e orientações sobre alterações de modelo, consulte Escrever instruções eficazes. Para tarefas que combinam conhecimento com chamadas de API, consulte Escrever instruções para agentes com plug-ins de API.

Escolher as fontes de conhecimento certas

Selecione fontes de conhecimento com base nas perguntas que o agente deve responder:

  • Prefira a relevância à quantidade. Origens do âmbito dos ficheiros, sites, chats ou outros conteúdos necessários para a tarefa. Para ficheiros incorporados e do SharePoint, siga Otimizar a obtenção de conteúdos.
  • Faça corresponder a recuperação aos requisitos de recência. Reveja regularmente o conteúdo de origem e a propriedade. A pesquisa na Web com escopo usa conteúdo indexado pelo Bing, não uma consulta direta dos dados subjacentes. Para dados estruturados atuais, avalie uma ação de API ou MCP suportada. Veja Base de pesquisa na Web e conteúdo dinâmico.
  • Confirme o acesso antes de partilhar. Teste com utilizadores que representem o público-alvo e as permissões. Reveja o comportamento da partilha de ficheiros incorporados separadamente do acesso aos ficheiros originais.
  • Verifique o suporte de capacidade e licenciamento. As opções de origens e de controlo do âmbito diferem consoante a ferramenta de criação e a configuração do inquilino. Siga a matriz de suporte da fonte de conhecimento e as orientações de licenciamento.
  • Avalie a fundamentação e não apenas a fluência das respostas. Teste perguntas com respostas conhecidas e marcar que as respostas e citações correspondam às fontes pretendidas. Inclua as perguntas cujas respostas não estão disponíveis.

A adição de fontes, por si só, não impede que o agente use o conhecimento interno do modelo. Quando o cenário exigir respostas baseadas na origem, defina behavior_overrides.special_instructions.discourage_model_knowledge e true reforce a utilização de origem pretendida nas instruções. Este controlo não garante que as respostas utilizem apenas origens configuradas. Continue a avaliar a atribuição da origem e o comportamento quando faltarem provas. Consulte Respostas no terreno a fontes de conhecimento configuradas e a referência de instruções especiais.

Estruture ações seguras

Utilizar ações para interações suportadas com serviços externos e distingui-las das fontes de conhecimento. Um conector Copilot utilizado para a fundamentação não é permutável com uma ferramenta de API ou MCP que altera dados externos.

  • Descreva as operações com precisão. Explique quando uma ferramenta deve ser utilizada, os parâmetros necessários e os resultados e erros esperados. Para APIs REST, siga as orientações do documento OpenAPI.
  • Configure confirmações para a integração. Para plugins API, use a extensão x-openai-isConsequentialOpenAPI, não isConsequential, e marque as operações com efeitos colaterais como consequenciais. Para ferramentas MCP, use readOnlyHint apenas para ferramentas que são somente leitura. Siga as instruções de confirmação para plug-ins MCP e API para as configurações e comportamento suportados.
  • Impor acesso no serviço. Utilize o método de autenticação suportado e valide a autorização e as entradas no serviço externo. As instruções e os pedidos de confirmação não substituem essas verificações.
  • Concepção para falhas e pedidos repetidos. Confirmações de teste negadas, autenticação expirada, entradas inválidas e erros de serviço. Para operações que alteram dados, certifique-se de que as novas tentativas não repetem a alteração inadvertidamente.

Use Planeje dados, privacidade e segurança para identificar os fluxos de dados, permissões e requisitos de supervisão humana para cada ação.

Testar e iterar

Defina o comportamento esperado antes de alterar o agente e mantenha um conjunto repetível de casos de teste. Use a experiência de teste da ferramenta de criação para obter feedback inicial e, em seguida, validar o agente implantado em seus hosts pretendidos.

Área de teste O que verificar
Tarefas com suporte Iniciadores de conversa, frases realistas do usuário e perguntas de acompanhamento produzem os resultados pretendidos.
Informações ausentes ou sem suporte O agente pede as entradas necessárias, explica as evidências indisponíveis e não inventa fatos ou alega que ações malsucedidas foram concluídas.
Fundamento e permissões As respostas e citações correspondem às fontes pretendidas. Teste os usuários com acesso diferente e confirme se as informações restritas não foram expostas.
Ações e falhas Verifique o resultado externo real, bem como a resposta. Confirmações de teste, cancelamentos, falhas de autenticação, erros de serviço e solicitações repetidas.
Experiência do host Teste cada aplicativo com suporte no qual você pretende implantar. Verifique o contexto do documento, a apresentação da resposta e os recursos disponíveis em vez de assumir um comportamento idêntico em todos os aplicativos.
Desempenho e alterações Meça os tempos de resposta e execute novamente os casos de regressão após as alterações nas instruções, conhecimento, ferramentas, habilidades ou comportamento da plataforma.

Inclua usuários que não escreveram as instruções para que os testes capturem frases e suposições inesperadas. Transforme problemas reproduzíveis relatados pelo usuário em casos de regressão.

Para design de caso de teste, asserções e avaliação repetível, consulte Visão geral da avaliação do agente. Para verificações de versão, consulte Validação de IA responsável e Validar e testar seu plug-in.