Escrever instruções efetivas para agentes declarativos

Os agentes declarativos são versões personalizadas de Microsoft 365 Copilot que o ajudam a criar experiências personalizadas ao declarar instruções, ações e conhecimentos específicos. Para escrever instruções eficazes para o seu agente declarativo, considere as seguintes perguntas:

• Qual é o objetivo que o agente tem de alcançar?
• Que fluxos de trabalho prevê que os seus utilizadores finais estão a passar?
  • Existe lógica de negócio que gostaria de incorporar?
  • Existe uma experiência de utilizador final pretendida que pretenda incorporar?
• Para cada fluxo de trabalho, pode fornecer instruções passo a passo para o agente?

Se o agente declarativo também tiver plug-ins de API como ações, o documento OpenAPI do plug-in ajuda o agente a compreender quaisquer instruções que se refuem à API. Para obter mais informações, veja How to make an OpenAPI document effective in extending Copilot (Como tornar um documento OpenAPI eficaz na expansão do Copilot).

Esta documentação de orientação aplica-se a programadores e criadores que estejam a utilizar o Toolkit de Agentes do Microsoft 365 (uma evolução do Teams Toolkit) ou Copilot Studio para criar agentes declarativos.

Componentes de instrução

Um conjunto bem estruturado de instruções garante que o agente compreende a sua função, as tarefas que deve realizar e como interagir com os utilizadores. Seguem-se os componentes main de instruções declarativas do agente:

• Objetivo
• Diretrizes gerais, incluindo direções gerais, tom e restrições
• Capacidades

Além disso, quando relevante, as instruções incluem:

• Instruções passo a passo
• Processamento de erros e limitações
• Comentários e iteração
• Exemplos de interação
• Termos não padrão
• Seguimento e fecho

O diagrama seguinte mostra os componentes principais das instruções declarativas do agente.

Melhores práticas para instruções do agente

Utilizar linguagem acionável clara

• Concentre-se no que Copilot deve fazer, não no que evitar.
• Utilize verbos precisos e específicos, como "perguntar", "procurar", "enviar", "marcar" ou "utilizar".
• Complemente com exemplos para minimizar a ambiguidade.
• Defina quaisquer termos que não sejam padrão ou exclusivos para a organização nas instruções.

Criar fluxos de trabalho passo a passo com transições

Divida os fluxos de trabalho em passos modulares, inequívocos e sem conflitos. Cada passo deve incluir:

• Objetivo: o objetivo do passo.
• Ação: o que o agente deve fazer e quais as ferramentas a utilizar.
• Transição: desmarque critérios para avançar para o passo seguinte ou terminar o fluxo de trabalho.

Instruções de estrutura em Markdown

Para dar ênfase e clareza à ordem dos passos, utilize Markdown.

• Utilize #, ##e ### para cabeçalhos de secção.
• Utilize - para listas não ordenadas e 1. para listas numeradas. Utilize listas não ordenadas, a menos que a ordem dos passos seja importante, nesse caso, utilize listas numeradas.
• Realce os nomes da ferramenta ou do sistema (por exemplo, Jira, ServiceNow, Teams) com a utilização de acentos anteriores (''''').
• Faça com que as instruções críticas a negrito com **.

Referenciar explicitamente capacidades, conhecimentos e ações

Chame claramente a atenção para os nomes das ações, capacidades ou origens de conhecimento envolvidas em cada passo.

• Ações: por exemplo, "Utilizar Jira para obter bilhetes".
• Conhecimentos do conector Copilot: por exemplo, "Utilizar ServiceNow KB para artigos de ajuda".
• Conhecimentos do SharePoint: por exemplo, "Referenciar documentos internos do SharePoint ou do OneDrive".
• Email mensagens: por exemplo, "Verificar e-mails de utilizador para obter informações relevantes".
• Mensagens do Teams: por exemplo, "Histórico de conversas do Teams de Pesquisa".
• Interpretador de código: por exemplo, "Utilizar interpretador de código para gerar gráficos de barras ou circulares".
• Pessoas conhecimento: por exemplo, "Utilizar o conhecimento das pessoas para obter o e-mail do utilizador".

Fornecer exemplos

Os exemplos ajudam o agente a compreender as instruções.

• Para cenários simples, não precisa de dar exemplos.
• Para cenários complexos, os agentes declarativos funcionam melhor com pedidos com poucas imagens. Ou seja, dê mais do que um exemplo para ilustrar diferentes aspetos ou casos extremos.

Evitar falhas de pedidos comuns

Tenha em atenção estas armadilhas e as suas soluções.

• Utilização de ferramentas excessivamente ansiosa
  • Problema: o modelo chama as ferramentas sem as entradas necessárias.
  • Solução: Adicione a instrução "Chame apenas a ferramenta se estiverem disponíveis entradas necessárias; caso contrário, pergunte ao utilizador."
• Sintagma repetitiva
  • Problema: o modelo reutiliza o texto literal da expressão de exemplo.
  • Solução: Incentive respostas variadas e linguagem natural. Considere adicionar mais do que um exemplo em vez de apenas um (aviso de poucos tiros). Experimente remover o exemplo para guardar em tokens.
• Explicações verbosas
  • Problema: o modelo explica demasiado ou fornece formatação excessiva.
  • Solução: para limitar a verbosidade ou formatação, adicione restrições e exemplos concisos.

Iterar as suas instruções

O desenvolvimento de instruções para agentes declarativos é frequentemente iterativo e consiste normalmente nos seguintes passos.

1. Crie instruções e iniciadores de conversação para o seu agente seguindo a estrutura e o formato descritos neste artigo.
2. Publique o agente. As práticas responsáveis de IA (RAI) estão integradas no processo de validação para garantir que os agentes mantêm padrões éticos. Para saber mais, confira:
   • Validação rai
   • Ferramentas e práticas RAI
   • Aplicações com tecnologia de inteligência artificial
3. Teste o agente.
   1. Para confirmar que o agente traz valor acrescentado ao responder, compare os resultados com Microsoft 365 Copilot.
   2. Verifique se os iniciadores de conversação funcionam conforme esperado com a documentação de orientação passo a passo.
   3. Verifique se o agente age de acordo com as instruções fornecidas.
   4. Confirme que os pedidos de utilizador fora dos iniciadores de conversação são processados adequadamente.
4. Itere as instruções para explorar se pode melhorar ainda mais o resultado.
   • Modifique as instruções para alterar o comportamento do agente.
   • Experimente adicionar conhecimentos como pesquisa na Web, OneDrive/SharePoint ou conectores de Microsoft 365 Copilot (anteriormente conectores do Microsoft Graph), se necessário, utilizando o Toolkit de Agentes ou Copilot Studio.

O diagrama seguinte ilustra o processo iterativo para criar e refinar instruções declarativas do agente.

Instruções de exemplo

As seguintes instruções de exemplo destinam-se a um agente que pode ajudar a resolver problemas comuns de TI.

# OBJECTIVE
Guide users through issue resolution by gathering information, checking outages, narrowing down solutions, and creating tickets if needed. Ensure the interaction is focused, friendly, and efficient.

# RESPONSE RULES
- Ask one clarifying question at a time, only when needed.
- Present information as concise bullet points or tables.
- Avoid overwhelming users with details or options.
- Always confirm before moving to the next step or ending.
- Use tools only if data is sufficient; otherwise, ask for missing info.

# WORKFLOW

## Step 1: Gather Basic Details
- **Goal:** Identify the user's issue.
- **Action:**
  - Proceed if the description is clear.
  - If unclear, ask a single, focused clarifying question.
    - Example:
      User: "Issue accessing a portal."
      Assistant: "Which portal?"
- **Transition:** Once clear, proceed to Step 2.

## Step 2: Check for Ongoing Outages
- **Goal:** Rule out known outages.
- **Action:**
  - Query `ServiceNow` for current outages.
  - If an outage is found:
    - Share details and ETA.
    - Ask: "Is your issue unrelated? If yes, I can help further."
    - If yes, go to Step 3. If no/no response, end politely.
  - If none, inform the user and go to Step 3.

## Step 3: Narrow Down Resolution
- **Goal:** Find best-fit solutions from the knowledge base.
- **Action:**
  - Search `ServiceNow KB` for related articles.
  - **Iterative narrowing:** Don't list all results. Instead:
    - Ask clarifying questions based on article differences.
    - Eliminate irrelevant options with user responses.
    - Repeat until the best solution is found.
  - Provide step-by-step fix instructions.
  - Confirm: "Did this help? If not, I can go deeper or create a ticket."
    - If more info is provided, repeat this step.
    - If ticket needed, go to Step 4.
    - If resolved/no response, end politely.

## Step 4: Create Support Ticket
- **Goal:** Log unresolved issues.
- **Action:**
  1. Map **category** and **subcategory** from the `sys_choice` SharePoint file.
     - Use only valid pairs. Leave blank if not clear.
  2. Fetch user's UPN (email) with the people capability.
  3. Fill the ticket with:
     - Caller ID (email)
     - Category, Subcategory (if mapped)
     - Description, attempted steps, error codes, metadata
- **Transition:** Confirm ticket creation and next steps.

# OUTPUT FORMATTING RULES
- Use bullets for actions, lists, next steps.
- Use tables for structured data where UI allows.
- Avoid long paragraphs; keep responses skimmable.
- Always confirm before ending or submitting tickets.

# EXAMPLES

## Valid Example
**User:** "I can't connect to VPN."
**Assistant:**
- "Are you seeing a specific error?"
  (User: "DNS server not responding.")
- "Let me check for outages."
  (No outage.)
- "No outages. Searching knowledge base…"
  (Finds articles. Asks: "Are you on office Wi-Fi or home?")
  (User: "Home.")
- "Try resetting your DNS settings. Here's how…"
- "Did this help? If not, I can create a support ticket."

## Invalid Example
- "Here are 15 articles I found…" *(Overwhelms the user)*
- "I'm raising a ticket" *(without confirming details)*

Conteúdo relacionado

• Para obter um ficheiro de manifesto de exemplo para um agente declarativo criado com o Toolkit de Agentes, veja Exemplo de manifesto de agente declarativo.
• Para obter informações sobre como utilizar Copilot Studio para criar agentes declarativos, consulte Expandir com agentes.
• Para obter informações sobre os requisitos de validação para agentes declarativos, veja Diretrizes de validação para agentes.