Escreva instruções eficazes para agentes declarativos

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

• Qual objetivo seu agente deve atingir?
• Quais fluxos de trabalho você imagina que seus usuários finais passarão?
  • Existe lógica de negócios que você deseja incorporar?
  • Existe uma experiência desejada para o usuário final que você deseja incorporar?
• Para cada fluxo de trabalho, você 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 ajudará o agente a entender todas as instruções referentes à API. Para obter mais informações, consulte Como tornar um documento OpenAPI eficaz na extensão do Copilot.

Essas diretrizes se aplicam a desenvolvedores e criadores que usam o Agent Builder no Microsoft 365 Copilot ou noMicrosoft 365 Agents Toolkit para criar agentes declarativos. Para obter mais informações sobre como escrever instruções para agentes do Copilot Studio, consulte Configurar instruções de alta qualidade para orquestração generativa.

Componentes de instrução

Um conjunto bem estruturado de instruções garante que o agente entenda seu papel, as tarefas que deve executar e como interagir com os usuários. Os principais componentes das instruções do agente declarativo são:

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

Quando relevante, inclua também os seguintes componentes nas instruções:

• Instruções passo a passo
• Tratamento de erros e limitações
• Comentários e iteração
• Exemplos de interação
• Termos não padronizados
• Acompanhamento e encerramento

O diagrama a seguir mostra os principais componentes das instruções do agente declarativo.

Práticas recomendadas para instruções de agente

Use linguagem clara e acionável

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

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

Divida os fluxos de trabalho em etapas modulares, inequívocas e não conflitantes. Cada etapa deve incluir:

• Meta: a finalidade da etapa.
• Ação: O que o agente deve fazer e quais ferramentas usar.
• Transição: Critérios claros para passar para a próxima etapa ou encerrar o fluxo de trabalho.

Use uma estrutura rígida

A estrutura é um dos sinais mais fortes usados para interpretar a intenção:

• Use seções para agrupar tarefas relacionadas em categorias lógicas, sem implicar sequência.
• Use marcadores para tarefas paralelas que podem ser concluídas independentemente. Evite numeração que possa introduzir ordem não intencional.
• Use etapas para ações que devem ocorrer em uma sequência necessária e reserve-as apenas para fluxos de trabalho verdadeiros.

Tornar as tarefas atômicas

Divida as instruções de multiação em unidades claramente separadas. Essa abordagem reduz a ambiguidade e impede que o modelo mescle ou reinterprete tarefas.

• Em vez de: Extraia métricas e resuma descobertas.
• Use etapas separadas:
  1. Extraia métricas.
  2. Resuma as descobertas.

Sempre especifique o tom, o detalhamento e o formato de saída

Se você não especificar o tom e o nível de detalhe, o modelo de linguagem poderá inferir esses atributos, o que pode levar a um comportamento inconsistente entre os modelos. Por exemplo, especifique:

• Tom: profissional e conciso.
• Saída: Três marcadores por seção.
• Retorne apenas o formato solicitado; Sem explicações.

Instruções de estrutura em Markdown

Para fornecer ênfase e clareza sobre a ordem das etapas, use Markdown.

• Use #, ##e ### para cabeçalhos de seção.
• Use - para listas não ordenadas e 1. para listas numeradas. Use listas não ordenadas, a menos que a ordem das etapas seja importante, nesse caso, use listas numeradas.
• Realce nomes de ferramentas ou sistemas (por exemplo, Jira, ServiceNow, Teams) usando acentos graves (''''').
• Torne as instruções críticas em negrito usando **.

Títulos claros e estruturas de lista consistentes ajudam o modelo a entender a hierarquia pretendida. Evite misturar tipos de lista de maneiras que possam introduzir interpretações não intencionais.

Forneça vocabulário de domínio

Defina termos especializados, fórmulas, acrônimos e linguagem específica do conjunto de dados. Essa definição evita inferências incorretas e garante uma interpretação consistente.

Referenciar explicitamente capacidades, conhecimentos e ações

Destaque claramente os nomes das ações, funcionalidades ou fontes de conhecimento envolvidas em cada etapa.

• Ações: Por exemplo, "Use Jira para buscar tíquetes".
• Conhecimento do conector do Copilot: por exemplo, "Use ServiceNow KB para artigos de ajuda".
• Conhecimento do SharePoint: Por exemplo, "Referenciar documentos internos do SharePoint ou do OneDrive".
• Email messages: Por exemplo, "verificar emails de usuários para obter informações relevantes".
• Mensagens do Teams: Por exemplo, "Pesquisar histórico de chats do Teams".
• Interpretador de código: por exemplo, "Usar o interpretador de código para gerar gráficos de barras ou de pizza".
• People knowledge: Por exemplo, "Use people knowledge para buscar e-mails do usuário".

Respostas de base para fontes de conhecimento configuradas

Os modelos de linguagem têm conhecimento interno de seus dados de treinamento. Em muitos cenários de agente, você deseja que o agente dependa apenas das fontes de conhecimento configuradas, não do conhecimento interno do modelo. Essa abordagem garante que as respostas sejam precisas, consistentes e rastreáveis aos dados organizacionais.

A maneira recomendada de impedir que o modelo se baseie em seu conhecimento interno é definir a discourage_model_knowledge propriedade como true no objeto do manifesto special_instructions do agente. Quando ativado, o agente faz o possível para evitar gerar respostas do conhecimento do modelo e depende das fontes de conhecimento configuradas. Para obter mais informações, consulte Objeto de instruções especiais.

Forneça exemplos

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

• Para cenários simples, você não precisa dar exemplos.
• Para cenários complexos, os agentes declarativos funcionam melhor com a solicitação de poucos tiros. Ou seja, dê mais de um exemplo para ilustrar diferentes aspectos ou casos extremos.

Controlar o raciocínio por meio de fraseado

Sua redação sinaliza quanto raciocínio você deseja que o modelo aplique.

Raciocínio profundo

Para aumentar a profundidade:

• Use verbos de raciocínio explícitos (analisar, derivar, avaliar, justificar).
• Adicione dicas de meta-raciocínio (pense passo a passo, reflita, verifique a lógica).
• Estruture as tarefas em várias etapas dependentes.

Use deep reasoning. Break the problem into steps, analyze each step, evaluate alternatives, and justify the final decision. Reflect before answering.
Task: Determine the optimal 3-year migration strategy given constraints A, B, and C.

Para detectar quando o raciocínio profundo foi selecionado:

Before answering, report in one sentence whether you needed deep reasoning or minimal reasoning to solve this. Then provide the final answer only.

Raciocínio moderado (equilibrado)

Para equilibrar o raciocínio:

• Peça uma explicação concisa, mas estruturada.
• Forneça restrições claras, mas não pistas de meta-raciocínio.

Provide a concise but structured explanation. Include a short summary, 3 key drivers, and a final recommendation. No step-by-step reasoning required.
Task: Explain the tradeoffs between solution X and Y.

Raciocínio rápido e mínimo

Para reduzir a profundidade:

• Brevidade do sinal. Especifique uma resposta curta e rápida; sem raciocínio / explicação.
• Evite verbos analíticos e estruturas de várias etapas.
• Use uma frase imperativa de intenção única e fase única.

Short answer only. No reasoning or explanation. Provide the final result only.
Task: Extract the product name and renewal date from this paragraph.

Evitar falhas comuns de prompt

Esteja ciente das seguintes armadilhas e suas soluções para evitar falhas comuns.

• Uso excessivo de ferramentas
  • Problema: O modelo chama ferramentas sem entradas necessárias.
  • Solução: Adicionar instrução "Chame a ferramenta apenas se as entradas necessárias estiverem disponíveis; caso contrário, pergunte ao usuário."
• Frases repetitivas
  • Problema: O modelo reutiliza o fraseado de exemplo literalmente.
  • Solução: Incentive respostas variadas e linguagem natural. Considere adicionar mais de um exemplo em vez de apenas um (solicitação de poucos tiros). Experimente remover o exemplo para economizar tokens.
• Explicações detalhadas
  • Problema: O modelo explica em excesso ou fornece formatação excessiva.
  • Solução: Para limitar o detalhamento ou a formatação, adicione restrições e exemplos concisos.

Adicionar uma etapa final de autoavaliação

Uma etapa de auto-marcação reforça a integridade e garante que o agente verifique o alinhamento com suas instruções antes de responder. Por exemplo: antes de finalizar, confirme se todos os itens da Seção A aparecem no resumo.

Aplicar um cabeçalho de estabilização quando necessário

Quando um agente mostrar sinais de desvio de inferência ou reordenação de etapa, adicione um cabeçalho curto que instrua o modelo a interpretar as instruções literalmente e evitar inferências. Para obter mais informações, consulte Padrão 8: aplicar um cabeçalho de execução literal para estabilidade imediata.

Iterar de acordo com suas instruções

O desenvolvimento de instruções para agentes declarativos geralmente é um processo iterativo. Normalmente, consiste nas seguintes etapas:

1. Crie instruções e iniciadores de conversa para seu agente seguindo a estrutura e o formato descritos neste artigo.
2. Publique seu agente. As práticas de IA responsável (RAI) são integradas ao processo de validação para garantir que os agentes mantenham os padrões éticos. Para saber mais, confira:
   • Validação de RAI
   • Ferramentas e práticas de IA
   • Aplicativos alimentados por inteligência artificial
3. Teste seu agente.
   1. Para confirmar se o agente traz valor agregado ao responder, compare os resultados com o Microsoft 365 Copilot.
   2. Verifique se os iniciadores de conversa funcionam conforme o esperado com as diretrizes passo a passo.
   3. Verifique se o agente age de acordo com as instruções fornecidas.
   4. Confirme se os prompts do usuário fora dos iniciadores de conversa são tratados adequadamente.
4. Itere as instruções para explorar se você pode melhorar ainda mais a saída.
   • Modifique as instruções para alterar o comportamento do agente.
   • Tente adicionar conhecimento, como pesquisa na Web, OneDrive/SharePoint ou conectores do Microsoft 365 Copilot, se necessário, usando o Agents Toolkit ou o Copilot Studio.

O diagrama a seguir ilustra o processo iterativo para criar e refinar instruções de agente declarativo.

Instruções de exemplo

As instruções de exemplo a seguir são para 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)*

Modelos de instrução e padrões de design

Esta seção fornece padrões e modelos que você pode adicionar às instruções do agente declarativo. Os exemplos mostrados não são prescritivos. Use-os como ponto de partida e adapte-os aos requisitos do seu caso de uso.

Padrão 1: Converter solicitações multitarefa ambíguas em fluxos de trabalho determinísticos

Usando esse padrão, você remove a ambiguidade definindo etapas atômicas, fórmulas explícitas e validação necessária. Essa abordagem garante um comportamento estável e repetível em todas as versões do modelo.

## Task: Metrics and ROI (Deterministic)

### Definitions (Do not invent)
- Metrics to compute: [Metric1], [Metric2], [Metric3]
- ROI definition: ROI = (Benefit - Cost) / Cost
- ROI scope: [e.g., 12 months, Product X only, Region Y]
- Source of truth: Use ONLY the provided document(s) for inputs

### Steps (Sequential — do not reorder)
Step 1: Locate inputs for [Metric1-3] in the document. Quote the section/table name where each input came from.
Step 2: Compute [Metric1-3] exactly as defined above. If any input is missing, stop and ask ONE question listing what's missing.
Step 3: Compute ROI using the ROI definition above. Do not substitute other ROI formulas.
Step 4: Output ONLY the table in the format below.

### Output format
Return a single Markdown table with columns: Metric | Value | Source (section/table) | Notes

### Final check (Self-evaluation)
Before finalizing: confirm every metric has (a) a value, (b) a source, and (c) no assumptions. If assumptions exist, stop and ask the user.

Padrão 2: Estrutura paralela correta versus sequencial

Usando esse padrão, você garante que o modelo separe a lógica paralela e sequencial. O modelo executa fluxos de trabalho corretamente sem adicionar ou reordenar etapas.

Section A — Extract Data
- Extract pricing changes.
- Extract margin changes.
- Extract sentiment themes.

Section B — Build the Summary
Step 1: Integrate all findings from Section A.
Step 2: Produce the 2 page call prep summary.

Padrão 3: regras de decisão explícitas

Usando esse padrão, você adiciona regras explícitas "se/então" que impedem a interpretação não intencional do modelo e impõem resultados determinísticos. Essa abordagem impede que o modelo de linguagem tente resolver a lógica condicional ambígua por conta própria, o que pode resultar em ramificações combinadas ("fazer ambos") ou na seleção do caminho condicional errado.

Read the product report.
Check category performance.
If performance is stable or improving, write the summary section.
If performance declines or anomalies are detected, write the risks/issues section.

Padrão 4: contrato de saída

Os contratos de saída fornecem forma, estrutura, tom e conteúdo permitido, garantindo consistência. Sem restrições de saída explícitas, seu agente pode produzir explicações excessivamente longas, respostas excessivamente concisas ou alternar de forma imprevisível entre as versões.

Boa precisão:

Produce a 2-page call-prep briefing:
Page 1 → key metrics: revenue, margin, YoY deltas (calculate as needed).
Page 2 → top themes, risks, opportunities, customer signals.
Tone: Professional. Reasoning: none unless calculation required.

Contrato de saída:

## Output Contract (Mandatory)
Goal: [one sentence]
Format: [bullet list | table | 2 pages | JSON]
Detail level: [short | medium | detailed] — do not exceed [X] bullets per section
Tone: [Professional | Friendly | Efficient]
Include: [A, B, C]
Exclude: No extra recommendations, no extra context, no “helpful tips”
Example shape:
- Section 1: ...
- Section 2: ...

Use esse padrão quando o resultado precisar seguir:

• Um formato preciso (marcadores, tabela, JSON, resumo de várias páginas).
• Um nível especificado de detalhes (curto, médio, detalhado).
• Um modelo de conformidade, auditoria ou voltado para o cliente.
• Um processo empresarial que exige formatação consistente entre as equipes.

Padrão 5: estrutura de Markdown limpa

O Markdown limpo e intencional garante que o modelo possa analisar suas instruções de maneira confiável. Listas mal aninhadas, cabeçalhos pouco claros ou formatação inconsistente causam etapas mescladas, hierarquia não intencional ou seções recolhidas.

## Section A — Extract Data
- Extract pricing changes.
- Extract margin changes.
- Extract sentiment themes.

## Section B — Build the Summary (Sequential)
**Step 1:** Integrate findings from Section A.
**Step 2:** Produce the 2 page call prep summary.

Padrão 6: Portão de autoavaliação

Ao adicionar uma etapa de auto-marcação explícita, você incentiva o modelo a validar a integridade, verificar o alinhamento com as instruções e corrigir omissões antes de responder. Essa etapa aumenta a consistência e a confiabilidade.

## Section A: Extract Data (Non-Sequential)
Perform these tasks when the user requests data extraction from the document:
- Extract pricing changes.
- Extract margin changes.
- Extract sentiment themes.
Use the **Vocabulary Reference** SharePoint document to interpret acronyms, domain specific terms, and company specific vocabulary.

## Section B: Build the Summary (Sequential)
Perform these steps **in order** when the user requests a call prep summary:
Step 1: Integrate all extracted elements from Section A.
Step 2: Produce a clear, well structured 2 page call prep summary.

## Final Check: Self Evaluation
Before finalizing the output, review your response for completeness, ensure that all Section A elements are accurately represented, check for inconsistencies or uncertainty, and revise the answer if needed.

Padrão 7: Raciocínio do modo automático de direção

Dicas de raciocínio explícito dão controle sobre quanto pensamento o modelo aplica. Sem essas diretrizes, seu agente pode explicar demais respostas simples ou decisões complexas.

Dispare o raciocínio profundo:

Use deep reasoning. Break the problem into steps, analyze each step, evaluate alternatives, and justify the final decision. Reflect before answering.
Task: Determine the optimal 3-year migration strategy given constraints A, B, and C.

Forçar raciocínio rápido e mínimo:

Short answer only. No reasoning or explanation. Provide the final result only.
Task: Extract the product name and renewal date from this paragraph.

Use esse padrão quando seu fluxo de trabalho exigir:

• Raciocínio mais profundo (planejamento, avaliação de alternativas, lógica de várias etapas).
• Recuperação ou extração rápida com explicação mínima.
• Alternar entre resumos de alto nível e análises mais profundas.
• Profundidade consistente em vários agentes ou casos de uso.

Padrão 8: aplicar um cabeçalho de execução literal para estabilidade imediata

Um cabeçalho de execução literal ajuda a estabilizar temporariamente um agente existente. Esse padrão é especialmente útil como uma correção provisória enquanto você atualiza o conjunto de instruções completo.

Always interpret instructions literally.
Never infer intent or fill in missing steps.
Never add context, recommendations, or assumptions.
Follow step order exactly with no optimization.
Respond concisely and only in the requested format.
Do not call tools unless a step explicitly instructs you to do so.

Use esse padrão quando:

• Você observa reordenação, etapas adicionadas ou raciocínio excessivo nas respostas do seu agente.
• Você precisa de uma mitigação rápida de curto prazo antes de aplicar melhorias estruturais mais profundas.
• Você deseja diagnosticar se a ambiguidade de inferência ou instrução está causando o problema.

Padrão 9: avaliar instruções de agente declarativo existentes

Use um prompt de avaliação estruturado para auditar rapidamente um agente existente, identificar pontos fracos específicos e gerar correções precisas.

You are reviewing Data Access (DA) agent instructions for stability.

INPUT
<instructions>
[PASTE CURRENT INSTRUCTIONS]
</instructions>

TASK
Concise audit. Identify ONLY issues and exact fixes.

CHECKS
- Step order: identify ambiguity, missing steps, or merged steps → propose atomic, numbered steps.
- Tool use: identify auto-calls, retries, or tool switching → add "use only in step X; no auto-retry".
- Grounding: detect inference, blending, or citation gaps → add "cite only retrieved; no inference; no cross-document stitching".
- Missing-data handling: if retrieval is empty or conflicting → add "stop and ask the user".
- Verbosity: identify chatty or explanatory output → replace with "return only the requested data/format".
- Contradictions or duplicates: resolve discrepancies; prefer explicit over implied.
- Vague verbs ("verify", "process", "handle", "clean"): replace with precise, observable actions.
- Safety: prohibit step reordering, optimization, or reinterpretation.

OUTPUT (concise)
- Header patch (3–6 lines)
- Top 5 changes (bullet list: "Issue → Fix")
- Example rewrite (≤10 lines) for the riskiest step

Use esse padrão quando:

• Você está auditando um agente existente que se comporta de forma inconsistente.
• Você não tem certeza de quais partes do conjunto de instruções são frágeis ou ambíguas.
• Você deseja um processo de avaliação repetível para vários agentes declarativos em uma organização.
• Você precisa de uma maneira rápida de identificar quais problemas estão relacionados a estruturas ou estilos estilísticos

Conteúdo relacionado

• Exemplo de manifesto de agente declarativo.
• Use o Copilot Studio para criar agentes.
• Diretrizes de validação para agentes.