Escrever instruções efetivas para agentes declarativos

Os agentes declarativos são versões personalizadas do 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 atingir?
• Que fluxos de trabalho prevê que os seus utilizadores finais estão a passar?
  • Existe lógica de negócio que pretenda 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 orientação aplica-se aos programadores e criadores que utilizam o Agent Builder no Microsoft 365 Copilot ou no Microsoft 365 Agents Toolkit para criar agentes declarativos. Para obter mais informações sobre como escrever instruções para Copilot Studio agentes, veja Configurar instruções de alta qualidade para orquestração geradora.

Importante

Microsoft 365 Copilot transições periódicas para versões de GPT mais recentes. Uma vez que estas atualizações são automáticas, espere algumas alterações comportamentais ao longo do tempo e esteja preparado para adaptar pedidos e instruções onde a precisão é importante. A recente mudança do GPT 5.0 para o GPT 5.1 foi uma mudança maior de uma interpretação literal das instruções para uma abordagem de raciocínio adaptável mais intenção. Esta mudança pode afetar a forma como o seu agente declarativo compreende e responde às suas instruções, particularmente em cenários estruturados ou passo a passo. Para obter mais informações, veja Alterações de modelo no GPT 5.1+ para 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. Os principais componentes das instruções declarativas do agente são:

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

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

• 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.

Utilizar estrutura estrita

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

• Utilize secções para agrupar tarefas relacionadas em categorias lógicas, sem implicar sequência.
• Utilize marcas de lista para tarefas paralelas que podem ser concluídas de forma independente. Evite numeração que possa introduzir uma ordem não intencional.
• Utilize os passos para ações que têm de ocorrer numa sequência necessária e reserve-as apenas para fluxos de trabalho verdadeiros.

Tornar as tarefas atómicas

Divida as instruções de várias secções em unidades claramente separadas. Esta abordagem reduz a ambiguidade e impede que o modelo intercale ou reinterprete tarefas.

• Em vez de: extrair métricas e resumir resultados.
• Utilize passos separados:
  1. Extrair métricas.
  2. Resumir as conclusões.

Especificar sempre o tom, a verbosidade e o formato de saída

Se não especificar o tom e o nível de detalhe, o modelo de linguagem poderá inferir estes atributos, o que pode levar a comportamentos inconsistentes entre modelos. Por exemplo, especifique:

• Tom: profissional e conciso.
• Saída: três pontos de marca por secção.
• Devolver apenas o formato pedido; sem explicações.

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 utilizem **.

Limpar cabeçalhos e estruturas de lista consistentes ajudam o modelo a compreender a hierarquia pretendida. Evite misturar tipos de lista de formas que possam introduzir interpretações não intencionais.

Fornecer vocabulário de domínio

Defina termos especializados, fórmulas, acrónimos e linguagem específica do conjunto de dados. Esta definição impede a inferência incorreta e garante uma interpretação consistente.

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".
• People 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.

Controlar o raciocínio através do sintagma

A sua redação indica o raciocínio que pretende que o modelo aplique.

Raciocínio profundo

Para aumentar a profundidade:

• Utilize verbos de raciocínio explícitos (analisar, derivar, avaliar, justificar).
• Adicione ajudas de meta-raciocínio (pense passo a passo, reflita, verifique a lógica).
• Estruturar tarefas em vários passos 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 detetar quando foi selecionado um raciocínio profundo:

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

Esta abordagem funciona porque o sistema de encaminhamento do GPT-5 inclui a deteção de tokens de raciocínio.

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ários passos.
• Utilize sintagma imperativa de intenção ú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 de pedidos comuns

Tenha em atenção as seguintes armadilhas e as suas soluções para evitar falhas comuns.

• Utilização da ferramenta Overeager
  • 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 sobreexplina ou fornece formatação excessiva.
  • Solução: para limitar a verbosidade ou formatação, adicione restrições e exemplos concisos.

Adicionar um passo final de autoaval avaliação

Um passo de auto-marcar reforça a conclusão e garante que o agente verifica o alinhamento com as suas instruções antes de responder. Por exemplo: antes de finalizar, confirme que todos os itens da Secção A aparecem no resumo.

Aplicar um cabeçalho estabilizador quando necessário

Quando um agente mostra sinais de desfasamento de inferência ou reordenação de passos, especialmente após uma atualização de modelo, adicione um cabeçalho curto que instrui o modelo a interpretar as instruções literalmente e evitar inferência. Para obter mais informações, veja Alterações de modelo no GPT 5.1+ para agentes declarativos.

Iterar as suas instruções

O desenvolvimento de instruções para agentes declarativos é, muitas vezes, um processo iterativo. Normalmente, consiste 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, se necessário, com 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 instruções de exemplo seguintes destinam-se a um agente que pode ajudar a resolve 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 estrutura

Esta secção fornece padrões e modelos que pode adicionar às instruções declarativas do agente. Os exemplos apresentados não são prescritivos. Utilize-os como ponto de partida e adapte-os aos requisitos do seu caso de utilização.

Padrão 1: Converter pedidos multitarefa ambíguos em fluxos de trabalho deterministas

Ao utilizar este padrão, remove a ambiguidade ao definir passos atómicos, fórmulas explícitas e validação necessária. Esta 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: Correção paralela versus estrutura sequencial

Ao utilizar este padrão, certifique-se de que o modelo separa a lógica paralela e sequencial. O modelo executa os fluxos de trabalho corretamente sem adicionar ou reordenar passos.

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

Ao utilizar este padrão, adiciona regras explícitas se/então que impedem a interpretação não intencional do modelo e impõem resultados deterministas. Esta abordagem impede que o modelo de linguagem tente resolve lógica condicional ambígua por si só, o que pode resultar em ramos combinados ("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 explícitas de saída, o agente pode produzir explicações demasiado longas, respostas excessivamente terse ou alternar imprevisivelmente entre 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: ...

Utilize este padrão quando a saída tiver de seguir:

• Um formato preciso (marcas de lista, tabela, JSON, resumo de várias páginas).
• Um nível de detalhe especificado (curto, médio, detalhado).
• Um modelo de conformidade, auditoria ou destinado ao cliente.
• Um processo de negócio que requer formatação consistente entre equipas.

Padrão 5: Limpar a estrutura de Markdown

Markdown limpo e intencional garante que o modelo pode analisar as suas instruções de forma fiável. Listas mal aninhadas, cabeçalhos pouco claros ou formatação inconsistente causam passos intercalados, hierarquia não intencional ou secções fechadas.

## 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: Porta de autoaval avaliação

Ao adicionar um passo de auto-marcar explícito, incentiva o modelo a validar a conclusão, a verificar o alinhamento com as instruções e a corrigir omissões antes de responder. Este passo aumenta a consistência e a fiabilidade.

## 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 modelo automático de direção

As ajudas explícitas de raciocínio dão-lhe controlo sobre a quantidade de ideias que o modelo aplica. Sem esta documentação de orientação, o agente poderá explicar demasiado as respostas simples ou subplicar decisões complexas.

Acionar um 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.

Utilize este padrão quando o fluxo de trabalho exigir:

• Raciocínio mais profundo (planeamento, avaliação de alternativas, lógica de vários passos).
• Obtenção rápida ou extração com explicação mínima.
• Alternar entre resumos de alto nível e análise mais profunda.
• Profundidade consistente em vários agentes ou casos de utilização.

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, especialmente após uma alteração de modelo. Este padrão é especialmente útil como uma correção provisória enquanto atualiza o conjunto de instruções completo. Para obter mais informações, veja Alterações de modelo no GPT 5.1+ para agentes declarativos.

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.

Utilize este padrão quando:

• Observa a reordenação, os passos adicionados ou o raciocínio excessivo após a atualização para o GPT 5.1+.
• Precisa de uma mitigação rápida a curto prazo antes de aplicar melhorias estruturais mais profundas.
• Quer diagnosticar se a ambiguidade da inferência ou da instrução está a causar o problema.

Padrão 9: Avaliar e migrar instruções do agente declarativo existente

Utilize um pedido 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 5.1 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

Utilize este padrão quando:

• Está a migrar um agente existente do GPT 5.0 para o GPT 5.1 ou posterior.
• Não tem a certeza de que partes do conjunto de instruções são frágeis ou ambíguas.
• Quer um processo de avaliação repetível para vários agentes declarativos numa organização.
• Precisa de uma forma rápida de identificar quais são os problemas estruturais, estilísticos ou relacionados com a segurança.

Conteúdo relacionado

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