Escrever instruções efetivas para agentes declarativos com plug-ins de API

Os agentes declarativos adaptam Microsoft 365 Copilot para satisfazer as necessidades específicas de uma organização. Quando cria agentes declarativos com o Toolkit de Agentes do Microsoft 365 (uma evolução do Teams Toolkit), pode adicionar competências ao seu agente através de plug-ins de API. Os plug-ins de API permitem que o agente consulte e interaja com os dados de uma organização através de APIs.

Este artigo descreve a arquitetura do agente e fornece as melhores práticas para escrever instruções para agentes declarativos que incluem plug-ins de API.

Componentes principais de agentes declarativos com plug-ins de API

Os agentes declarativos que chamam plug-ins de API incluem vários componentes que garantem uma integração e funcionalidade eficazes. Compreender esta arquitetura irá ajudá-lo a conceber o seu agente de forma eficaz. A arquitetura inclui os seguintes componentes:

• Manifesto da aplicação – descreve como a sua aplicação está configurada e referencia o manifesto declarativo do agente.
• Manifesto de agente declarativo – define a configuração do agente, incluindo instruções, capacidades, iniciadores de conversação e ações. Referencia o manifesto do plug-in.
• Manifesto de plug-in – descreve a configuração do plug-in, incluindo as funções disponíveis e uma referência à especificação OpenAPI.
• Especificação de OpenAPI – fornece definições detalhadas de pontos finais de API, incluindo caminhos, parâmetros, formatos de pedido e resposta e autenticação.

Em conjunto, estes ficheiros definem o comportamento do agente e como interage com a API subjacente.

Para obter mais informações sobre plug-ins de API, veja:

• Plug-ins de API para Microsoft 365 Copilot
• Como tornar um documento OpenAPI eficaz na expansão das capacidades do Copilot

Mapeamento de funções no manifesto de plug-in

No manifesto de plug-in, cada função tem de mapear para um operationId correspondente na especificação OpenAPI. Isto garante que, quando o agente invoca uma função (por exemplo, createTask), o agente sabe qual o ponto final da API a chamar.

Os exemplos seguintes mostram o mapeamento no manifesto do plug-in e a função mapeada na especificação OpenAPI.

"functions": [
  {
    "name": "createTask",
    "description": "Creates a new task in the specified task list."
  }
]

paths:
  /me/todo/lists/{listId}/tasks:
    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task in the specified task list.
      parameters:

Melhores práticas para instruções do agente

Escrever instruções eficazes é essencial para garantir que os agentes declarativos com plug-ins de API são bem-sucedidos. Para otimizar o agente, aplique o mapeamento de funções correto, utilize o encadeamento para permitir interações mais ricas e teste e refine iterativamente o comportamento do agente.

Aplique as seguintes melhores práticas ao escrever instruções para agentes declarativos com plug-ins de API:

• Evite instruções ambíguas ou negativas. Instruções contrastantes ou negativas podem introduzir ambiguidade e confundir o modelo. Concentre-se na definição de casos de utilização válidos com exemplos positivos. Se for importante distinguir entre consultas válidas e inválidas, forneça critérios claros e exemplos que definam a resposta esperada do agente para cada uma.
• Utilizar exemplos Forneça exemplos claros para orientar o comportamento do agente. Por exemplo:

Entrada do utilizador: Qual é o tempo em Praga? Chamada do agente: getWeather(location="Praga") Entrada do utilizador: "Preciso de um guarda-chuva amanhã?" Chamada do agente: getWeather(location=user_location, forecast="tomorrow")

• Reveja e teste as instruções. Teste as instruções em vários cenários para verificar se o agente faz as chamadas de função corretas. Se ao testar descobrir que o agente invoca funções inesperadamente, reveja a descrição da função na especificação OpenAPI e esclareça as instruções do agente para melhorar o mapeamento de intenções.

• Instruções de conceção para conversações multiturno. Quando integrar plug-ins de API, estruture as instruções para que o agente processe conversações multiturno.

Por exemplo, se a função precisar de vários parâmetros, além de definir os parâmetros necessários na especificação OpenAPI, instrua o agente a recolher todos os parâmetros antes de efetuar a chamada à API. Isto garante que o agente recolhe todas as informações necessárias numa sequência lógica.

O exemplo seguinte mostra como instruir um agente meteorológico para conversações multiturno e o fluxo do agente que resulta.

Instruções para o agente

Fluxo do agente

Se o utilizador perguntar sobre a meteorologia: - Peça a localização ao utilizador. - Peça ao utilizador o dia da previsão. - Peça ao utilizador o sistema de unidades. - Chame getWeather apenas quando recolher todos os valores.

Utilizador: "Qual é o tempo?" Agente: "Qual é a sua localização?" Utilizador: "Londres" Agente: "Prefere as informações meteorológicas em Unidades Métricas ou Imperiais?" Utilizador: "Métrica" Agente: "Precisa da meteorologia para hoje ou previsão para amanhã?" Utilizador: "Today" Agent: "I will marcar the weather for London for today" Agent calls: getWeather(location="London", forecast="today", system="Metric")

Para obter as melhores práticas gerais para instruções do agente, veja Escrever instruções efetivas.

Chamadas da função encadeamento em plug-ins de API

As chamadas de funções de encadeamento permitem que agentes declarativos combinem múltiplas ações de API num fluxo totalmente integrado. As secções seguintes descrevem padrões comuns e como escrever instruções para cada um.

A função encadear chama com saída como parâmetro de entrada

Utilize o resultado de uma chamada à API como entrada para outra. Isto é útil quando o resultado da primeira função é necessário para executar a segunda função. Isto pode ser compatível com plug-ins.

No exemplo seguinte, um agente declarativo com a API de Meteorologia e a API to-do cria uma tarefa a fazer com dados da previsão meteorológica.

Instruções para o agente	Fluxo do agente
Para obter a meteorologia, utilize sempre a ação getWeather e, em seguida, crie uma tarefa com o título "temperatura em" e adicione a localização e a temperatura mencionadas na meteorologia ao título da tarefa.	Utilizador: "Obter a meteorologia em Praga" Agente: Chamadas getWeather (localização="Praga", previsão="hoje") Agente: Utiliza os dados da primeira chamada para criar uma tarefa a fazer createTask (título ="{saída meteorológica}")

Encadear com base no histórico de conversações dentro de um agente

Quando utiliza o encadeamento com base no histórico de conversações, o agente utiliza respostas anteriores para processar ações de seguimento. Esta abordagem utiliza o histórico de conversações para manter o contexto.

No exemplo seguinte, um agente elimina uma tarefa pelo nome.

Instruções para o agente	Fluxo do agente
1. Quando o utilizador pedir para listar todas as tarefas, chame getTasks para obter a lista de tarefas com título e ID. 2. Depois de listar as tarefas, se o utilizador pedir para eliminar uma tarefa, utilize o ID da resposta para chamar deleteTask.	Utilizador: "Mostrar todas as tarefas na pasta Tarefas?" Agente: alls getTasks (folderId="Tasks") e apresenta todas as tarefas com IDs. Utilizador: "Eliminar tarefas do TaskMaster Pro" Agente: utiliza as informações do histórico de conversações para localizar o ID da tarefa e elimina a tarefa ao chamar deleteTask.

Encadear com conhecimentos do SharePoint

O encadeamento de chamadas à API permite que um agente combine origens de conhecimento e ações para criar fluxos de trabalho mais complexos.

No exemplo seguinte, um agente obtém o projeto status dados do SharePoint e cria tarefas correspondentes no Microsoft To-Do para controlo.

Instruções para o agente	Fluxo do agente
- Para obter os estados do projeto, utilize ProjectDeadlines de conhecimento do SharePoint. - Crie sempre uma tarefa para cada projeto com status atualização para o título.	Utilizador: "Pode fornecer uma atualização sobre a status de todos os projetos?" Agente: Extrai status dados do projeto do SharePoint e, em seguida, utiliza createTask para gerar uma tarefa a fazer para cada projeto.

Encadeamento com interpretador de código

Também é possível encadear chamadas à API e integrar capacidades adicionais, como um interpretador de código. Isto permite que um agente processe dinamicamente saídas de API para permitir fluxos de trabalho mais avançados.

No exemplo seguinte, um agente cria um gráfico com base nos dados em tarefas de tarefas a fazer.

Instruções para o agente	Fluxo do agente
Quando o utilizador pedir para listar todas as tarefas, chame getTasks para obter a lista de tarefas com título e ID, também desenhe o gráfico para a saída.	Utilizador: "Obter todas as tarefas em Tarefas" Agente: chama os getTasks (folderId="Tasks") e apresenta todas as tarefas com IDs. Agente: Chama o interpretador de código para iniciar a geração do gráfico com base no resultado da primeira chamada.

Este exemplo também executa várias ações ao mesmo tempo. Isto é útil para iniciar uma série de ações relacionadas que não requerem múltiplas entradas de utilizador.

Conteúdo relacionado

• Criar um agente declarativo com Visual Studio Code
• Plug-ins de API para Microsoft 365 Copilot